%%%============================================================================== % WinEdt pragmas % !Mode:: "TeX:EN" % Default Compile engines: % !TEX program = pdflatex % !PDFTeXify ext = --enable-etex --enable-write18 % !PDFLaTeX ext = --enable-etex --enable-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.20} {2025/12/17} %% %% The list of files that compose this work can be found in the README.md file at %% https://ctan.org/pkg/codedescribe %% %%%============================================================================== \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,silence,colors=darker,listing colors=darker]{codedescribe} \usepackage[strict,infograb,silence]{codedescribe} \usepackage{enumitem} \RequirePackage[backend=biber]{biblatex} \addbibresource{codedescribe.bib} %\usepackage{xindex} %\makeindex %\defgroupfmt{code}{color=red,font=\sffamily} % %\defgroupfmt{code}{color=brown,font=\ttfamily} \RequirePackage[hidelinks,hypertexnames=false]{hyperref} \begin{document} \setnewcodekey{codedesc}{ texcs={printindex}, 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} } %%% 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,no index]{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 margin paragraph''), or underlying macros, so it should be possible to use these with any/most document classes. \end{typesetabstract} \tableofcontents \section{Introduction} This package aims at documenting both document level (i.e. final user) and package/class level commands. It's fully implemented using \tsobj[pkg]{expl3}, requiring just an up to date kernel. \tsobj[pkg]{scontents,listing} packages (see \cite{SCONTENTS} and \cite{listings}) are used to typeset code snippets. The package \tsobj[pkg]{pifont} (see \cite{pifont}) is needed just to typeset those (open)stars, in case one wants to mark a command as (restricted) expandable. \tsobj[pkg]{xcolor} (see \cite{xcolor}) is needed to switch colors, and \tsobj[pkg]{xpeekahead} (see \cite{xpeekahead}) for spacing fine tuning. The package \tsobj[pkg]{infograb} (see \cite{pkginfograb}) is also loaded, for package's documentation only (including tracking of package's version). 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. Generating an index is supported (see \ref{indexing} and \ref{obj-types}) but no index package is pre-loaded, leaving it to the end user. \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. All packages (\tsobj[pkg]{codedescribe,codelisting,codelstlang,codedescsets}) share the same version, currently: \PkgInfo{codedescribe}{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. \subsection{Single versus Multi-column Classes} This package ``can'' be used with multi-column classes, given that the \tsobj[code,no index]{\linewidth,\columnsep} are defined appropriately. \tsobj[code,no index]{\linewidth} shall defaults to text/column real width, whilst \tsobj[code,no index]{\columnsep}, if needed (2 or more columns) shall be greater than \tsobj[code,no index,sep = plus]{\marginparwidth,\marginparsep}. \section{codelisting Package} It loads: \tsobj[pkg]{listings,scontents,xpeekahead}, defines an environment: \tsobj[env,no index]{codestore} and a few commands for listing/demo code. \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{listing colors}{Possible values: \tsobj[option]{black,default,brighter, darker}. This will adjust the initial color configuration for the many listings' elements (used by \tsobj[code,no index]{\tscode,\tsdemo}). \tsobj[option]{black} will defaults all 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{colors}{This is just an alias for \tsobj[option]{listing colors}} \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[values]{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}, 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,no index]{scontents} environment (from \tsobj[pkg]{scontents}, 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,no index]{\tscode,\tsmergedcode,\tsdemo,\tsresult,\tsexec}). \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,no index]{stmeta}: \tscode*[codeprefix={Sample Code:}] {stmeta} and this will demonstrate it, side by side with source code: \tsdemo[numbers=left,firstnumber=5,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{Colors Customization} \begin{codedescribe}[code,new=2025/12/14]{\setlistcolorscheme} \begin{codesyntax} % \tsmacro{\setlistcolorscheme}{color-key-list} \end{codesyntax} This allows to customize the default colors used by \tsobj[code,no index]{\tscode,\tsdemo} when typesetting (assuming the default listings's style is being used). Note that the given colors will be mixed with black. The key \tsobj[key]{brightness} set's the mixing proportion. The changes become effective at the point of use. \end{codedescribe} \tsobj[marg]{color-key-list} can be any combination of: \begin{describelist*}{keys} \describe{bckgnd}{(default: black) Sets the background base color. Note this is mixed with white, not black as the others. } \describe{string}{(default: teal) Sets the string base color} \describe{comment}{(default: green) Sets the comment base color} \describe{texcs}{(default: blue) Sets the texcs (\TeX{} commands) base color} \describe{keywd}{(default: cyan) Sets the keywd (keywords) base color} \describe{emph}{(default: red) Sets the emph (emphasis) base color} \describe{rule}{(default: gray) Sets the rule (unused by now) base color. Note this is mixed with white, not black as the others. } \describe{number}{(default: gray) Sets the (small line) numbers base color. Note this is mixed with white, not black as the others. } \describe{brightness}{(default: 1) Sets the mixing proportion between each base color and black.} \describe{default}{Sets all the above to their default value} \describe{scheme}{Selects a pre-set color scheme. see below} \end{describelist*} \begin{codedescribe}[code,new=2025/12/14]{\newlistcolorscheme} \begin{codesyntax} % \tsmacro{\newlistcolorscheme}{new-scheme,color-key-list} \end{codesyntax} This creates/defines a \tsobj[marg]{new-scheme} (\tsobj[marg]{color-key-list} as above) which can be later used as \tsobj[code,no index]{\setlistcolorscheme{scheme=new-scheme}} \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/12}]{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,no index]{set} variants initialize/redefine those sets (an empty list, clears the set), while the others extend those sets. The \tsobj[key,no index]{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,no index]{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,update=2025/12/16]{numbers,numberstyle,firstnumber} \begin{codesyntax} % \tsobj[key]{numbers,numberstyle,firstnumber} \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. \tsobj[key]{firstnumber} sets the numbering start, it can be any number, \tsobj[value,or]{last,auto}. It defaults to \tsobj[value]{last} (see \cite{listings} for details). \end{codedescribe} \begin{codedescribe}[key]{stringstyle,commentstyle} \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,no index]{\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[code,no index]{\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[code,no index]{\footnotesize} \tsobj[code,no index]{\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}{key} \describe{nolisting}{Will suppress the \tsobj[pkg]{codelisting} package load. In case it isn't needed or another listing package will be used.} \describe{index}{(new: 2025/12/15) This will set the default of some object groups to \tsobj[key,no index]{index}. This won't load any index package, but just change some objects' default behaviour (see \ref{indexing} and \ref{obj-type-def})} \describe{label set}{(new: 2025/11/22) This allows to pre-select a label set, see \ref{labelset}. Currently, the possible values are \tsobj[option]{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{} sometimes thinks they are too wide, when they are not. This just sets \tsobj[code,no index]{\hfuzz} to the given value.} \describe{describe keys}{(defaults to \tsobj[value]{group}) This sets the way the keys \tsobj[key]{new,update,note} are listed in a \tsobj[env]{codedescribe} environment, see \ref{desc-env}. Possible values are \tsobj[value,or]{group,as is, in sequence}. By default keys are grouped together, with \tsobj[value,or]{as is, in sequence} keys will respect the used sequence. } \describe{colors}{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{listing~ colors}{This will be passed over to \tsobj[pkg]{codelisting} package (if loaded). See \ref{codelist.pack-options}. } \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}. } \describe{infograb}{This will enable the document level, \LaTeX2e, aliases from the package \tsobj[pkg]{pckinfograb} \cite{pkginfograb}.} \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} The option \tsobj[option]{colors} doesn't affect \tsobj[pkg]{codelisting} / \tsobj[pkg]{listings} colors. \end{tsremark} \end{describelist} \subsection{Indexing}\label{indexing} Its up to the user to choose a companion package to format and display index entries, though a very simple setup, using \tsobj[pkg]{xindex}'s defaults, could just be: \begin{codestore}[index-demo] % in the document's preamble \usepackage{xindex} \makeindex ... % at the document's end \printindex \end{codestore} \tscode*[codedesc,codeprefix={}]{index-demo} The command \tsobj[code,no index]{\tsobj} and environments \tsobj[env,no index]{codedescribe,describelist} create index entries with the command \tsobj[code,no index]{\index} based on the object type (see \ref{obj-type-def}, \ref{desc-env} and \ref{ts-commands}). The many items will be grabbed as \textbf{\tsmeta{index prefix}\tsmeta{item}@\tsmeta{index group}!\tsmeta{item}}. That way \tsobj[meta]{index prefix} can be used to force items to be sorted together and \tsobj[meta]{index group} can be used to group, indent, similar items. The backslash, if any, is removed from the first \tsmeta{item} (preceding the @). Note that, when defining an Object Type (see below) only \tsobj[meta]{index group} can be preset. \tsobj[meta]{index-prefix} can only be set when calling \tsobj[code,no index]{\tsobj} or using the \tsobj[env,no index,or]{codedescribe,describelist} environments. \begin{tsremark} The package option \tsobj[option]{index} won't load any index package, but just set the defaults of some format groups (see \ref{format-group}) to generate index entries. \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}. Both define the formatting function, font shape, bracketing, etc. to be applied. When using a \tsobj[arg]{obj-type}, first the associated \tsobj[arg]{format-group} is applied, then the particular (if any) object format is 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. Note that, it only makes sense if applied at the same level, meaning, if the format was originally defined at group formatting level, it only can be removed at this level.} \describe {format} {Sets the base format. Possible values: \tsobj[values,or]{meta,xmeta,verb,xverb,code,nofmt,none}, as above.} \begin{tsremark} The \tsobj[key]{format} Key is just an alternative way of setting the base formatting. \tsobj[value]{none} is just an alias to \tsobj[key]{nofmt}. \end{tsremark} \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. Note that, it only makes sense if applied at the same level, meaning, if shape was originally defined at group formatting level, it only can be removed at this level.} \describe {shape} {Sets the font shape. Possible values: \tsobj[value,or]{itshape,italic,slshape,slanted,noshape,none}, as above.} \begin{tsremark} The \tsobj[key]{shape} Key is just an alternative way of setting the font shape. \tsobj[value]{none} is just an alias to \tsobj[value]{noshape}. \end{tsremark} \describe {shape preadj}{Adds a (thin) space before each term in \tsobj{\tsobj}, see \ref{ts-commands}. Possible values: \tsobj[values,or]{none,very thin, thin, mid}.} \describe {shape posadj}{Adds a (thin) space after each term in \tsobj{\tsobj}, see \ref{ts-commands}. Possible values: \tsobj[values,or]{none,very thin, thin, mid}.} \begin{tsremark} These are meant for the case in which the italic or slanted shapes of the used font renders a character too close to a upright character. \end{tsremark} \describe {lbracket} {Sets the left bracket (when using \tsobj{\tsargs}), see \ref{ts-commands}.} \describe {rbracket} {Sets the right bracket (when using \tsobj{\tsargs}), see \ref{ts-commands}.} \describe {color} {Sets the text color. \textbf{NB:} color's name as understood by \tsobj[pkg]{xcolor} package.} \describe {font} {Defaults to \tsobj[code,no index]{\ttfamily}. Sets font family.} \describe {fsize} {Defaults to \tsobj[code,no index]{\small}. Sets font size.} \begin{tsremark} \tsobj[key]{font,fsize} shall receive a single command that absorbs no tokens. \end{tsremark} \describe {no index} {To NOT include the items in the default index.} \describe {index} {To include the items in the default index.} \describe {index group} {Sets the `index group' for those items (see \ref{indexing}).} \begin{tsremark}[\color{red}Important:] Except for \tsobj[key]{font,fsize} all other keys will expand the assigned value at definition time! \end{tsremark} \end{describelist*} \subsubsection{Format Groups}\label{format-group} Using \tsobj{\defgroupfmt} (see \ref{format-custom}) one can (re-)define custom \tsobj[arg]{format-groups}. Predefined ones: \begin{describelist*}{keys} \describe {meta} {which sets \tsobj[keys]{meta,color}} \describe {verb} {which sets \tsobj[keys]{color}} \describe {code} {which sets \tsobj[keys]{code,color,index} (\tsobj[keys]{index group} = ``\tsobj[value]{command(s)}'')} \describe {oarg} {which sets \tsobj[keys]{meta,color}} \describe {syntax} {which sets \tsobj[keys]{color}} \describe {env} {which sets \tsobj[keys]{slshape,color,index} (\tsobj[keys]{index group} = ``\tsobj[value]{environment(s)}'')} \describe {pkg} {which sets \tsobj[keys]{slshape,color}} \describe {option} {which sets \tsobj[keys]{color,index} (\tsobj[keys]{index group} = ``\tsobj[value]{option(s)}'')} \describe {keys} {which sets \tsobj[keys]{slshape,color,index} (\tsobj[keys]{index group} = ``\tsobj[value]{key(s)}'')} \describe {values} {which sets \tsobj[keys]{slshape,color}} \describe {defaultval} {which sets \tsobj[keys]{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} \begin{tsremark} \tsobj[keys]{index,index group} will only be set if the option \tsobj[option]{index} was used when loading this package, see \ref{codedesc.pack-options}. \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 format to be used. With \tsobj{\defobjectfmt} (see \ref{format-custom}) one can (re-)define custom \tsobj[arg]{obj-types}. Predefined ones: \begin{describelist*}{keys,no index} \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} {based on (group) \tsobj[key]{keys}} \describe {value, values} {based on (group) \tsobj[key]{values}} \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 predefined 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 the 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, to change the color of all \tsobj[key]{obj-types} based on the \tsobj[key]{code} group (\tsobj[key,no index]{code, macro, function} objects) to red, it's enought to \tsobj[code,no index]{\defgroupfmt{code}{color=red}}. \begin{codedescribe}[code,new=2025/12/11]{\dupgroupfmt} \begin{codesyntax} % \tsmacro{\dupgroupfmt}{new-group,org-group} \end{codesyntax} \tsobj[marg]{new-group} will be a copy of \tsobj[marg]{org-group} definition at time of use. Both can be later chaged/re-defined independently of each other. \end{codedescribe} \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}) allows 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} \begin{codedescribe}[code,new=2025/12/14]{\setcolorscheme} \begin{codesyntax} % \tsmacro{\setcolorscheme}{color-key-list} \end{codesyntax} This allows to customize the default colors used by the many object types and format groups. Note that the given colors will be mixed with black. The key \tsobj[key]{brightness} set's the mixing proportion. The changes become effective at the point of use. \end{codedescribe} \tsobj[marg]{color-key-list} can be any combination of: \begin{describelist*}{keys} \describe{error}{(default: red) Sets the error base color } \describe{verb}{(default: black) Sets the verb base color} \describe{args}{(default: gray) Sets the args base color} \describe{code}{(default: blue) Sets the code base color} \describe{keys}{(default: teal) Sets the keys base color} \describe{values}{(default: green) Sets the values base color} \describe{env}{(default: green) Sets the env base color} \describe{pack}{(default: green) Sets the pack base color} \describe{brightness}{(default: 1) Sets the mixing proportion between each base color and black.} \describe{default}{Sets all the above to their default value} \describe{scheme}{(no default) Selects a pre-set color scheme. see below} \end{describelist*} \begin{codedescribe}[code,new=2025/12/14]{\newcolorscheme} \begin{codesyntax} % \tsmacro{\newcolorscheme}{new-scheme,color-key-list} \end{codesyntax} This creates/defines a \tsobj[marg]{new-scheme} (\tsobj[marg]{color-key-list} as above) which can be later used as \tsobj[code,no index]{\setcolorscheme{scheme=new-scheme}} \end{codedescribe} \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, while \tsobj{\selectlabelset} will select (activate) the given set. All those commands can 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,no index]{Commands, Variables, Environments, etc.} \tsobj[marg]{csv-list} items will be listed in the left margin. The \tsobj[env]{codesyntax} will be attached to it's right, and the rest of the text will be below them, with the usual text width. 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: \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.} \describe {no index} {To NOT include the items in the default index} \describe {index} {To include the items in the default index} \describe {index group} {Sets the \tsobj[meta]{index group} for those items (see \ref{indexing}).} \describe {index prefix} {Sets the \tsobj[meta]{index prefix} for those items (see \ref{indexing}).} \describe {force margin} {If set, \tsobj[meta]{csv-list} items will be listed in the margin, regardless of their width.} \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} The default behaviour, when using \tsobj[key,no index,or]{new,update,note}, is that they will be grouped, first all \tsobj[key,no index]{new} keys, then all \tsobj[key,no index]{update} keys and lastly all \tsobj[key,no index]{note} keys. This can be changed with the package option \tsobj[option]{describe keys} (see \ref{codedesc.pack-options}). If set to \tsobj[value,or]{as is, in sequence}, those keys will be listed in the order of appearance. \end{tsremark} \begin{tsremark}[\color{red} Attention:] The \tsobj[env]{codedescribe} environment `acts' as a single block! That assures the margin block, the \tsobj[env]{codesyntax} environment (block) and the following text (inside the \tsobj[env]{codedescribe} environment) will always stay in the same page. \end{tsremark} \begin{tsremark}[\color{red} Attention:] If the items don't fit in the margin, the \tsobj[marg]{csv-list} will advance towards the text window, reducing the horizontal space of the \tsobj[env]{codesyntax} block. This can be changed with the \tsobj[key]{force margin}, in which case the \tsobj[marg]{csv-list} will always be at the margin, growing leftwards (might end outside the page). \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,codeprefix={}]{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} \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 margin. 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}, it can be any object from \ref{obj-types} (or \ref{format-custom}) and the following keys: \begin{describelist*}{key} \describe {no index} {To NOT include {item names} in the default index.} \describe {index} {To include {item names} in the default index.} \describe {index group} {Sets the \tsobj[meta]{index group} for those items (see \ref{indexing}).} \describe {index prefix} {Sets the \tsobj[meta]{index prefix} for those items (see \ref{indexing}).} \end{describelist*} \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-indent} wide, so that \tsobj[marg]{item-description} will be fully indented, otherwise \tsobj[marg]{item-name} will be typed in the margin. \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: \end{codedescribe} \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,no index]{abc,xdh,htf,hrf}.} \describe{meta or}{To produce a bnf style or list between angles, like \tsobj[option,meta or,no index]{abc,xdh,htf,hrf}.} \describe{par or}{To produce a bnf style or list between parentheses, like \tsobj[option,par or,no index]{abc,xdh,htf,hrf}.} \describe {no index} {To NOT include the items in the default index.} \describe {index} {To include the items in the default index.} \describe {index group} {Sets the \tsobj[meta]{index group} for those items (see \ref{indexing}).} \describe {index prefix} {Sets the \tsobj[meta]{index prefix} for those items (see \ref{indexing}).} \end{describelist*} \begin{tsremark} If \tsobj[key,sep={and/or}]{shape preadj,shape posadj} are set (see \ref{format-keys}, a (thin) space will be added before and/or after each term of \tsobj[marg]{csv-list}. \end{tsremark} \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,no index]{\tsobj [code] {macro-list}} \tsobj[code,no index]{\tsargs [oarg] {oargs-list}} \tsobj[code,no index]{\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. \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,codeprefix={},resultprefix={}]{demo.remark} \end{codedescribe} \subsection{Auxiliary Commands and Environment}\label{aux-commands} In case the Document Class being used redefines the \tsobj[code,no index]{\maketitle} command and/or \tsobj[env,no index]{abstract} environment, alternatives are provided (based on the article class). \begin{codedescribe}[code,index group=Test]{\typesettitle,\tstitle} \begin{codesyntax} \tsmacro{\typesettitle}{title-keys} \tsmacro{\tstitle}{title-keys} \end{codesyntax} This is based on the \tsobj[code,no index]{\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,no index]{\footnote} command in it.} \describe{date}{Title's date.} \end{describelist*} \begin{tsremark} The \tsobj[code,no index]{\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,index group=Test]{tsabstract} \begin{codesyntax} \tsmacro{\begin{tsabstract}}{} \ldots \tsmacro{\end{tsabstract}}{} \end{codesyntax} This is the \tsobj[env,no index]{abstract} environment from the \tsobj[pkg]{article} class. \end{codedescribe} \begin{codedescribe}[code,new=2023/05/16,index group=Test]{\typesetdate,\tsdate} \begin{codesyntax} \tsmacro{\typesetdate}{} \tsmacro{\tsdate}{} \end{codesyntax} This provides the current date (in Month Year format). \end{codedescribe} \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,no index} \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 %\printindex \end{document}