%%%============================================================================== % 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.19} {2025/11/26} %% %% 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[T1]{fontenc} \usepackage[utf8]{inputenc} \usepackage{lmodern} %\usepackage[strict,infograb,load xtra dialects,TeX dialects={doctools,l3kernelsign, l3expsign, l3amssign, l3pgfsign, l3bibtexsign, % l3kernel, l3exp, l3ams, l3pgf, l3bibtex, kernel, xpacks, ams, pgf, pgfplots, % bibtex, babel, hyperref}]{codedescribe} \usepackage[strict,infograb,load xtra dialects,silence]{codedescribe} %\usepackage[strict,infograb]{codedescribe} \usepackage{enumitem} \RequirePackage[backend=biber]{biblatex} \addbibresource{codedescribe.bib} %\defgroupfmt{code}{color=red,font=\sffamily} \RequirePackage[hidelinks ,hypertexnames=false]{hyperref} \begin{document} \setnewcodekey{codedesc}{ texcs2={defgroupfmt,defobjectfmt,tsmacro,tsobj,setcodelabels,newlabelset,selectlabelset}, emph={lbracket,rbracket,stmeta}, emph2={tscode,tsdemo,new,update,note,env,and,or,months,remark}, keywd2={oarg,arg,parg,xarg,meta,color}, keywd={codedescribe,codesyntax,codestore,tsremark} } %\tscode*[emph2={tscode,tsdemo},emph={stmeta},keywd2={codestore}]{democodestore}[1] % %\tsresult*[emph2={tscode,tsdemo},emph={stmeta},keywd2={codestore}]{democodestore}[1] %\tscode*[codeprefix=~,keywd={oarg,arg,parg,xarg},keywd2={meta,color},emph={lbracket,rbracket}]{demo.fmtdef} %%% 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,xcolor}. 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 it should be possible to use these with any/most document classes. \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. Besides those, \tsobj[pkg]{xcolor} is needed to switch colors, and \tsobj[pkg]{xpeekahead} for spacing fine tuning. No other package/class is needed, and it should be possible to use these packages with most classes\footnote{If, by chance, a class with compatibility issues is found, just open an issue at \url{https://github.com/alceu-frigeri/codedescribe/issues} to see what can be done}, which allows to demonstrate document 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}), \tsobj[pkg]{codedescribe} defines a series of macros to display/enumerate macros and environments (somewhat resembling the \tsobj[pkg]{doc3} style), and \tsobj[pkg]{codelstlang} defines a series of \tsobj[pkg]{listings} TeX dialects. \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} All packages (\tsobj[pkg]{codedescribe,codelisting,codelstlang,codedescsets}) share the same version, currently: \PkgInfo{codelstlang}{version}. Those 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 loads: \tsobj[pkg]{listings,scontents,xpeekahead}, 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{Package Options}\label{codelist.pack-options} The following options are also \tsobj[pkg]{codedescribe} options, see \ref{codedesc.pack-options}. \begin{describelist}{option} \describe{load xtra dialects}{(defaults to false) If set, it will load the auxiliary package \tsobj[pkg]{codelstlang} (see \ref{lstlang.pack}), which just defines a series of \tsobj[pkg]{listings} TeX dialects. } \describe{TeX dialects}{This will set which \tsobj[pkg]{listings} TeX dialects will be used when defining the listing style \tsobj[option]{codestyle}. It defaults to \tsobj[option]{doctools}, which is derived from the [LaTeX]TeX dialect (this contains the same set of commands used by the package \tsobj[pkg]{doctools}). One can use any valid (TeX derived) \tsobj[pkg]{listings} dialect, including user defined ones, see \cite{listings} for details. Besides those, one can use (if the \tsobj[option]{load xtra dialects} is set): \tsobj[option]{l3kernelsign, l3expsign, l3amssign, l3pgfsign, l3bibtexsign, l3kernel, l3exp, l3ams, l3pgf, l3bibtex, kernel, xpacks, ams, pgf, pgfplots, bibtex, babel, hyperref }. See \ref{lstlang.pack} for details on those dialects. } \begin{tsremark} \tsobj[option]{TeX dialects} is a comma separated list of the dialect's name, without the base language (internally it will be converted to \tsverb[key]{[dialect]TeX}). \end{tsremark} \end{describelist} For example: \begin{codestore}[demo.dialect] %% could be \usepackage[...]{codelisting} \usepackage[load xtra dialects, TeX dialects={doctools,l3kernel,l3ams}]{codedescribe} %% %% assuming the user has defined a dialect, named: [my-own-set]TeX %% \usepackage[TeX dialects={doctools,my-own-set}]{codedescribe} %% \end{codestore} % \tscode*[codeprefix=~,codedesc]{demo.dialect} \newpage \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*[codedesc]{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*[codedesc]{democodestore}[1] \tsresult*[codedesc]{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,new={2025/11/26}]{lststyle} \begin{codesyntax}% Also \tsobj[key]{lststyle} \end{codesyntax} This sets the base style to be used. It defaults to \tsobj[key]{codestyle}, and the user can use this (\tsobj[key]{codestyle}) as the base style for his own one (and avoid having to define every single aspect of it). For example: \end{codedescribe} \begin{codestore}[demo.lststyle] \lstdefinestyle{my-own}{ % see the listings manual for a complete list of keywords style=codestyle, texcsstyle = * {\bfseries\color{red}} } \tscode*[lststyle=my-own]{demo-X} \end{codestore} % \tscode*[codeprefix=~,codedesc]{demo.lststyle} \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} These define sets of \LaTeX{} commands (csnames, sans the preceding slash bar), 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}'s default value is an empty list. \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} \end{codedescribe} \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} \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} \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}\label{codedesc.pack-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{label set}{(new: 2025/11/22) This allows to pre-select a label set, see \ref{labelset}. Currently, the possible values are \tsobj[key]{english,german,french}, the ones present in the auxiliary package \tsobj[pkg]{codedescsets}.} \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{silence}{(new: 2025/11/22, defaults to 18.89999pt) This will suppress some annoying bad boxes warnings. Given the way environments at \ref{desc-env} are defined, with \tsobj[pkg]{expl} coffins, TeX thinks they are too wide, when they are not. } \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.} \describe{load xtra dialects}{This will be passed over to \tsobj[pkg]{codelisting} package (if loaded). See \ref{codelist.pack-options}. } \describe{TeX dialects}{This will be passed over to \tsobj[pkg]{codelisting} package (if loaded). See \ref{codelist.pack-options}. } \begin{tsremark} In case of an unknown \tsobj[option]{label set}, an error will be risen, and all known sets will be listed in the log file and terminal. \end{tsremark} \begin{tsremark} \tsobj[option]{color scheme} doesn't affect \tsobj[pkg]{codelisting} / \tsobj[pkg]{listings} colors. \end{tsremark} \end{describelist} \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} {sets base format to typeset between angles,} \describe {xmeta} {sets base format to typeset *verbatim* between angles,} \describe {verb} {sets base format to typeset *verbatim*,} \describe {xverb} {sets base format to typeset *verbatim*, no spaces,} \describe {code} {sets base format to typeset *verbatim*, no spaces, replacing a TF by \underline{TF},} \describe {nofmt} {in case of a redefinition, removes 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, removes the base shape,} \describe {lbracket} {sets the left bracket (when using \tsobj{\tsargs}),} \describe {rbracket} {sets the right bracket (when using \tsobj{\tsargs}),} \describe {color} {sets the text color. \textbf{NB:} color's name, as understood by \tsobj[pkg]{xcolor} package,} \describe {font} {defaults to \tsobj{\ttfamily}. Sets font family,} \describe {fsize} {defaults to \tsobj{\small}. Sets font size.} \end{describelist*} \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=~,codedesc]{demo.fmtdef} \subsection{Locale} The following commands allows to customize the many `labels' in use, in particular the auxiliary package \tsobj[pkg]{codedescsets} holds a few locale sets, the user is invited to submit translations for a specific case/language via a PR (Push Request) at \url{https://github.com/alceu-frigeri/codedescribe} \begin{codedescribe}[code,new=2025/11/22]{\setcodelabels,\newlabelset,\selectlabelset}\label{labelset} \begin{codesyntax} % \tsmacro{\setcodelabels}{labels-list} \tsmacro{\newlabelset}{lang,labels-list} \tsmacro{\selectlabelset}{lang} \end{codesyntax} \tsobj{\setcodelabels} allows to change the many `labels' used (like `updated' in the \tsobj[env]{codedescribe} environment). See below for a complete list of possible labels, it can be used at any time, allowing to change those labels mid text. \tsobj{\newlabelset} will create a label's set (named as \tsobj[marg]{lang}) for later use with \tsobj{\selectlabelset} (akin of a language locale), while \tsobj{\selectlabelset} will select (activate) the given set. They can also be used at any time. \end{codedescribe} The \tsobj[marg]{labels-list} can be any combination of: \begin{describelist*}{key} \describe{new}{It set's the `new' label used in the \tsobj[env]{codedescribe} environment.} \describe{update}{It set's the `update' label used in the \tsobj[env]{codedescribe} environment.} \describe{note}{It set's the `note' label used in the \tsobj[env]{codedescribe} environment.} \describe{and}{It set's the `and' label used by \tsobj{\tsobj} (hint: last item separator).} \describe{or}{It set's the `or' label used by \tsobj{\tsobj} (hint: last item separator).} \describe{months}{It set's the month list used by \tsobj{\tsdate}, see \ref{aux-commands}. NB.: it expects a list of names starting at `January' and ending at `December'.} \end{describelist*} \begin{tsremark} \tsobj{\newlabelset} is used in the auxiliary package \tsobj[pkg]{codedescsets} to pre-define some sets, which can then be used as a package option, see \ref{codedesc.pack-options}. \end{tsremark} \begin{tsremark} The given \tsobj[marg]{labels-list} doesn't need to be complete, though, only the given labels will be changed. \end{tsremark} \begin{tsremark} \tsobj{\newlabelset} can be used to redefine a given set, though, if doing so, one has to provide all labels. The old (if any) definitions will be erased. No warnings given. \end{tsremark} For example, this sets a new label set for German. In fact, since this is defined in the package \tsobj[pkg]{codedescsets} this label set can be used when loading this package, see \ref{codedesc.pack-options}. \begin{codestore}[labelset] \newlabelset {german} { new = neu , update = aktualisiert , note = NB , remark = Hinweis , and = und , or = oder , months = { Januar, Februar, März, April, Mai, Juni, Juli, August, September, Oktober, November, Dezember } } \end{codestore} \tscode*[codedesc,codeprefix={}]{labelset} \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} If using one of the keys \tsobj[key,or]{new,update,note,rulecolor,EXP,rEXP} the user must also provide an object type. \tsobj[key]{code} is the solely default IF nothing else is provided. \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,update=2025/11/25]{codesyntax} \begin{codesyntax} \tsmacro{\begin{codesyntax}}[obj-type]{} \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. The content will be formatted as defined by \tsobj[oarg]{obj-type} (defaults to \tsobj[syntax]{syntax}). \tsobj[oarg]{obj-type} can be any object from \ref{obj-types} (or \ref{format-custom}) \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 a warning 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*[codedesc]{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} 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{or}{To set the separator between the last two items to ``or''.} \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 by \tsobj{\tsobj}. \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 might pop out. \end{tsremark} \end{codedescribe} \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[codedesc]{demo.remark} \end{codedescribe} \subsection{Auxiliary Commands and Environment}\label{aux-commands} 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} \newpage \section{codelstlang Package}\label{lstlang.pack} This is an auxiliary package (which can be used on its own). It assumes the package \tsobj[pkg]{listings} was already loaded, and just defines the following \TeX{} dialects, all of them derived from (listings) \tsverb[key]{[LaTeX]TeX}: \begin{describelist}{key} \describe{[l3kernelsign]TeX} {Most/all \tsobj[pkg]{expl} keys found in the \tsobj[pkg,comma]{l3kernel}\cite{l3kernel} packages, including signatures. } \describe{[l3expsign]TeX} {Most/all \tsobj[pkg]{expl} keys found in the \tsobj[pkg,comma]{l3kernel} experimental packages, including signatures. } \describe{[l3amssign]TeX} {Most/all \tsobj[pkg]{expl} keys found in the \tsobj[pkg,comma]{ams,siunitx} and related packages, including signatures. } \describe{[l3pgfsign]TeX} {Most/all \tsobj[pkg]{expl} keys found in the \tsobj[pkg,comma]{pgf} and related packages, including signatures. } \describe{[l3bibtexsign]TeX} {Most/all \tsobj[pkg]{expl} keys found in the \tsobj[pkg,comma]{bibtex,biblatex} and related packages, including signatures.} \begin{tsremark} The underscore `\_' and colon `:' have to be defined as letters (\tsverb[key]{letter = { _ , : }}, see \ref{code-keys}). Take note that those dialects are quite large, due the many signatures variants. \end{tsremark} \describe{[l3kernel]TeX} {Most/all \tsobj[pkg]{expl} keys found in the \tsobj[pkg,comma]{l3kernel} packages, without signatures. } \describe{[l3exp]TeX} {Most/all \tsobj[pkg]{expl} keys found in the \tsobj[pkg,comma]{l3kernel} experimental packages, without signatures. } \describe{[l3ams]TeX} {Most/all \tsobj[pkg]{expl} keys found in the \tsobj[pkg,comma]{ams,siunitx} and related packages, without signatures. } \describe{[l3pgf]TeX} {Most/all \tsobj[pkg]{expl} keys found in the \tsobj[pkg,comma]{pgf} and related packages, without signatures. } \describe{[l3bibtex]TeX} {Most/all \tsobj[pkg]{expl} keys found in the \tsobj[pkg,comma]{bibtex,biblatex} and related packages, without signatures.} \begin{tsremark} The underscore `\_' has to be defined as letter (\tsverb[key]{letter = { _ }}, but not the colon `:', see \ref{code-keys}). Those are more compact versions of the previous ones. \end{tsremark} \describe{[kernel]TeX} {Most/all document level keys found in the \tsobj[pkg,comma]{kernel} packages. } \describe{[xpacks]TeX} {Most/all document level keys found in the \tsobj[pkg,comma]{x*} packages, like \tsobj[pkg,comma]{xkeyval,xpatch,xcolor} etc. } \describe{[ams]TeX} {Most/all document level keys found in the \tsobj[pkg,comma]{ams,siunitx} and related packages. } \describe{[pgf]TeX} {Most/all document level keys found in the \tsobj[pkg,comma]{pgf} and related packages.} \describe{[pgfplots]TeX} {Most/all document level keys found in the \tsobj[pkg,comma]{pgfplots} and related packages.} \describe{[bibtex]TeX} {Most/all document level keys found in the \tsobj[pkg,comma]{bibtex,biblatex} and related packages.} \describe{[babel]TeX} {Most/all document level keys found in the \tsobj[pkg,comma]{babel} and related packages.} \describe{[hyperref]TeX} {Most/all document level keys found in the \tsobj[pkg,comma]{hyperref} and related packages.} \begin{tsremark} Those are usual document level, \LaTeXe, commands. In particular none of them includes any `@' symbol. \end{tsremark} \end{describelist} \printbibliography \end{document}