%%%==============================================================================
% WinEdt pragmas
% !Mode:: "TeX:EN"
% Default Compile engines:
% !TEX program = pdflatex
% !PDFTeXify ext =  --enable-etex  --restrict-write18
% !PDFLaTeX ext  =  --enable-etex  --restrict-write18
% !BIB program = biber
%%%==============================================================================
%% Copyright 2023-present by Alceu Frigeri
%%
%% This work may be distributed and/or modified under the conditions of
%%
%% * The [LaTeX Project Public License](http://www.latex-project.org/lppl.txt),
%%   version 1.3c (or later), and/or
%% * The [GNU Affero General Public License](https://www.gnu.org/licenses/agpl-3.0.html),
%%   version 3 (or later)
%%
%% This work has the LPPL maintenance status *maintained*.
%%
%% The Current Maintainer of this work is Alceu Frigeri
%%
%% This is version {{1.16}} {2025/10/23}
%%
%% The list of files that compose this work can be found in the README.md file at
%% https://ctan.org/pkg/codedescribe
%%
%%%==============================================================================
%\documentclass[dctools,english]{ufrgscca}
\documentclass{article}
\RequirePackage[verbose,a4paper,marginparwidth=28mm,top=3cm,bottom=1.5cm,hmargin={45mm,25mm},marginparsep=2.5mm,columnsep=10mm,asymmetric]{geometry}
%\usepackage[color scheme = darker]{codedescribe}
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
\usepackage{lmodern}
\usepackage[strict,infograb]{codedescribe}
\usepackage{enumitem}

\RequirePackage[backend=biber]{biblatex}
\addbibresource{codedescribe.bib}

\RequirePackage[hidelinks ,hypertexnames=false]{hyperref}
\begin{document}

%%% TO BE DETERMINED !! \parindent
%%%\setlength\parindent{0pt}

\tstitle{
  author={Alceu Frigeri\footnote{\tsverb{https://github.com/alceu-frigeri/codedescribe}}},
  date={\tsdate},
  title={The codedescribe and codelisting Packages\break Version \PkgInfo{codedescribe}{version}}
  }
  
\begin{typesetabstract}

This package is designed to be as class independent as possible, depending only on \tsobj[pkg]{expl3,scontents,listing,xpeekahead,pifont}. Unlike other packages of the kind, a minimal set of macros/commands/environments is defined: most/all defined commands have an ``object type'' as a \tsobj[key]{keyval} parameter, allowing for an easy expansion mechanism (instead of the usual ``one set of macros/environments'' for each object type).

No assumption is made about page layout (besides ``having a marginpar''),  or underlying macros, so that it can be used with any document class.

\end{typesetabstract}

\tableofcontents

\section{Introduction}


This package aims to document both \tsobj[code]{Document} level (i.e. final user) commands, as well \tsobj[code]{Package/Class} level commands. It's fully implemented using \tsobj[pkg]{expl3} syntax and structures, in special \tsobj[pkg]{l3coffins, l3seq, l3keys}. Besides those \tsobj[pkg]{scontents,listing} packages (see \cite{SCONTENTS} and \cite{listings}) are used to typeset code snippets. The package \tsobj[pkg]{pifont} is needed just to typeset those (open)stars, in case one wants to mark a command as (restricted) expandable.
 
 
No other package/class is needed, any class can be used as the base one, which allows to demonstrate the documented commands with any desired layout.

\tsobj[pkg]{codelisting} defines a few macros to display and demonstrate \LaTeX{} code (using \tsobj[pkg]{listings} and \tsobj[pkg]{scontents}), whilst \tsobj[pkg]{codedescribe} defines a series of macros to display/enumerate macros and environments (somewhat resembling the \tsobj[pkg]{doc3} style).

\subsection{Single versus Multi-column Classes}
This package ``can'' be used with multi-column classes, given that the \tsobj[code]{\linewidth,\columnsep} are defined appropriately. \tsobj{\linewidth} shall defaults to text/column real width, whilst \tsobj{\columnsep}, if needed (2 or more columns) shall be greater than \tsobj{\marginparwidth} plus \tsobj{\marginparsep}.

\subsection{Current Version}
This doc regards to \tsobj[pkg]{codedescribe} version \PkgInfo{codedescribe}{version}~ and \tsobj[pkg]{codelisting} version \PkgInfo{codelisting}{version}. Those two packages are fairly stable, and given the \tsobj[meta]{obj-type} mechanism (see \ref{obj-type-def}) they can be easily extended without changing their interface.

\section{codelisting Package}

It requires two packages: \tsobj[pkg]{listings,scontents},  defines an environment: \tsobj[env]{codestore}, a few commands for listing/demo code: \tsobj[code]{\tscode,\tsmergedcode,\tsdemo,\tsresult,\tsexec} and 2 auxiliary commands: \tsobj{\setcodekeys,\setnewcodekey}.

\subsection{In Memory Code Storage}
Thanks to \tsobj[pkg]{scontents} (\tsobj[pkg]{expl3} based) it's possible to store \LaTeX{} code snippets in a \tsobj[pkg]{expl3} sequence variable.


\begin{codestore}[store-colon]
  %The code will be stored as 'store:A'
  \begin{codestore}[store-env = store:A]
  ...
  \end{codestore}
  
  %Same
  \begin{codestore}[st = store:A]
  ...
  \end{codestore}

  %The code will be stored as 'storeA'
  \begin{codestore}[storeA]
  ...
  \end{codestore}
  
  %This might raises an error. 
  %It will be stored as 'store' (not as 'store:A')
  \begin{codestore}[store:A]
  ...  
  \end{codestore}
\end{codestore}

\begin{codedescribe}[env]{codestore}
	\begin{codesyntax}
		\tsmacro{\begin{codestore}}[stcontents-keys]{}
    \tsmacro{\end{codestore}}{}
	\end{codesyntax}
This environment is an alias to \tsobj[env]{scontents} environment (from \tsobj[pkg]{scontents} package, see \cite{SCONTENTS}), all \tsobj[pkg]{scontents} keys are valid, with two additional ones: \tsobj[key]{st,store-at} which are aliases to the \tsobj[key]{store-env} key. If an ``isolated'' \tsobj[key,meta]{st-name} is given (unknown \tsobj[key]{key}), it is assumed that the environment body shall be stored in it (for use with \tsobj[code]{\tscode,\tsmergedcode,\tsdemo,\tsresult,\tsexec}).
%, in which case, obviously, a comma or equal signs are not allowed as well (new restriction since august 2025 \tsobj[pkg]{l3kernel} update) a colon ( : ) isn't allowed.
\end{codedescribe}
\begin{tsremark}
  From \tsobj[pkg]{scontents}, \tsobj[marg]{st-name} is \tsobj[oarg]{index}ed (The code is stored in a sequence variable). It is possible to store as many code snippets as needed under the same name. The first one will be \tsobj[oarg]{index}$\rightarrow 1$, the second $2$, and so on.
\end{tsremark}
\begin{tsremark}[\color{red}Warning:]
  If explicitly using one of the \tsobj[key,sep=or]{store-env,st,store-at} keys, the storage name can be anything. BUT, due to changes (August 2025) in the latex kernel keys processing, if an implicity key is used,  then colons ( : ), besides a comma and equal signs, aren't allowed.
  \tscode*{store-colon}
\end{tsremark}



%\subsection{Setting Keys}

\subsection{Code Display/Demo}\label{codelist}



\begin{codedescribe}[code,update=2024/01/06,update=2025/04/29]{\tscode*,\tsdemo*,\tsresult*}
	\begin{codesyntax}%
		\tsmacro{\tscode*}[code-keys]{st-name}\tsargs[oarg]{index}
		\tsmacro{\tsdemo*}[code-keys]{st-name}\tsargs[oarg]{index}
		\tsmacro{\tsresult*}[code-keys]{st-name}\tsargs[oarg]{index}
	\end{codesyntax}
\tsmacro{\tscode*}{} just typesets \tsobj[meta]{st-name} (created with \tsobj[env]{codestore}) verbatim with syntax highlight (from \tsobj[pkg]{listings} package \cite{listings}). The non-star version centers it and use just half of the base line. The star version uses the full text width.

\tsmacro{\tsdemo*}{} first typesets \tsobj[meta]{st-name}, as above, then \emph{executes} it. The non-start version place them side-by-side, whilst the star version places one following the other.

(new 2024/01/06) \tsmacro{\tsresult*}{} only \emph{executes} it. The non-start version centers it and use just half of the base line, whilst the star version uses the full text width.
\end{codedescribe}

\begin{tsremark}
  (from \tsobj[pkg]{stcontents} package) \tsobj[oarg]{index} can be from $1$ up to the number of stored codes under the same \tsobj[marg]{st-name}. Defaults to $1$.
\end{tsremark}

\begin{tsremark}
  All are executed in a local group which is discarded at the end. This is to avoid unwanted side effects, but might disrupt code execution that, for instance, depends on local variables being set. That for, see \tsobj{\tsexec} below.
\end{tsremark}

For Example:
\begin{codestore}[st=democodestore]
\begin{codestore}[stmeta]
		Some \LaTeX{} coding, for example: \ldots.
\end{codestore}  
This will just typesets \tsobj[key]{stmeta}:
\tscode*[codeprefix={Sample Code:}] {stmeta}
and this will demonstrate it, side by side with source code:
\tsdemo[numbers=left,ruleht=0.5, 
    codeprefix={inner sample code},
    resultprefix={inner sample result}] {stmeta}
\end{codestore}
\tscode*[emph2={tscode,tsdemo},emph={stmeta},keywd2={codestore}]{democodestore}[1]

\tsresult*[emph2={tscode,tsdemo},emph={stmeta},keywd2={codestore}]{democodestore}[1]



\begin{codedescribe}[code,new=2025/04/29]{\tsmergedcode*}
	\begin{codesyntax}%
		\tsmacro{\tsmergedcode*}[code-keys]{st-name-index list}
	\end{codesyntax}
This will typeset (as \tsobj{\tscode}) the merged contents from \tsobj[marg]{st-name-index list}. The list syntax comes from \tsobj[pkg]{scontents} (command \tsobj{\mergesc}), where it is possible to refer to a single index \tsargs[marg]{st-name A}\tsargs[oarg]{index}, a index range \tsargs[marg]{st-name B}\tsargs[oarg]{indexA-indexB}, or all indexes from a \tsobj[marg]{st-name}, \tsargs[marg]{st-name C}\tsargs[oarg]{1-end}. The special index \tsobj[oarg]{1-end} refers to all indexes stored under a given \tsobj[marg]{st-name}.
\end{codedescribe}
\begin{tsremark}
  The brackets aren't optional. For instance \tsmacro{\tsmergedcode*}[code-keys]{} {\color{red}\{} \tsargs[marg]{st-name A}\tsargs[oarg]{index} , \tsargs[marg]{st-name B}\tsargs[oarg]{indexA-indexB} , \tsargs[marg]{st-name C}\tsargs[oarg]{1-end} {\color{red}\}}
\end{tsremark}
\begin{codedescribe}[code,new=2025/04/29]{\tsexec}
	\begin{codesyntax}%
		\tsmacro{\tsexec}{st-name}\tsargs[oarg]{index}
	\end{codesyntax}
Unlike the previous commands which are all executed in a local group (discarded at the end) this will execute the code stored at \tsobj[marg]{st-name}\tsargs[oarg]{index} in the current \LaTeX{} group.

\end{codedescribe}



\subsubsection{Code Keys}\label{code-keys}

\begin{codedescribe}{\setcodekeys}
	\begin{codesyntax}%
		\tsmacro{\setcodekeys}{code-keys}
	\end{codesyntax}

One has the option to set \tsmeta{code-keys}  per \tsobj{\tscode,\tsmergedcode,\tsdemo,\tsresult} call (see \ref{codelist}), or \emph{globally}, better said, \emph{in the called context group} .

\begin{tsremark}[N.B.:]
All \tsobj[code]{\tscode,\tsdemo} commands create a local group  in which the \tsmeta{code-keys} are defined, and discarded once said local group is closed. \tsmacro{\setcodekeys}{} defines those keys in the \emph{current} context/group.
\end{tsremark}
\end{codedescribe}

\begin{codedescribe}[code,new=2025-05-01]{\setnewcodekey}
	\begin{codesyntax}%
		\tsmacro{\setnewcodekey}{new-key,code-keys}
	\end{codesyntax}
This will define a new key \tsobj[marg]{new-key}, which can be used with \tsobj{\tscode,\tsmergedcode,\tsdemo,\tsresult}. \tsobj[marg]{code-keys} can be any of the following ones, including other \tsobj[marg]{new-key}s. Be careful not to create a definition loop.
\end{codedescribe}

\begin{codedescribe}[key,update=2025-05-01]{settexcs,texcs,texcsstyle}
\begin{codesyntax}% Also
	\tsobj[key]{settexcs,settexcs2,settexcs3,settexcs4}
	\tsobj[key]{texcs,texcs2,texcs3,texcs4}
	\tsobj[key]{texcsstyle,texcs2style,texcs3style,texcs4style}
\end{codesyntax}
Those define sets of \LaTeX{} commands (csnames), the \tsobj[key]{set} variants initialize/redefine those sets (an empty list, clears the set), while the others extend those sets. The \tsobj[key]{style} ones redefines the command display style (an empty \tsobj[meta]{value} resets the style to it's default).\\
\end{codedescribe}


\begin{codedescribe}[key,update=2025-05-01]{setkeywd,keywd,keywdstyle}
\begin{codesyntax}	%
	\tsobj[key]{setkeywd,setkeywd2,setkeywd3,setkeywd4}
	\tsobj[key]{keywd,keywd2,keywd3,keywd4}
	\tsobj[key]{keywdstyle,keywd2style,keywd3style,keywd4style}
\end{codesyntax}
Same for other \emph{keywords} sets.\\
\end{codedescribe}

\begin{codedescribe}[key,update=2025-05-01]{setemph,emph,emphstyle}
\begin{codesyntax}	%
	\tsobj[key]{setemph,setemph2,setemph3,setemph4}
	\tsobj[key]{emph,emph2,emph3,emph4}
	\tsobj[key]{emphstyle,emph2style,emph3style,emph4style}
\end{codesyntax}
for some extra emphasis sets.\\
\end{codedescribe}

\begin{codedescribe}[key,new=2025-05-13]{letter,other}
\begin{codesyntax} %
	\tsobj[key]{letter,other}
\end{codesyntax}
These allow to redefine what a letter or other are (they correspond to the \tsobj[key]{alsoletter,alsoother} keys from \tsobj[pkg]{listings}). The default value for the \tsobj[key]{letter} includes (sans the comma) \tsobj[verb]{ @ : _ } , whilst \tsobj[key]{other} default value is an empty list.\\
\end{codedescribe}
\begin{tsremark}
  You might want to consider setting \tsobj[key]{letter} to just \tsverb[key]{letter={@,_}} so you don't have to list all variants, but just the base name of an \tsobj[pkg]{expl3} function.
\end{tsremark}

\begin{codedescribe}[key]{numbers,numberstyle}
\begin{codesyntax} %
	\tsobj[key]{numbers,numberstyle}
\end{codesyntax}
\tsobj[key]{numbers} possible values are \tsobj[value]{none} (default) and \tsobj[value]{left} (to add tinny numbers to the left of the listing). With \tsobj[key]{numberstyle} one can redefine the numbering style.\\
\end{codedescribe}

\begin{codedescribe}[key]{stringstyle,codestyle}
\begin{codesyntax} %
	\tsobj[key]{stringstyle,commentstyle}
\end{codesyntax}
to redefine \tsobj[key]{strings} and \tsobj[key]{comments} formatting style.\\
\end{codedescribe}

\begin{codedescribe}[key]{bckgndcolor}
\begin{codesyntax} %
	\tsobj[key]{bckgndcolor}
\end{codesyntax}
to change the listing background's color.\\
\end{codedescribe}

\begin{codedescribe}[key]{codeprefix,resultprefix}
\begin{codesyntax} %
	\tsobj[key]{codeprefix,resultprefix}
\end{codesyntax}
those set the \tsobj[key]{codeprefix} (default: \LaTeX{} Code:) and \tsobj[key]{resultprefix} (default: \LaTeX{} Result:)
\end{codedescribe}

\begin{codedescribe}[key]{parindent}
\begin{codesyntax} %
	\tsobj[key]{parindent}
\end{codesyntax}
Sets the indentation to be used when `demonstrating' \LaTeX{}code (\tsobj[code]{\tsdemo}). Defaults to whatever value \tsobj[code]{\parindent} was when the package was first loaded.
\end{codedescribe}

\begin{codedescribe}[key]{ruleht}%-very-long-long-long,xyz,xyh,kjh,ljd,kls}
\begin{codesyntax} %
	\tsobj[key]{ruleht}
\end{codesyntax}
When typesetting the `code demo' (\tsobj{\tsdemo}) a set of rules are drawn. The Default, 1, equals to \tsobj{\arrayrulewidth} (usually 0.4pt).
\end{codedescribe}

\begin{codedescribe}[key,new=2023/11/18]{basicstyle}%-very-long-long-long,xyz,xyh,kjh,ljd,kls}
\begin{codesyntax} %
	\tsobj[key]{basicstyle}
\end{codesyntax}
Sets the base font style used when typesetting the `code demo', default being \tsobj{\footnotesize} \tsobj{\ttfamily}
\end{codedescribe}


\section{codedescribe Package}

This package aims at minimizing the number of commands, being the object kind (if a macro, or environment, or variable, or key ...) a parameter, allowing for a simple extension mechanism: other object types can be easily introduced without having to change, or add commands.

\subsection{Package Options}

\begin{describelist}{option}
\describe{nolisting}{it will suppress the \tsobj[pkg]{codelisting} package load. In case it isn't needed or another listing package will be used.}
\describe{base skip}{Changes the base skip, all skips (used by the environments at \ref{desc-env}) are scaled up from this. It defaults to the font size at load time.}
\describe{strict}{Package Warnings will be reported as Package Errors.}
\describe{color scheme}{Possible values: \tsobj[option]{black,default,brighter, darker}. This will adjust the initial color configuration for the many format groups/objects (see \ref{format-keys}). \tsobj[option]{black} will defaults all \tsobj{\tsobj} colors to black.  \tsobj[option]{default, brighter, darker} are roughly the same color scheme. The \tsobj[option]{default} scheme is the one used in this document. With  \tsobj[option]{brighter} the colors are brighter than the default, and with \tsobj[option]{darker} the colors will be darker, but not black.}
\end{describelist}
\begin{tsremark}
  \tsobj[option]{color scheme} doesn't affect \tsobj[pkg]{codelisting} / \tsobj[pkg]{listings} colors.
\end{tsremark}

\subsection{Object Type keys}\label{obj-type-def}

\tsobj[arg]{obj-types} defines the applied format, which is defined in terms of \tsobj[arg]{format-groups} wich defines a formatting function, font shape, bracketing, etc. to be applied.

\subsubsection{Format Keys}\label{format-keys}
Those are the primitive \tsobj[arg]{format-keys} used when (re)defining  \tsobj[arg]{format-groups,obj-types} (see \ref{format-custom}):
\begin{describelist*}{keys}
  \describe {meta} {to typeset between angles,}
  \describe {xmeta} {to typeset *verbatim* between angles,}
  \describe {verb} {to typeset *verbatim*,}
  \describe {xverb} {to typeset *verbatim*, suppressing all spaces,}
  \describe {code} {to typeset *verbatim*, suppressing all spaces and replacing a TF by \underline{TF},}
  \describe {nofmt} {in case of a redefinition, to remove the `base' formatting,}
  \describe {slshape} {to use a slanted font shape,}
  \describe {itshape} {to use an italic font shape,}
  \describe {noshape} {in case of a redefinition, to remove the `base' shape,}
  \describe {lbracket}  {defines the left bracket (when using \tsobj{\tsargs}). \textbf{Note:} this key must have an associated value,}
  \describe {rbracket}  {defines the right bracket (when using \tsobj{\tsargs}). \textbf{Note:} this key must have an associated value,}
  \describe {color}   {defines the text color. \textbf{Note:} this key must have an associated value (a color, as understood by \tsobj[pkg]{xcolor} package).}
\end{describelist*}

%\ExplSyntaxOn
%\makeatletter
%\cs_show:N \color_select:n
%\cs_show:N \f@size
%\skip_show:n {\lineskip}
%\skip_show:n {\baselineskip}
%\makeatother
%\ExplSyntaxOff

\subsubsection{Format Groups}\label{format-group}
Using \tsobj{\defgroupfmt} (see \ref{format-custom}) one can (re-)define custom \tsobj[arg]{format-groups}. The following ones are predefined:
\begin{describelist*}{keys}
  \describe {meta} {which sets \tsobj[keys]{meta,color}}
  \describe {verb} {which sets \tsobj[keys]{color}}
  \describe {oarg} {which sets \tsobj[keys]{meta,color}}
  \describe {code} {which sets \tsobj[keys]{code,color}}
  \describe {syntax} {which sets \tsobj[keys]{color}}
  \describe {keyval} {which sets \tsobj[keys]{slshape,color}}
  \describe {option} {which sets \tsobj[keys]{color}}
  \describe {defaultval} {which sets \tsobj[keys]{color}}
  \describe {env}  {which sets \tsobj[keys]{slshape,color}}
  \describe {pkg}  {which sets \tsobj[keys]{slshape,color}}
\end{describelist*}
\begin{tsremark}
\tsobj[keys]{color} was used in the list above just as a `reminder' that a color is defined/associated with the given group, it can be changed with \tsobj{\defgroupfmt}.
\end{tsremark}

\subsubsection{Object Types}\label{obj-types}
Object types are the \tsobj[meta]{keys} used with \tsobj{\tsobj} (and friends, see \ref{ts-commands}) defining the specific formatting to be used.
With \tsobj{\defobjectfmt} (see \ref{format-custom}) one can (re-)define custom \tsobj[arg]{obj-types}. 
The predefined ones are:

\begin{describelist*}{keys}
  \describe {arg, meta} {based on (group) \tsobj[key]{meta}}
  \describe {verb, xverb} {based on (group) \tsobj[key]{verb} plus \tsobj[key,sep=or]{verb,xverb}}
  \describe {marg} {based on (group) \tsobj[key]{meta} plus brackets}
  \describe {oarg, parg, xarg} {based on (group) \tsobj[key]{oarg} plus brackets}
  \describe {code, macro, function} {based on (group) \tsobj[key]{code}}
  \describe {syntax} {based on (group) \tsobj[key]{syntax}}
  \describe {keyval, key, keys, values} {based on (group) \tsobj[key]{keyval}}
  \describe {option} {based on (group) \tsobj[key]{option}}
  \describe {defaultval} {based on (group) \tsobj[key]{defaultval}}
  \describe {env}  {based on (group) \tsobj[key]{env}}
  \describe {pkg, pack}  {based on (group) \tsobj[key]{pkg}}
\end{describelist*}

  

\subsubsection{Customization}\label{format-custom}

To create  user defined groups/objects or change the pre-defined ones:


\begin{codedescribe}[code,new=2023/05/16]{\defgroupfmt}
\begin{codesyntax} %
	\tsmacro{\defgroupfmt}{format-group,format-keys}
\end{codesyntax}
\tsobj[marg]{format-group} is the name of the new group (or one being redefined, which can be one of the standard ones). \tsobj[marg]{format-keys} is any combination of the keys from \ref{format-keys}
\end{codedescribe}

For example, one can redefine the \tsobj[key]{code group} standard color with \tsobj{\defgroupfmt{code}{color=red}} and all \tsobj[key]{obj-types} based on it will be typeset in red (in the standard case: \tsobj[key]{code, macro, function} objects).



\begin{codedescribe}[code,new=2023/05/16]{\defobjectfmt}
\begin{codesyntax} %
	\tsmacro{\defobjectfmt}{obj-type,format-group,format-keys}
\end{codesyntax}
\tsobj[marg]{obj-type} is the name of the new \tsobj[arg]{object} being defined (or redefined),
\tsobj[marg]{format-group} is the base group to be used (see \ref{format-group}). \tsobj[marg]{format-keys} (see \ref{format-keys}) allow for further differentiation.
\end{codedescribe}
For instance, the many optional \tsobj[arg]{*arg} are defined as follow:
\begin{codestore}[demo.fmtdef]
\colorlet {c__codedesc_oarg_color} { gray!90!black }

\defgroupfmt  {oarg} { meta , color=c__codedesc_oarg_color }

\defobjectfmt {oarg} {oarg} { lbracket={[} , rbracket={]} }
\defobjectfmt {parg} {oarg} { lbracket={(} , rbracket={)} }
\defobjectfmt {xarg} {oarg} { lbracket={<} , rbracket={>} }
\end{codestore}
\tscode*[codeprefix=~,keywd={oarg,arg,parg,xarg},keywd2={meta,color},emph={lbracket,rbracket}]{demo.fmtdef}

\subsection{Environments}\label{desc-env}

\begin{codedescribe}[env,new=2023/05/01,update=2023/05/01,note={a note example},update=2024/02/16,update=2025/09/25]{codedescribe}
\begin{codesyntax}
\tsmacro{\begin{codedescribe}}[obj-keys]{csv-list}
\ldots
\tsmacro{\end{codedescribe}}{}
\end{codesyntax}
This is the main environment to describe \tsobj[env,comma]{Commands, Variables, Environments, etc.} \tsobj[marg]{csv-list} items will be listed  in the left margin. The optional \tsobj[oarg]{obj-keys} defaults to just \tsobj[key]{code}, it can be any object type as defined at \ref{obj-types} (and \ref{format-custom}), besides the following keys:
\begin{describelist*}{key}
  \describe{new}{To add a \emph{new} line.}
  \describe{update}{To add an \emph{updated} line.}
  \describe{note}{To add a \emph{NB} line.}
  \describe{rulecolor}{For instance \tsmacro{\begin{codedescribe}[rulecolor=white]}{} will suppress the rules.}
  \describe{EXP}{A star \ding{72} will be added to all items, signaling the commands are fully expandable.}
  \describe{rEXP}{A hollow star \ding{73} will be added to all items, signaling the commands are restricted expandable.}
\end{describelist*}
\end{codedescribe}
\begin{tsremark}
The keys \tsobj[keys]{new,update,note} can be used multiple times. (2024/02/16)
\end{tsremark}
\begin{tsremark}
With the \tsobj[option]{strict} package option
an error will be raised if used inside another \tsobj[env]{codedescribe} environment. Otherwise a warning will be raised. (it's safe to do so, but it doesn't make much sense).
\end{tsremark}

\begin{codedescribe}[env,update=2025/09/25]{codesyntax}
\begin{codesyntax}
\tsmacro{\begin{codesyntax}}{}
\ldots
\tsmacro{\end{codesyntax}}{}
\end{codesyntax}
The \tsobj[env]{codesyntax} environment sets the fontsize and activates \tsmacro{\obeylines,\obeyspaces}{}, so one can list macros/cmds/keys use, one per line.
\end{codedescribe}

\begin{tsremark}
\tsobj[env]{codesyntax} environment shall appear only once, inside of a \tsobj[env]{codedescribe} environment. 
 Take note, as well, this is not a verbatim environment!
\end{tsremark}
\begin{tsremark}
With the \tsobj[option]{strict} package option
an error will be raised if used outside a \tsobj[env]{codedescribe} environment, or more than once inside. Otherwise warnings will be raised.
\end{tsremark}

For example, the code for  \tsobj[env]{codedescribe} (previous entry) is:

\begin{codestore}[demoD]
\begin{codedescribe}[env,new=2023/05/01,update=2023/05/01,note={a note example},update=2024/02/16,update=2025/09/25]{codedescribe}
  \begin{codesyntax}
    \tsmacro{\begin{codedescribe}}[obj-type]{csv-list}
    \ldots
    \tsmacro{\end{codedescribe}}{}
  \end{codesyntax}
  This is the main ...
\end{codedescribe}
\end{codestore}  

\tscode*{demoD}

\begin{codedescribe}[env]{describelist,describelist*}
  \begin{codesyntax}
\tsmacro{\begin{describelist}}[item-indent]{obj-type}
  ~~\tsmacro{\describe}{item-name,item-description}
  ~~\tsmacro{\describe}{item-name,item-description}
  ~~\ldots
\tsmacro{\end{describelist}}{}
  \end{codesyntax}
This sets a \tsobj[env]{description} like `list'. In the non-star version the \tsobj[marg]{items-name} will be typeset on the marginpar. In the star version, \tsobj[marg]{item-description} will be indented by \tsobj[oarg]{item-indent} (defaults to: 20mm).
\tsobj[marg]{obj-type} defines the object-type format used to typeset \tsobj[marg]{item-name}. 
\end{codedescribe}

\begin{codedescribe}[code]{\describe}
\begin{codesyntax}
\tsmacro{\describe}{item-name,item-description}
\end{codesyntax}
This is the \tsobj[env]{describelist} companion macro. In case of the \tsobj[env]{describe*}, \tsobj[marg]{item-name} will be typeset in a box \tsobj[oarg]{item-ident} wide, so that \tsobj[marg]{item-description} will be fully indented, otherwise \tsobj[marg]{item-name} will be typed in the marginpar.
\end{codedescribe}

\begin{tsremark}
An error will be raised (undefined control sequence) if called outside of a \tsobj[env,sep=or]{describelist,describelist*} environment.
\end{tsremark}


\subsection{Typeset Commands}\label{ts-commands}
\emph{Note} that, in the following commands, \tsobj[oarg]{obj-type} refers to any object type defined in  \ref{obj-types} and \ref{format-custom}.
% plus the following key:
%\begin{describelist*}{key}
%  \describe{strut}{This was a work around a bug when using \tsobj{\color} at the begin of an \tsobj[marg]{item-description} (from \tsobj{\describe}).}
%\end{describelist*}

\begin{codedescribe}[code,update=2025/05/29]{\typesetobj,\tsobj}
\begin{codesyntax}
\tsmacro{\typesetobj}[obj-type]{csv-list}
\tsmacro{\tsobj}[obj-type]{csv-list}
\end{codesyntax}
This is the main typesetting command, each term of \tsobj[marg]{csv-list} will be separated by a comma and formatted as defined by \tsobj[oarg]{obj-type} (defaults to \tsobj[key]{code}). \tsobj[oarg]{obj-type} can be any object from \ref{obj-types} (or \ref{format-custom}) and the following keys:
\begin{describelist*}{key}
  \describe{mid sep}{To change the item separator. Defaults to a comma, can be anything.}
  \describe{sep}{To change the separator between the last two items. Defaults to ``and''.}
  \describe{comma}{To set the separator between the last two items to a comma.}
  \describe{bnf or}{To produce a bnf style or list, like \tsobj[option,bnf or]{abc,xdh,htf,hrf}.}
  \describe{meta or}{To produce a bnf style or list between angles, like \tsobj[option,meta or]{abc,xdh,htf,hrf}.}
  \describe{par or}{To produce a bnf style or list between parentheses, like \tsobj[option,par or]{abc,xdh,htf,hrf}.}
\end{describelist*}
\end{codedescribe}


\begin{codedescribe}[code]{\typesetargs,\tsargs}
\begin{codesyntax}
\tsmacro{\typesetargs}[obj-type]{csv-list}
\tsmacro{\tsargs}[obj-type]{csv-list}
\end{codesyntax}
 These will typeset \tsobj[marg]{csv-list} as a list of parameters, like \tsargs[oarg]{arg1,arg2,arg3}, or \tsargs[marg]{arg1,arg2,arg3}, etc. \tsobj[oarg]{obj-type} defines the formating AND kind of brackets used (see \ref{obj-type-def}): \tsverb{[]} for optional arguments (oarg), \tsverb{{}} for mandatory arguments (marg), and so on.
\end{codedescribe}

\begin{codedescribe}[code]{\typesetmacro,\tsmacro}
\begin{codesyntax}
\tsmacro{\typesetmacro}{macro-list}\tsargs[oarg]{oargs-list}\tsargs[marg]{margs-list}
\tsmacro{\tsmacro}{macro-list}\tsargs[oarg]{oargs-list}\tsargs[marg]{margs-list}
\end{codesyntax}
These are just short-cuts for\par \tsobj[code]{\tsobj [code] {macro-list}} \tsobj[code]{\tsargs [oarg] {oargs-list}} \tsobj[code]{\tsargs [marg] {margs-list}}.

\end{codedescribe}

\begin{codedescribe}[code]{\typesetmeta,\tsmeta}
\begin{codesyntax}
\tsmacro{\typesetmeta}{name}
\tsmacro{\tsmeta}{name}
\end{codesyntax}
 These will just typeset \tsobj[meta]{name} between left/right `angles' (no further formatting).
 
\end{codedescribe}


\begin{codedescribe}[code]{\typesetverb,\tsverb}
\begin{codesyntax}
\tsmacro{\typesetverb}[obj-type]{verbatim text}
\tsmacro{\tsverb}[obj-type]{verbatim text}
\end{codesyntax}
 Typesets \tsobj[marg]{verbatim text} as is (verbatim...). \tsobj[oarg]{obj-type} defines the used format. The difference with \tsverb{\tsobj[verb]{something}} is that \tsmeta{verbatim text} can contain commas (which, otherwise, would be interpreted as a list separator in \tsobj{\tsobj}.
\end{codedescribe}
\begin{tsremark}
This is meant for short expressions, and not multi-line, complex code (one is better of, then, using \ref{codelist}).  \tsobj[meta]{verbatim text} must be balanced ! otherwise, some low level \TeX\ errors may pop out.
\end{tsremark}

\subsection{Note/Remark Commands}\label{note-commands}


\begin{codedescribe}[code]{\typesetmarginnote,\tsmarginnote}
\begin{codesyntax}
\tsmacro{\typesetmarginnote}{note}
\tsmacro{\tsmarginnote}{note}
\end{codesyntax}
Typesets a small note at the margin.
\end{codedescribe}

\begin{codedescribe}[env]{tsremark}
\begin{codesyntax}
\tsmacro{\begin{tsremark}}[NB]{}
\tsmacro{\end{tsremark}}{}
\end{codesyntax}
 The environment body will be typeset as a text note. \tsobj[oarg]{NB} (defaults to Note:) is the note begin (in boldface). For instance:
 \begin{codestore}[demo.remark]
 Sample text. Sample test.
  \begin{tsremark}[N.B.]
    This is an example.
  \end{tsremark}
 \end{codestore}
 \tsdemo{demo.remark}
\end{codedescribe}

\subsection{Auxiliary Commands and Environment}
In case the Document Class being used redefines the \tsobj[code]{\maketitle} command and/or \tsobj[env]{abstract} environment, alternatives are provided (based on the article class).

\begin{codedescribe}[code]{\typesettitle,\tstitle}
\begin{codesyntax}
\tsmacro{\typesettitle}{title-keys}
\tsmacro{\tstitle}{title-keys}
\end{codesyntax}
This is based on the \tsobj[code]{\maketitle} from the \tsobj[pkg]{article} class. The \tsobj[marg]{title-keys} are:
\end{codedescribe}

\begin{describelist*}{key}
\describe{title}{The title.}
\describe{author}{Author's name. It's possible to use the \tsobj[code]{\footnote} command in it.}
\describe{date}{Title's date.}
\end{describelist*}
\begin{tsremark}
  The \tsobj{\footnote} (inside this) will use an uniquely assigned counter, starting at one each time this is used (to avoid \tsobj[pkg]{hyperref} warnings).
\end{tsremark}


\begin{codedescribe}[env]{tsabstract}
\begin{codesyntax}
\tsmacro{\begin{tsabstract}}{}
\ldots
\tsmacro{\end{tsabstract}}{}
\end{codesyntax}
This is the \tsobj[env]{abstract} environment from the \tsobj[pkg]{article} class.
\end{codedescribe}

\begin{codedescribe}[code,new=2023/05/16]{\typesetdate,\tsdate}
\begin{codesyntax}
\tsmacro{\typesetdate}{}
\tsmacro{\tsdate}{}
\end{codesyntax}
This provides the current date (in Month Year, format).
\end{codedescribe}

\printbibliography



\end{document}
