diff options
author | Norbert Preining <norbert@preining.info> | 2023-05-17 03:01:58 +0000 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2023-05-17 03:01:58 +0000 |
commit | 92ffb9032b85f818a8d3b469ad4d3889c2a44ba1 (patch) | |
tree | 54bc1ce009357117a376baa5ffa223f904acee4f /macros/latex/contrib/codedescribe | |
parent | 95bdae3d8a40af1f2f82f786dc29d3761fe431f1 (diff) |
CTAN sync 202305170301
Diffstat (limited to 'macros/latex/contrib/codedescribe')
-rw-r--r-- | macros/latex/contrib/codedescribe/README.md | 7 | ||||
-rw-r--r-- | macros/latex/contrib/codedescribe/doc/codedescribe.pdf | bin | 246809 -> 250689 bytes | |||
-rw-r--r-- | macros/latex/contrib/codedescribe/doc/codedescribe.tex | 221 | ||||
-rw-r--r-- | macros/latex/contrib/codedescribe/latex/codedescribe.sty | 845 | ||||
-rw-r--r-- | macros/latex/contrib/codedescribe/latex/codelisting.sty | 50 |
5 files changed, 652 insertions, 471 deletions
diff --git a/macros/latex/contrib/codedescribe/README.md b/macros/latex/contrib/codedescribe/README.md index 8045a1a210..ee3db68821 100644 --- a/macros/latex/contrib/codedescribe/README.md +++ b/macros/latex/contrib/codedescribe/README.md @@ -86,5 +86,10 @@ The Current Maintainer of this work is Alceu Frigeri ## Changelog -* Version 1.0 (this) +* Version 1.1 (this) + - Added two commands to allow <obj-types> customization + - requiring (now) pifont for EXP/rEXP <format-keys> + - Added a date command (auxiliary command) + +* Version 1.0 - Initial release by CTAN diff --git a/macros/latex/contrib/codedescribe/doc/codedescribe.pdf b/macros/latex/contrib/codedescribe/doc/codedescribe.pdf Binary files differindex 882a93affd..9e2924847f 100644 --- a/macros/latex/contrib/codedescribe/doc/codedescribe.pdf +++ b/macros/latex/contrib/codedescribe/doc/codedescribe.pdf diff --git a/macros/latex/contrib/codedescribe/doc/codedescribe.tex b/macros/latex/contrib/codedescribe/doc/codedescribe.tex index b16853b40a..4b2a03ecbe 100644 --- a/macros/latex/contrib/codedescribe/doc/codedescribe.tex +++ b/macros/latex/contrib/codedescribe/doc/codedescribe.tex @@ -2,7 +2,7 @@ % !TEX ext = --interaction=nonstopmode --enable-etex --enable-write18 % !BIB program = none %%%============================================================================== -%% Copyright 2022 by Alceu Frigeri +%% Copyright 2023 by Alceu Frigeri %% %% This work may be distributed and/or modified under the conditions of %% @@ -15,15 +15,15 @@ %% %% The Current Maintainer of this work is Alceu Frigeri %% -%% This is version 1.0 (2023/05/11) +%% This is version 1.1 (2023/05/16) %% %% The list of files that compose this work can be found in the README.md file at -%% https://ctan.org/pkg/democodetools +%% https://ctan.org/pkg/codedescribe %% %%%============================================================================== %\documentclass[dctools,english]{ufrgscca} \documentclass{article} -\RequirePackage[verbose,a4paper,marginparwidth=27.5mm,top=2.5cm,bottom=1.5cm,hmargin={40mm,20mm},marginparsep=2.5mm,columnsep=10mm,asymmetric]{geometry} +\RequirePackage[verbose,a4paper,marginparwidth=28mm,top=3cm,bottom=1.5cm,hmargin={45mm,25mm},marginparsep=2.5mm,columnsep=10mm,asymmetric]{geometry} \usepackage{codedescribe} \usepackage{enumitem} @@ -34,13 +34,13 @@ \tstitle{ author={Alceu Frigeri\footnote{\tsverb{https://github.com/alceu-frigeri/codedescribe}}}, - date={2023/05/11}, - title={The codedescribe and codelisting Packages\break Version \PkgInfo{codedesc}{version}} + date={\tsdate}, + title={The codedescribe and codelisting Packages\break Version \PkgInfo{codedescribe}{version}} } \begin{typesetabstract} -This documentation package is designed to be `as class independent as possible', depending only on \tsobj[pkg]{expl3,scontents,listing}. 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). +This documentation package is designed to be `as class independent as possible', depending only on \tsobj[pkg]{expl3,scontents,listing,pifont}. Unlike other packages of the kind, a minimal set of macros/commands/environments is defined: most/all defined commands have an 'object type' as a \tsobj[key]{keyval} parameter, allowing for an easy expansion mechanism (instead of the usual 'one set of macros/environments' for each object type). No assumption about page layout is made (besides `having a marginpar'), or underlying macros, so that it can be used with any document class. @@ -48,11 +48,10 @@ No assumption about page layout is made (besides `having a marginpar'), or unde \tableofcontents -%\setcodefmt{fontsize=\large} - \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 are used to typeset code snippets. + +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 are used to typeset code snippets. The package \tsobj[pkg]{pifont} is needed just to typeset those (open)stars, in case one wants to mark a command as (restricted) expandable. No other package/class is needed, any class can be used as the base one, which allows to demonstrate the documented commands with any desired layout. @@ -63,7 +62,7 @@ No other package/class is needed, any class can be used as the base one, which a This package 'can' be used with multi-column classes, given that the \tsobj[code]{\linewidth,\columnsep} are defined appropriately. \tsobj{\linewidth} shall defaults to text/column real width, whilst \tsobj{\columnsep}, if needed (2 or more columns) shall be greater than \tsobj{\marginparwidth} plus \tsobj{\marginparsep}. \subsection{Current Version} -This doc regards to \tsobj[pkg]{codedescribe} version \PkgInfo{codedesc}{version}~ and \tsobj[pkg]{codelisting} version \PkgInfo{codedesc}{version}. Those two packages are fairly stable, and given the \tsobj[meta]{obj-type} mechanism (see below, \ref{obj-type-def}) it can be easily extended without changing it's interface. +This doc regards to \tsobj[pkg]{codedescribe} version \PkgInfo{codedescribe}{version}~ and \tsobj[pkg]{codelisting} version \PkgInfo{codelisting}{version}. Those two packages are fairly stable, and given the \tsobj[meta]{obj-type} mechanism (see below, \ref{obj-type-def}) it can be easily extended without changing it's interface. \section{codelisting Package} @@ -84,7 +83,19 @@ This environment is an alias to \tsobj[env]{scontents} environment (from \tsobj[ -\subsection{Code Display/Demo} +\subsection{Code Display/Demo}\label{codelist} + +\begin{codedescribe}{\setcodekeys} + \begin{codesyntax}% + \tsmacro{\setcodekeys}{code-keys} + \end{codesyntax} + +One has the option to set \tsmeta{code-keys} (see \ref{code-keys}) per \tsmacro{\tscode}{}/\tsmacro{\tsdemo}{} call, 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}{\tscode*,\tsdemo*} \begin{codesyntax}% \tsmacro{\tscode*}[code-keys]{st-name} @@ -99,38 +110,21 @@ This environment is an alias to \tsobj[env]{scontents} environment (from \tsobj[ For Example: \begin{codestore}[st=democodestore] - \begin{codestore}[stmeta] +\begin{codestore}[stmeta] Some \LaTeX~coding, for example: \ldots. - \end{codestore} - +\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, +\tsdemo[numbers=left,ruleht=0.5, codeprefix={inner sample code}, resultprefix={inner sample result}] {stmeta} \end{codestore} - \tsdemo*[emph2={tscode,tsdemo},emph={stmeta},keywd2={codestore}]{democodestore} -\begin{codedescribe}{\setcodekeys} - \begin{codesyntax}% - \tsmacro{\setcodekeys}{code-keys} - \end{codesyntax} - -Instead of setting/defining \tsmeta{code-keys} per \tsmacro{\tscode}{}/\tsmacro{\tsdemo}{} call, one can set those \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} - - -\subsubsection{Code Keys} +\subsubsection{Code Keys}\label{code-keys} Using a \tsobj[key]{key}\,=\tsobj[value]{value} syntax, one can fine tune \tsobj[pkg]{listings} syntax highlight. \begin{codedescribe}[key]{settexcs,texcs,texcsstyle} @@ -142,6 +136,7 @@ Using a \tsobj[key]{key}\,=\tsobj[value]{value} syntax, one can fine tune \tsobj Those define sets of \LaTeX~commands (csnames), the \tsobj[key]{set} variants initialize/redefine those sets (an empty list, clears the set), while the others extend those sets. The \tsobj[key]{style} ones redefines the command display style (an empty \tsobj[meta]{value} resets the style to it's default).\\ \end{codedescribe} + \begin{codedescribe}[key]{setkeywd,keywd,keywdstyle} \begin{codesyntax} % \tsobj[key]{setkeywd,setkeywd2,setkeywd3} @@ -192,10 +187,10 @@ those set the \tsobj[key]{codeprefix} (default: \LaTeX~Code:) and \tsobj[key]{re \begin{codesyntax} % \tsobj[key]{parindent} \end{codesyntax} -Sets the indentation to be used when 'demonstrating' \LaTeXe code (\tsobj[code]{\tsdemo}). Defaults to whatever value \tsobj[code]{\parindent} was when the package was first loaded. +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{codedescribe}[key]{ruleht}%-very-long-long-long,xyz,xyh,kjh,ljd,kls} \begin{codesyntax} % \tsobj[key]{ruleht} \end{codesyntax} @@ -203,90 +198,139 @@ When typesetting the 'code demo' (\tsobj{\tsdemo}) a set of rules is drawn. The \end{codedescribe} - \section{codedescribe Package} This package aims at minimizing the number of commands, having the object kind (if a macro, or a function, or environment, or variable, or key ...) as 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} It has a single package option: + \begin{describelist}{option} \describe{nolisting}{it will suppress the \tsobj[pkg]{codelisting} package load. In case it's not necessary or one wants to use a differen package for \LaTeX\ code listing.} \end{describelist} -\subsection{\tsobj[oarg]{obj-type} keys}\label{obj-type-def} +\subsection{Object Type keys}\label{obj-type-def} + +The applied text format is defined in terms of \tsobj[arg]{obj-types}, which are defined in terms of \tsobj[arg]{format-groups} and each one defines a 'formatting function', 'font shape', bracketing, etc. to be applied. + +\subsubsection{Format Keys}\label{format-keys} +There is a set of primitive \tsobj[arg]{format-keys} used to define \tsobj[arg]{format-groups,obj-types}, which are: + +\begin{describelist*}{keys} + \describe {meta} { to typeset between angles,} + \describe {xmeta} { to typeset *verbatim* between angles,} + \describe {verb} { to typeset *verbatim*,} + \describe {xverb} { to typeset *verbatim*, suppressing all spaces,} + \describe {code} { to typeset *verbatim*, suppressing all spaces and replacing a TF by \underline{TF},} + \describe {nofmt} { in case of a redefinition, to remove the 'base' formatting,} + \describe {slshape} { to use a slanted font shape,} + \describe {itshape} { to use an italic font shape,} + \describe {noshape} { in case of a redefinition, to remove the 'base' shape,} + \describe {lbracket} { defines the left bracket (when using \tsobj{\tsargs}). \textbf{Note:} this key must have an associated value,} + \describe {rbracket} { defines the right bracket (when using \tsobj{\tsargs}). \textbf{Note:} this key must have an associated value,} + \describe {color} { defines the text color. \textbf{Note:} this key must have an associated value (a color, as understood by \tsobj[pkg]{xcolor} package).} +\end{describelist*} + +\subsubsection{Format Groups} +Using \tsobj{\defgroupfmt} one can (re-)define custom \tsobj[arg]{format-groups}. There is, though, a set of pre-defined ones as follow: + +\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. +\end{tsremark} + +\subsubsection{Object Types} +Using \tsobj{\defobjectfmt} one can (re-)define custom \tsobj[arg]{obj-types}. +Similarly, there is a set of predefined ones, as follow: +\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*} -The current known Object Types (keys) are: -\begin{itemize}[noitemsep] -\item \tsobj[keys]{meta} for a 'general' case, -\item \tsobj[keys]{arg,marg,oarg,parg,xarg} for commands/functions arguments, -\item \tsobj[keys]{code,macro,function} for macros in general, -\item \tsobj[keys]{syntax} to describe/typeset code syntax, -\item \tsobj[keys]{key,keys,keyval,value,defaultval} to list keys, values, etc., -\item \tsobj[keys]{option} for package/macros options, -\item \tsobj[keys]{env} for environments, -\item \tsobj[keys]{pkg,pack} for packages. -\end{itemize} -% Besides those, for \tsmacro{\tsobj}{} one has \tsobj[keys]{sep,comma} keys to change the last 'connector term' (default: and) and \tsobj[keys]{rulecolor,new,update,note} to customize the \tsobj[env]{codedescribe} environment. -The format's defaults can be changed with \tsobj{\setcodefmt} +\subsubsection{Customization}\label{format-custom} -\begin{codedescribe}[code]{\setcodefmt} +One can add user defined groups/objects or change the pre-defined ones with the following commands: + + +\begin{codedescribe}[code,new=2023/05/16]{\defgroupfmt} \begin{codesyntax} % - \tsmacro{\setcodefmt}{fmt-keys} + \tsmacro{\defgroupfmt}{format-group,format-keys} \end{codesyntax} -\tsobj[marg]{fmt-keys} are basically the same as above: -\begin{itemize}[noitemsep] - \item To change default colors: (note each group defines a single entry/alias) - \begin{itemize}[noitemsep] -\item \tsobj[keys,sep=or]{meta,marg,arg} , -\item \tsobj[keys,sep=or]{oarg,parg,xarg} , -\item \tsobj[keys,sep=or]{code,macro,function} , -\item \tsobj[keys,sep=or]{syntax} , -\item \tsobj[keys,sep=or]{key,keys,keyval,value} , -\item \tsobj[keys,sep=or]{defaultval} , -\item \tsobj[keys,sep=or]{option} , -\item \tsobj[keys,sep=or]{env} , -\item \tsobj[keys,sep=or]{pkg,pack} , -\item \tsobj[keys,sep=or]{allcolors} to set all colors at once, single value. - \end{itemize} -\item others - \begin{itemize} - \item \tsobj[keys]{font} to change font (default: \tsobj{\ttfamily}) - \item \tsobj[keys]{fontsize} to change size (default: \tsobj{\small}) - \item \tsobj[keys]{fontshape} to change the used 'slshape' (default: \tsobj{\slshape}) - \end{itemize} -\end{itemize} +\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 defined in \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. \tsobj[marg]{format-keys} allows for further differentiation. \end{codedescribe} +For instance, the many optional \tsobj[arg]{*arg} are defined as follow: +\begin{codestore}[demo.fmtdef] +\colorlet {c__codedesc_oarg_color} { gray!90!black } +\defgroupfmt {oarg} { meta , color=c__codedesc_oarg_color } +\defobjectfmt {oarg} {oarg} { lbracket={[} , rbracket={]} } +\defobjectfmt {parg} {oarg} { lbracket={(} , rbracket={)} } +\defobjectfmt {xarg} {oarg} { lbracket={<} , rbracket={>} } +\end{codestore} +\tscode*[codeprefix=~,keywd={oarg,arg,parg,xarg},keywd2={meta,color},emph={lbracket,rbracket}]{demo.fmtdef} \subsection{Environments} + \begin{codedescribe}[env,new=2023/05/01,update=2023/05/1,note={this is an example}]{codedescribe} \begin{codesyntax} \tsmacro{\begin{codedescribe}}[obj-type]{csv-list} \ldots \tsmacro{\end{codedescribe}}{} -\end{codesyntax} +\end{codesyntax}[Note 1:] This is the main environment to describe \tsobj[env]{Macros, Functions, Variable, Environments, etc.} \tsobj[meta]{csv-list} is typeset in the margin. The optional \tsobj[oarg]{obj-type} defines the object-type format. \end{codedescribe} \begin{tsremark} One can change the rule color with the key \tsobj[keys]{rulecolor}, for instance \tsmacro{\begin{codedescribe}[rulecolor=white]}{} will remove the rules. \end{tsremark} -\begin{tsremark} +\begin{tsremark}[Note 2:] Besides that, one can use the keys \tsobj[keys]{new,update,note} to further customize it as: \tsverb{\begin{codedescribe}[new=2023/05/01,update=2023/05/1,note={this is an example}]} \end{tsremark} +\begin{tsremark}[Note 3:] +Finally, one can use \tsobj[key]{EXP,rEXP} to add a star \ding{72} or a hollow star \ding{73}, as per expl3/doc3 conventions (if expandable, restricted expandable or not). +\end{tsremark} \begin{codedescribe}[env]{codesyntax} \begin{codesyntax} \tsmacro{\begin{codesyntax}}{} +\ldots +\tsmacro{\end{codesyntax}}{} \end{codesyntax} The \tsobj[env]{codesyntax} environment sets the fontsize and activates \tsmacro{\obeylines,\obeyspaces}{}, so one can list macros/cmds/keys use, one per line. - \end{codedescribe} - \begin{tsremark} \tsobj[env]{codesyntax} environment shall appear only once, inside of a \tsobj[env]{codedescribe} environment. Take note, as well, this is not a verbatim environment! %\begin{describelist*}{code} @@ -341,7 +385,7 @@ This is the \tsobj[env]{describelist} companion macro. In case of the \tsobj[env \tsmacro{\typesetobj}[obj-type]{csv-list} \tsmacro{\tsobj}[obj-type]{csv-list} \end{codesyntax} -It can be used to typeset a single 'object' or a list thereof. In the case of a list, each term will be separated by commas. The last two by \tsobj[key]{sep} (defaults to: and). +This is the main typesetting command (most of the others are based on this). It can be used to typeset a single 'object' or a list thereof. In the case of a list, each term will be separated by commas. The last two by \tsobj[key]{sep} (defaults to: and). \end{codedescribe} \begin{tsremark} One can change the last 'separator' with the key \tsobj[keys]{sep}, for instance \tsverb[code]{\tsobj[env,sep=or] {}} (in case one wants to produce an 'or' list of environments). Additionally, one can use the key \tsobj[keys]{comma} to change the last separator to a single comma, like \tsverb[code]{\tsobj[env,comma] {}}. @@ -352,7 +396,7 @@ One can change the last 'separator' with the key \tsobj[keys]{sep}, for instance \tsmacro{\typesetargs}[obj-type]{csv-list} \tsmacro{\tsargs}[obj-type]{csv-list} \end{codesyntax} - Those 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 braces used: \tsverb{[]} for optional arguments (oarg), \tsverb{{}} for mandatory arguments (marg), and so on. + Those 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} @@ -377,8 +421,12 @@ This is just a short-cut for\par \tsobj[code]{\tsobj [code] {macro-list}} \tsobj \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. + 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{something} can contain commas (which, otherwise, would be interpreted as a list separator in \tsobj{\tsobj}. \end{codedescribe} +\begin{tsremark} +This is meant to short expressions, and not multi-line, complex code (one is better of, then, using \ref{codelist}). \tsobj[meta]{verbatim text} must be balanced ! otherwise, some low level \TeX\ errors may pop out. +\end{tsremark} + \begin{codedescribe}[code]{\typesetmarginnote,\tsmarginnote} \begin{codesyntax} @@ -390,7 +438,7 @@ Typesets a small note at the margin. \begin{codedescribe}[env]{tsremark} \begin{codesyntax} -\tsmacro{\begin{tsremark}[NB]}{} +\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: @@ -403,7 +451,7 @@ Typesets a small note at the margin. \tsdemo{demo.remark} \end{codedescribe} -\subsection{Auxiliar Command / Environment} +\subsection{Auxiliary Command / Environment} In case the used Document Class 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} @@ -429,5 +477,12 @@ This is based on the \tsobj[code]{\maketitle} from the \tsobj[pkg]{article} clas 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 (Month Year, format). +\end{codedescribe} \end{document}
\ No newline at end of file diff --git a/macros/latex/contrib/codedescribe/latex/codedescribe.sty b/macros/latex/contrib/codedescribe/latex/codedescribe.sty index 370f01ba82..a260c0d422 100644 --- a/macros/latex/contrib/codedescribe/latex/codedescribe.sty +++ b/macros/latex/contrib/codedescribe/latex/codedescribe.sty @@ -12,7 +12,7 @@ %% %% The Current Maintainer of this work is Alceu Frigeri %% -%% This is version 1.0.1beta (2023/05/11) +%% This is version 1.1 (2023/05/16) %% %% The list of files that compose this work can be found in the README.md file at %% https://ctan.org/pkg/codedescribe @@ -22,33 +22,37 @@ \RequirePackage{ expl3 } \ProvidesExplPackage {codedescribe} - {2023/05/11} - {1.0} + {2023/05/16} + {1.1} {LaTeX Code Description/Documentation} -\prop_if_exist:NTF \g__codedesc_pkg_prop - {} - { \prop_new:N \g__codedesc_pkg_prop } - -\prop_put_from_keyval:Nn \g__codedesc_pkg_prop +%%%%%%% +%%% +%%% Just an attempt of having my packages info in a regular way +%%% Idea being: { <pck-name> / pkg info } for each and all. +%%% +%%%%%%% +\keys_define:nn { codedescribe / pkg info} { - codedesc . name = codedescribe , - codedesc . prefix = codedesc , - codedesc . date = 2023/05/11 , - codedesc . version = 1.0 , - codedesc . description = LaTeX Code Description/Documentation + name .code:n = codedescribe , + prefix .code:n = codedesc , + date .code:n = 2023/05/16 , + version .code:n = 1.1 , + description .code:n = \LaTeX~Code~Description/Documentation } - -\cs_gset:Npn \__codedesc_pkg_info:nn #1#2 +\cs_if_exist:NF \__codedesc_pkg_info:nn { - \prop_item:Nn \g__codedesc_pkg_prop {#1.#2} + \cs_new_protected:Npn \__codedesc_pkg_info:nn #1#2 + { \keys_set:nn {#1 / pkg info}{#2} } } +\cs_if_exist:NF \PkgInfo + { \NewDocumentCommand \PkgInfo {mm} { \keys_set:nn {#1 / pkg info}{#2} } } +%%%%%%% +%%% End of cut-n-paste +%%%%%%% + + -\cs_if_exist:NTF \PkgInfo - {} - { - \NewDocumentCommand \PkgInfo {mm} { \prop_item:Nn \g__codedesc_pkg_prop {#1.#2} } - } \use:c {@reversemargintrue} @@ -58,20 +62,55 @@ \keys_define:nn { codedescribe } { - nolisting.usage:n = general, + nolisting.usage:n = load, nolisting.bool_set_inverse:N = \l__codedesc_loadlisting_bool, nolisting.default:n = {true}, } \ProcessKeyOptions [codedescribe ] +%% bbding is need for those hollow stars... \RequirePackage{xcolor} +\RequirePackage{pifont} \bool_if:nT {\l__codedesc_loadlisting_bool} { \RequirePackage{codelisting} } + \cs_generate_variant:Nn \tl_set:Nn {Ne} +\cs_generate_variant:Nn \keys_set:nn {ne} +\cs_generate_variant:Nn \keys_define:nn {ne} +\cs_generate_variant:Nn \tl_to_str:n {o , e} + + +\msg_new:nnnn {codedesc} {format-err} + { + (ID:#1)~Format~Key~(#2)~not~defined! + } + { + You~tried~to~use~a~non~defined~format~key:#2. + ~Error~Code~ ID:<#1>. + } + +\msg_new:nnnn {codedesc} {group-err} + { + (ID:#1)~Format~group~(#2)~not~defined! + } + { + You~tried~to~use~a~non~defined~format~group:#2. + ~Error~Code~ ID:<#1>. + } + +\msg_new:nnnn {codedesc} {object-err} + { + (ID:#1)~Objetc~Type~(#2)~not~defined! + } + { + You~tried~to~use~a~non~defined~object~type:#2. + ~Error~Code~ ID:<#1>. + } + @@ -99,7 +138,7 @@ \dim_new:N \l__codedesc_linewidth_dim \dim_new:N \l__codedesc_textcolwidth_dim -\cs_new:Npn \__codedesc_set_textcolwidth: +\cs_new_protected:Npn \__codedesc_set_textcolwidth: { \dim_compare:nNnTF {\linewidth} = {\l__codedesc_linewidth_dim} {} @@ -113,246 +152,309 @@ } -\colorlet{c__codedesc_none_color}{red!70!black} -\bool_new:N \l__codedesc_descnotes_bool -\bool_new:N \l__codedesc_descdate_new_bool -\tl_new:N \l__codedesc_descdate_new_tl -\bool_new:N \l__codedesc_descdate_update_bool -\tl_new:N \l__codedesc_descdate_update_tl -\bool_new:N \l__codedesc_sidenote_bool -\tl_new:N \l__codedesc_sidenote_tl -\cs_new:Npn \__codedesc_keysmetadefaults:nn #1#2 +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + + + +\keys_define:nn { codedesc / scratch_def } +{ + meta.usage:n = general , + meta .value_forbidden:n = true , + meta .code:n ={ \tl_set:Nn \l__codedesc_tmpfmt_tl {meta} } , + + xmeta.usage:n = general , + xmeta .value_forbidden:n = true , + xmeta .code:n ={ \tl_set:Nn \l__codedesc_tmpfmt_tl {xmeta} } , + + code.usage:n = general , + code .value_forbidden:n = true , + code .code:n ={ \tl_set:Nn \l__codedesc_tmpfmt_tl {code} } , + + verb.usage:n = general , + verb .value_forbidden:n = true , + verb .code:n ={ \tl_set:Nn \l__codedesc_tmpfmt_tl {verb} } , + + xverb.usage:n = general , + xverb .value_forbidden:n = true , + xverb .code:n ={ \tl_set:Nn \l__codedesc_tmpfmt_tl {xverb} } , + + nofmt.usage:n = general , + nofmt .value_forbidden:n = true , + nofmt .code:n = {\tl_clear:N \l__codedesc_tmpfmt_tl } , + + slshape.usage:n = general , + slshape .value_forbidden:n = true , + slshape .code:n ={ \tl_set:Nn \l__codedesc_tmpshape_tl { slshape} } , + + itshape.usage:n = general , + itshape .value_forbidden:n = true , + itshape .code:n ={ \tl_set:Nn \l__codedesc_tmpshape_tl { itshape} } , + + noshape.usage:n = general , + noshape .value_forbidden:n = true , + noshape .code:n ={ \tl_clear:N \l__codedesc_tmpshape_tl } , + + color.usage:n = general , + color .value_required:n = true , + color.code:n = { \tl_set:Nn \l__codedesc_tmpcolor_tl { #1 } } , + + lbracket .usage:n = general , + lbracket .value_required:n = true , + lbracket .code:n = { \tl_set:Nn \l__codedesc_tmplbracket_tl { #1 } } , + + rbracket .usage:n = general , + rbracket .value_required:n = true , + rbracket .code:n = { \tl_set:Nn \l__codedesc_tmprbracket_tl { #1 } } , + + unknown.code:n = + { + \msg_error:nnxx { codedesc } {format-err} {format}{\l_keys_key_str} + }, + +} + + +\keys_define:nn { codedesc / grp_scratch } { - \tl_if_blank:nTF {#2} - { \keys_set:nn {codedesc / defaults} { #1 } } - { \keys_set:nn {codedesc / defaults} { #1 = {#2} } } + unknown .code:n = {} } -\keys_define:nn { codedesc / defaults } -{ - meta.usage:n = general, - meta.code:n = { \colorlet{c__codedesc_marg_color}{#1} } , - meta.default:n = { gray!60!black } , - % - marg.usage:n = general, - marg.code:n = { \__codedesc_keysmetadefaults:nn {meta}{#1} } , - % - arg.usage:n = general, - arg.code:n = { \__codedesc_keysmetadefaults:nn {meta}{#1} } , - % +\cs_new_protected:Npn \__codedesc_group_define:nn #1#2 + { + \tl_clear:N \l__codedesc_tmpfmt_tl + \tl_clear:N \l__codedesc_tmpshape_tl + \tl_clear:N \l__codedesc_tmpcolor_tl + \tl_clear:N \l__codedesc_tmplbracket_tl + \tl_clear:N \l__codedesc_tmprbracket_tl + + \keys_set:nn { codedesc / grp_scratch } {#1} + \keys_set:nn { codedesc / scratch_def } {#2} + + \tl_clear:N \l_tmpa_tl + \tl_clear:N \l_tmpb_tl + \tl_if_empty:NF \l__codedesc_tmpfmt_tl + { + \tl_put_right:No \l_tmpa_tl{\l__codedesc_tmpfmt_tl} + \tl_set:Nn \l_tmpb_tl { , } + } + \tl_if_empty:NF \l__codedesc_tmpshape_tl + { + \tl_put_right:No \l_tmpa_tl{ \l_tmpb_tl } + \tl_put_right:No \l_tmpa_tl{\l__codedesc_tmpshape_tl} + \tl_set:Nn \l_tmpb_tl { , } + } + \tl_if_empty:NF \l__codedesc_tmpcolor_tl + { + \tl_put_right:No \l_tmpa_tl{ \l_tmpb_tl } + \tl_put_right:Nn \l_tmpa_tl{ color = } + \tl_put_right:No \l_tmpa_tl{ \l__codedesc_tmpcolor_tl} + \tl_set:Nn \l_tmpb_tl { , } + } + \tl_if_empty:NF \l__codedesc_tmplbracket_tl + { + \tl_put_right:No \l_tmpa_tl{ \l_tmpb_tl } + \tl_put_right:Nn \l_tmpa_tl{ lbracket = } + \tl_put_right:No \l_tmpa_tl{ \l__codedesc_tmplbracket_tl} + \tl_set:Nn \l_tmpb_tl { , } + } + \tl_if_empty:NF \l__codedesc_tmprbracket_tl + { + \tl_put_right:No \l_tmpa_tl{ \l_tmpb_tl } + \tl_put_right:Nn \l_tmpa_tl{ rbracket = } + \tl_put_right:No \l_tmpa_tl{ \l__codedesc_tmprbracket_tl} +% \tl_set:Nn \l_tmpb_tl { , } + } + + \keys_define:ne { codedesc / grp_scratch } { #1 .meta:nn = { codedesc / scratch_def } { \l_tmpa_tl} } + \keys_define:ne { codedesc / grp_fmt } { #1 .meta:nn = { codedesc / base_fmt } { \l_tmpa_tl} } + } - oarg.usage:n = general, - oarg.code:n = { \colorlet{c__codedesc_oarg_color}{#1} } , - oarg.default:n = { gray!90!black } , - % - parg.usage:n = general, - parg.code:n = { \__codedesc_keysmetadefaults:nn {oarg}{#1} } , - % - xarg.usage:n = general, - xarg.code:n = { \__codedesc_keysmetadefaults:nn {oarg}{#1} } , - % - code.usage:n = general, - code.code:n = { \colorlet{c__codedesc_code_color}{#1} } , - code.default:n = { blue!40!black } , - % - macro.usage:n = general, - macro.code:n = { \__codedesc_keysmetadefaults:nn {code}{#1} } , - % - function.usage:n = general, - function.code:n = { \__codedesc_keysmetadefaults:nn {code}{#1} } , - % - syntax.usage:n = general, - syntax.code:n = { \colorlet{c__codedesc_syntax_color}{#1} } , - syntax.default:n = { blue!60!black } , - % - keyval.usage:n = general, - keyval.code:n = { \colorlet{c__codedesc_keyval_color}{#1} } , - keyval.default:n = { teal!40!black } , - % - key.usage:n = general, - key.code:n = { \__codedesc_keysmetadefaults:nn {keyval}{#1} } , - % - keys.usage:n = general, - keys.code:n = { \__codedesc_keysmetadefaults:nn {keyval}{#1} } , - % - value.usage:n = general, - value.code:n = { \__codedesc_keysmetadefaults:nn {keyval}{#1} } , - % +\keys_define:nn { codedesc / grp_fmt } + { + unknown .code:n = \msg_error:nnxx { codedesc } {group-err} {grpfmt}{\l_keys_key_str} + } - option.usage:n = general, - option.code:n = { \colorlet{c__codedesc_options_color}{#1} } , - option.default:n = { green!30!black } , - % - defaultval.usage:n = general, - defaultval.code:n = { \colorlet{c__codedesc_defaultval_color}{#1} } , - defaultval.default:n = { blue!60!black } , - % +\cs_new_protected:Npn \__codedesc_object_define:nnn #1#2#3 + { + \tl_if_blank:nTF {#3} + { + \keys_define:nn { codedesc / format } + { #1 .meta:nn = { codedesc / grp_fmt } { #2 } } + } + { + \__codedesc_group_define:nn { #1_objfmt } {#3} + \keys_define:nn { codedesc / format } + { #1 .meta:nn = { codedesc / grp_fmt } { #2 , #1_objfmt} } + } + } - env.usage:n = general, - env.code:n = { \colorlet{c__codedesc_env_color}{#1} } , - env.default:n = { green!30!black } , - % - pkg.usage:n = general, - pkg.code:n = { \colorlet{c__codedesc_pkg_color}{#1} } , - pkg.default:n = { green!30!black } , - % - pack.usage:n = general, - pack.code:n = { \__codedesc_keysmetadefaults:nn {pkg}{#1} } , - % - - allcolors.usage:n = general, - allcolors.meta:n = - { - meta = {#1} , - oarg = {#1} , - code = {#1} , - syntax = {#1} , - keyval = {#1} , - option = {#1} , - defaultval = {#1} , - env = {#1} , - pkg = {#1} , - } , - allcolors.default:n = { black } , - - font.usage:n = general , - font.code:n = { \tl_set:Nn \__codedesc_metafont_tl: {#1} } , - font.default:n = { \ttfamily } , - - fontsize.usage:n = general , - fontsize.code:n = { \tl_set:Nn \__codedesc_metasize_tl: {#1} } , - fontsize.default:n = { \small } , +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - fontshape.usage:n = general , - fontshape.code:n = { \tl_set:Nn \__codedesc_slshape_tl: {#1} } , - fontshape.default:n = { \slshape } , + - setdefaults.usage:n = general , - setdefaults.meta:n = { meta, oarg, code, syntax, keyval, option, defaultval, env, pkg , font, fontsize, fontshape} , +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - unknown.usage:n = general, - unknown.code:n = - { }, % unknown keys are silently ignored... -} +\tl_set:Nn \__codedesc_metasize_tl: {\small} +\tl_set:Nn \__codedesc_metafont_tl: {\ttfamily} -\keys_set:nn {codedesc / defaults}{setdefaults} -\NewDocumentCommand \setcodefmt {m} { \keys_set:nn {codedesc / defaults}{#1}} + \colorlet{c__codedesc_none_color}{red!70!black} -\keys_define:nn { codedesc / format } -{ - meta.usage:n = general, - meta.code:n = - { - \tl_set:Nn \__codedesc_metacolor_tl: { \color{c__codedesc_marg_color} } - \tl_set:Nn \__codedesc_typeset_tl:n { \__codedesc_meta:n } - \tl_set:Nn \__codedesc_typeset_tl:o { \__codedesc_meta:o } - }, - marg.usage:n = general, - marg.meta:n = { meta } , - % - % - arg.usage:n = general, - arg.meta:n = { meta } , - % + \colorlet{c__codedesc_verb_color}{ black } +\__codedesc_group_define:nn {verb} {color=c__codedesc_verb_color} +\__codedesc_object_define:nnn {verb}{verb}{verb} +\__codedesc_object_define:nnn {xverb}{verb}{xverb} - oarg.usage:n = general, - oarg.code:n = - { - \tl_set:Nn \__codedesc_metacolor_tl: { \color{c__codedesc_oarg_color} } - \tl_set:Nn \__codedesc_typeset_tl:n { \__codedesc_meta:n } - \tl_set:Nn \__codedesc_typeset_tl:o { \__codedesc_meta:o } - }, - % - parg.usage:n = general, - parg.meta:n = { oarg } , - % - xarg.usage:n = general, - xarg.meta:n = { oarg } , - % + \colorlet{c__codedesc_marg_color}{ gray!60!black } +\__codedesc_group_define:nn {meta} {meta,color=c__codedesc_marg_color} +\__codedesc_object_define:nnn {meta}{meta}{} +\__codedesc_object_define:nnn {arg}{meta}{} +\__codedesc_object_define:nnn {marg}{meta}{lbracket={\{},rbracket={\}}} - code.usage:n = general, - code.code:n = - { - \tl_set:Nn \__codedesc_metacolor_tl: { \color{c__codedesc_code_color} } - \tl_set:Nn \__codedesc_typeset_tl:n { \__codedesc_macro_typeset:n } - \tl_set:Nn \__codedesc_typeset_tl:o { \__codedesc_macro_typeset:o } - }, - % - macro.usage:n = general, - macro.meta:n = { code } , - % - function.usage:n = general, - function.meta:n = { code } , - % + \colorlet{c__codedesc_oarg_color}{ gray!90!black } +\__codedesc_group_define:nn {oarg} {meta,color=c__codedesc_oarg_color} +\__codedesc_object_define:nnn {oarg}{oarg}{lbracket={[},rbracket={]}} +\__codedesc_object_define:nnn {parg}{oarg}{lbracket={(},rbracket={)}} +\__codedesc_object_define:nnn {xarg}{oarg}{lbracket={<},rbracket={>}} - syntax.usage:n = general, - syntax.code:n = - { - \tl_set:Nn \__codedesc_metacolor_tl: { \color{c__codedesc_syntax_color} } - }, - % + \colorlet{c__codedesc_code_color}{ blue!40!black } +\__codedesc_group_define:nn {code} {code,color=c__codedesc_code_color} +\__codedesc_object_define:nnn {code}{code}{} +\__codedesc_object_define:nnn {macro}{code}{} +\__codedesc_object_define:nnn {function}{code}{} +%\__codedesc_group_define:nn {code} {xverb,color=red} - keyval.usage:n = general, - keyval.code:n = - { - \tl_set:Nn \__codedesc_metacolor_tl: { \color{c__codedesc_keyval_color} } - \tl_set:Nn \__codedesc_metashape_tl: { \__codedesc_slshape_tl: } - }, - % - key.usage:n = general, - key.meta:n = { keyval } , - % - keys.usage:n = general, - keys.meta:n = { keyval } , - % - value.usage:n = general, - value.meta:n = { keyval } , - % + \colorlet{c__codedesc_syntax_color}{ blue!60!black } +\__codedesc_group_define:nn {syntax} {color=c__codedesc_syntax_color} +\__codedesc_object_define:nnn {syntax}{syntax}{} - option.usage:n = general, - option.code:n = - { - \tl_set:Nn \__codedesc_metacolor_tl: { \color{c__codedesc_options_color} } - }, - % + \colorlet{c__codedesc_keyval_color}{ teal!40!black } +\__codedesc_group_define:nn {keyval} {slshape,color=c__codedesc_keyval_color} +\__codedesc_object_define:nnn {keyval}{keyval}{} +\__codedesc_object_define:nnn {key}{keyval}{} +\__codedesc_object_define:nnn {keys}{keyval}{} +\__codedesc_object_define:nnn {value}{keyval}{} - defaultval.usage:n = general, - defaultval.code:n = - { - \tl_set:Nn \__codedesc_metacolor_tl: { \color{c__codedesc_defaultval_color} } - }, - % + \colorlet{c__codedesc_options_color}{ green!30!black } +\__codedesc_group_define:nn {option} {color=c__codedesc_options_color} +\__codedesc_object_define:nnn {option}{option}{} + + \colorlet{c__codedesc_defaultval_color}{ blue!60!black } +\__codedesc_group_define:nn {defaultval} {color=c__codedesc_defaultval_color} +\__codedesc_object_define:nnn {defaultval}{defaultval}{} - env.usage:n = general, - env.code:n = + \colorlet{c__codedesc_env_color}{ green!30!black } +\__codedesc_group_define:nn {env} {slshape,color=c__codedesc_env_color} +\__codedesc_object_define:nnn {env}{env}{} + + \colorlet{c__codedesc_pkg_color}{ green!30!black } +\__codedesc_group_define:nn {pkg} {slshape,color=c__codedesc_pkg_color} +\__codedesc_object_define:nnn {pkg}{pkg}{} +\__codedesc_object_define:nnn {pack}{pkg}{} + + + + +\keys_define:nn { codedesc / base_fmt } +{ + meta .usage:n = general , + meta .value_forbidden:n = true , + meta .code:n = { + \tl_set:Nn \__codedesc_typeset_tl:n { \__codedesc_meta:n } + \tl_set:Nn \__codedesc_typeset_tl:o { \__codedesc_meta:o } + } , + + xmeta .usage:n = general , + xmeta .value_forbidden:n = true , + xmeta .code:n = { + \tl_set:Nn \__codedesc_typeset_tl:n { \__codedesc_meta*:n } + \tl_set:Nn \__codedesc_typeset_tl:o { \__codedesc_meta*:o } + } , + + verb .usage:n = general , + verb .value_forbidden:n = true , + verb .code:n = { + \tl_set:Nn \__codedesc_typeset_tl:n { \tl_to_str:n } + \tl_set:Nn \__codedesc_typeset_tl:o { \tl_to_str:o } + } , + + xverb .usage:n = general , + xverb .value_forbidden:n = true , + xverb .code:n = { + \tl_set:Nn \__codedesc_typeset_tl:n { \__codedesc_verb_nospc_typeset:n } + \tl_set:Nn \__codedesc_typeset_tl:o { \__codedesc_verb_nospc_typeset:o } + } , + + code .usage:n = general , + code .value_forbidden:n = true , + code .code:n = { + \tl_set:Nn \__codedesc_typeset_tl:n { \__codedesc_macro_typeset:n } + \tl_set:Nn \__codedesc_typeset_tl:o { \__codedesc_macro_typeset:o } + } , + + slshape .usage:n = general , + slshape .value_forbidden:n = true , + slshape .code:n = { + \tl_set:Nn \__codedesc_metashape_tl: { \slshape} + } , + + itshape .usage:n = general , + itshape .value_forbidden:n = true , + itshape .code:n = { + \tl_set:Nn \__codedesc_metashape_tl: { \itshape } + } , + + lbracket .usage:n = general , + lbracket .value_required:n = true , + lbracket .code:n = { \tl_set:Nn \__codedesc_Lbracket_tl { #1 } } , + + rbracket .usage:n = general , + rbracket .value_required:n = true , + rbracket .code:n = { \tl_set:Nn \__codedesc_Rbracket_tl { #1 } } , + + color .usage:n = general , + color .value_required:n = true , + color .code:n = { + \tl_set:Nn \__codedesc_metacolor_tl: { \color{#1} } + } , +} + +\keys_define:nn { codedesc / format } +{ + EXP.usage:n = general, + EXP.code:n = { - \tl_set:Nn \__codedesc_metacolor_tl: { \color{c__codedesc_env_color} } - \tl_set:Nn \__codedesc_metashape_tl: { \__codedesc_slshape_tl: } + \tl_set:Nn \__codedesc_exp_tl { ~\hfill{\scriptsize\ding{72}} } }, % - - pkg.usage:n = general, - pkg.code:n = + rEXP.usage:n = general, + rEXP.code:n = { - \tl_set:Nn \__codedesc_metacolor_tl: { \color{c__codedesc_pkg_color} } - \tl_set:Nn \__codedesc_metashape_tl: { \__codedesc_slshape_tl: } + \tl_set:Nn \__codedesc_exp_tl { ~\hfill{\scriptsize\ding{73}} } }, % - pack.usage:n = general, - pack.meta:n = { pkg } , - % - sep.usage:n = general, - sep.code:n = + sep.code:n = { \tl_set:Nn \__codedesc_lastsep_tl { ~#1~ } }, @@ -396,19 +498,23 @@ unknown.usage:n = general, unknown.code:n = { - \tl_set:Nn \__codedesc_metacolor_tl: { \color{c__codedesc_none_color} } - }, - + \tl_set:Nn \__codedesc_metacolor_tl: { \color{c__codedesc_none_color} } + \msg_error:nnxx { codedesc } {object-err} {format}{\l_keys_key_str} + }, } -\cs_new:Npn \__codedesc_metafmt_set:n #1 +\cs_new_protected:Npn \__codedesc_metafmt_set:n #1 { \tl_set:Nn \__codedesc_rulecolor_tl: { \__codedesc_metacolor_tl: } \tl_set:Nn \__codedesc_metashape_tl: { } \tl_set:Nn \__codedesc_typeset_tl:n { } - \tl_set:Nn \__codedesc_typeset_tl:o { \relax } + \tl_set:Nn \__codedesc_typeset_tl:o { } + \tl_set:Nn \__codedesc_Lbracket_tl { } + \tl_set:Nn \__codedesc_Rbracket_tl { } \tl_set:Nn \__codedesc_sep_tl {,\ } \tl_set:Nn \__codedesc_lastsep_tl {\ and\ } + \tl_set:Nn \__codedesc_exp_tl { } + \bool_set_false:N \l__codedesc_descnotes_bool \bool_set_false:N \l__codedesc_descdate_new_bool @@ -420,29 +526,16 @@ \cs_generate_variant:Nn \__codedesc_metafmt_set:n {o} -\cs_new:Npn \__codedesc_metafmt:n #1 +\cs_new_protected:Npn \__codedesc_metafmt:n #1 { - \tl_set:Nn \__codedesc_rulecolor_tl: { \__codedesc_metacolor_tl: } - \tl_set:Nn \__codedesc_metashape_tl: { } - \tl_set:Nn \__codedesc_typeset_tl:n { } - \tl_set:Nn \__codedesc_typeset_tl:o { } - \tl_set:Nn \__codedesc_sep_tl {,\ } - \tl_set:Nn \__codedesc_lastsep_tl {\ and\ } - - \bool_set_false:N \l__codedesc_descnotes_bool - \bool_set_false:N \l__codedesc_descdate_new_bool - \bool_set_false:N \l__codedesc_descdate_update_bool - \bool_set_false:N \l__codedesc_sidenote_bool - - \keys_set:nn {codedesc / format}{#1} - %\tl_show:N \__codedesc_rulecolor_tl + \__codedesc_metafmt_set:n {#1} \__codedesc_metafmt: } \cs_generate_variant:Nn \__codedesc_metafmt:n {o} -\cs_new:Npn \__codedesc_metafmt: +\cs_new_protected:Npn \__codedesc_metafmt: { \__codedesc_metacolor_tl: \__codedesc_metasize_tl: @@ -451,57 +544,12 @@ } -\keys_define:nn { codedesc / delimiters } -{ - oarg.usage:n = general, - oarg.code:n = - { - \tl_set:Nn \__codedesc_open_delimit_tl {[} - \tl_set:Nn \__codedesc_close_delimit_tl {]} - }, - marg.usage:n = general, - marg.code:n = - { - \tl_set:Nn \__codedesc_open_delimit_tl {\{} - \tl_set:Nn \__codedesc_close_delimit_tl {\}} - }, - parg.usage:n = general, - parg.code:n = - { - \tl_set:Nn \__codedesc_open_delimit_tl {(} - \tl_set:Nn \__codedesc_close_delimit_tl {)} - }, - % - xarg.usage:n = general, - xarg.code:n = - { - \tl_set:Nn \__codedesc_open_delimit_tl {<} - \tl_set:Nn \__codedesc_close_delimit_tl {>} - }, - % - meta.usage:n = general, - meta.code:n = - { - \tl_set:Nn \__codedesc_open_delimit_tl {} - \tl_set:Nn \__codedesc_close_delimit_tl {} - }, - % - unknown.usage:n = general, - unknown.code:n = - { -% \tl_set:Nn \__codedesc_open_delimit_tl {!} -% \tl_set:Nn \__codedesc_close_delimit_tl {!} - }, - % -} - - %%%%%%% %%% %%% < meta > %%% %%%%%%% -\cs_new:Npn \__codedesc_meta:n #1 +\cs_new_protected:Npn \__codedesc_meta:n #1 { \ensuremath\langle #1 \ensuremath\rangle } @@ -513,7 +561,7 @@ %%% < meta > 'detokenized' %%% %%%%%%% -\cs_new:Npn \__codedesc_meta*:n #1 +\cs_new_protected:Npn \__codedesc_meta*:n #1 { \ensuremath\langle \tl_to_str:n {#1} \ensuremath\rangle } @@ -523,7 +571,7 @@ -\cs_new:Npn \__codedesc_macro_typeset:n #1 +\cs_new_protected:Npn \__codedesc_macro_typeset:n #1 { \tl_set:Ne \l_tmpb_tl {\tl_to_str:n{#1}} \regex_replace_all:nnN {\ }{} \l_tmpb_tl @@ -536,11 +584,18 @@ \cs_generate_variant:Nn \__codedesc_macro_typeset:n {o} +\cs_new_protected:Npn \__codedesc_verb_nospc_typeset:n #1 + { + \tl_set:Ne \l_tmpb_tl {\tl_to_str:n{#1}} + \regex_replace_all:nnN {\ }{} \l_tmpb_tl + \l_tmpb_tl + } +\cs_generate_variant:Nn \__codedesc_verb_nospc_typeset:n {o} -\cs_new:Npn \__codedesc_list_typeset:nnn #1#2#3 +\cs_new_protected:Npn \__codedesc_list_typeset:nnn #1#2#3 { \seq_set_from_clist:Nn \l_tmpa_seq {#1} \bool_set:Nn \l__codedesc_bool {\seq_if_empty_p:N \l_tmpa_seq} @@ -578,7 +633,7 @@ -\cs_new:Npn \__codedesc_args_typeset:nnnn #1#2#3#4 +\cs_new_protected:Npn \__codedesc_args_typeset:nnnn #1#2#3#4 { \seq_set_from_clist:Nn \l_tmpa_seq {#3} \group_begin: @@ -586,6 +641,13 @@ \seq_map_inline:Nn \l_tmpa_seq {~\!\!#2 \__codedesc_meta:n {##1} #4 } \group_end: } + + +%%%%%%%%%%%%%%%%%%% +%%%% +%%%% Variables used in the codedescibe environment +%%%% +%%%%%%%%%%%%%%%%%%% \bool_new:N \l__codedesc_longblock_bool @@ -596,6 +658,22 @@ \dim_new:N \l__codedesc_syntax_wd_dim \dim_new:N \l__codedesc_margin_wd_dim +\bool_new:N \l__codedesc_descnotes_bool +\bool_new:N \l__codedesc_descdate_new_bool +\tl_new:N \l__codedesc_descdate_new_tl +\bool_new:N \l__codedesc_descdate_update_bool +\tl_new:N \l__codedesc_descdate_update_tl +\bool_new:N \l__codedesc_sidenote_bool +\tl_new:N \l__codedesc_sidenote_tl + + +\coffin_new:N \__codedesc_describe_coffin +\dim_new:N \__codedesc_describelabel_wd_dim +\dim_new:N \__codedesc_describelist_wd_dim +\tl_new:N \__codedesc_join_tl: +\tl_new:N \__codedesc_ragged_tl: + +\dim_new:N \__codedesc_paradvance_dim %%%%%%%%%%%%%%%%%%% @@ -604,10 +682,26 @@ %%%% %%%%%%%%%%%%%%%%%%% - + +\NewDocumentCommand \defgroupfmt {mm} + { + \__codedesc_group_define:nn {#1} {#2} + } + +\NewDocumentCommand \defobjectfmt {mmm} + { + \__codedesc_object_define:nn {#1} {#2} {#3} + } \NewDocumentEnvironment {codedescribe}{O{code}m} { + \mode_if_horizontal:TF + { + \dim_set:Nn \__codedesc_paradvance_dim {\baselineskip} + } + { + \dim_set:Nn \__codedesc_paradvance_dim {0pt} + } \seq_set_from_clist:Nn \l_tmpa_seq {#2} \__codedesc_set_textcolwidth: \hcoffin_set:Nn \l__codedesc_margin_coffin @@ -616,21 +710,23 @@ \begin{tabular}{@{} l @{} } \__codedesc_hline:nnnn {\__codedesc_rulecolor_tl:}{0.5ex}{2}{0.25ex} - \seq_map_inline:Nn \l_tmpa_seq { \__codedesc_typeset_tl:n {##1} \\ } + \seq_map_inline:Nn \l_tmpa_seq { \__codedesc_typeset_tl:n {##1} \__codedesc_exp_tl \\ } \bool_if:nTF {\l__codedesc_descnotes_bool} { - \\[-2.5ex] - \__codedesc_hline:nnnn {\color{black}}{0.5ex}{0.25}{0.25ex} - - \bool_if:nT {\l__codedesc_descdate_new_bool} - {\scriptsize\color{black}new:~ \l__codedesc_descdate_new_tl\\} - \bool_if:nT {\l__codedesc_descdate_update_bool} - {\scriptsize\color{black}update:~ \l__codedesc_descdate_update_tl\\} - \bool_if:nT {\l__codedesc_sidenote_bool} - {\scriptsize\color{black}NB:~ \l__codedesc_sidenote_tl\\} + \\[-2.5ex] + \__codedesc_hline:nnnn {\color{black}}{0.5ex}{0.25}{0.25ex} + + \bool_if:nT {\l__codedesc_descdate_new_bool} + {\scriptsize\color{black}new:~ \l__codedesc_descdate_new_tl\\[-1ex]} + \bool_if:nT {\l__codedesc_descdate_update_bool} + {\scriptsize\color{black}update:~ \l__codedesc_descdate_update_tl\\[-1ex]} + \bool_if:nT {\l__codedesc_sidenote_bool} + {\scriptsize\color{black}NB:~ \l__codedesc_sidenote_tl\\[-1ex]} + \\[-1.5ex] + } + { + \\[-2.5ex] } - {} - \\[-2.5ex] \__codedesc_hline:nnnn {\__codedesc_rulecolor_tl:}{-0.25ex}{2}{1ex} \end{tabular} } @@ -656,17 +752,18 @@ \bool_if:NTF \l__codedesc_longblock_bool { % __describeblock starting at marginpar \coffin_join:NnnNnnnn \l__codedesc_syntax_coffin {l}{t} \l__codedesc_margin_coffin {r}{t} {-\marginparsep}{0pt} - \coffin_join:NnnNnnnn \l__codedesc_syntax_coffin {l}{b} \l__codedesc_text_coffin {l}{t} {\marginparwidth+\marginparsep}{0pt}%{-0.25\baselineskip} + \coffin_join:NnnNnnnn \l__codedesc_syntax_coffin {l}{b} \l__codedesc_text_coffin {l}{t} {\marginparwidth+\marginparsep}{\baselineskip} \par\noindent - \coffin_typeset:Nnnnn \l__codedesc_syntax_coffin {l}{t} {-\marginparwidth-\marginparsep}{0pt} + \coffin_typeset:Nnnnn \l__codedesc_syntax_coffin {l}{t} {-\marginparwidth-\marginparsep}{\__codedesc_paradvance_dim} } { % __describeblock at marginpar \coffin_attach:NnnNnnnn \l__codedesc_syntax_coffin {l}{t} \l__codedesc_margin_coffin {r}{t} {-\marginparsep}{0pt} - \coffin_join:NnnNnnnn \l__codedesc_syntax_coffin {l}{b} \l__codedesc_text_coffin {l}{t} {0pt}{0pt}%{-0.25\baselineskip} + \coffin_join:NnnNnnnn \l__codedesc_syntax_coffin {l}{b} \l__codedesc_text_coffin {l}{t} {0pt}{\baselineskip} \par\noindent - \coffin_typeset:Nnnnn \l__codedesc_syntax_coffin {l}{t} {0pt}{0pt} + \coffin_typeset:Nnnnn \l__codedesc_syntax_coffin {l}{t} {0pt}{\__codedesc_paradvance_dim} } - \\[0.25\baselineskip] + \\[0.5\baselineskip] + %\\[\__codedesc_paradvance_dim]%[-0.5\baselineskip] } @@ -691,20 +788,13 @@ \vcoffin_gset_end: } - -\coffin_new:N \__codedesc_describe_coffin -\dim_new:N \__codedesc_describelabel_wd_dim -\dim_new:N \__codedesc_describelist_wd_dim -\tl_new:N \__codedesc_join_tl: -\tl_new:N \__codedesc_ragged_tl: - \NewDocumentEnvironment{describelist}{O{20mm}m} { %\vspace*{-1.5ex} \mode_if_horizontal:TF - {\vspace*{-0.75ex}} + {\\[-0.5\baselineskip]} {} \__codedesc_set_textcolwidth: \coffin_clear:N \__codedesc_describe_coffin @@ -722,7 +812,7 @@ { %\vspace*{-1.5ex} \mode_if_horizontal:TF - {\vspace*{-1ex}} + {\\[-0.5\baselineskip]}%{\vspace*{-1ex}} {} \__codedesc_set_textcolwidth: \coffin_clear:N \__codedesc_describe_coffin @@ -737,34 +827,31 @@ } \NewDocumentCommand \describe {mm} - { - + { \hcoffin_set:Nn \l_tmpb_coffin { \__codedesc_metafmt:o { \__codedesc_listkind_tl } \__codedesc_ragged_tl: \__codedesc_typeset_tl:n {#1} - } + } + \dim_compare:nNnTF {\coffin_wd:N \l_tmpb_coffin} > {\__codedesc_describelabel_wd_dim} + { + \vcoffin_set:Nnn \l_tmpa_coffin + { \__codedesc_describelabel_wd_dim } + { ~\ ~ } + \coffin_attach:NnnNnnnn + \l_tmpa_coffin {r}{t} + \l_tmpb_coffin {r}{t} + {0pt}{0pt} - \dim_compare:nNnTF {\coffin_wd:N \l_tmpb_coffin} > {\__codedesc_describelabel_wd_dim} - { - \vcoffin_set:Nnn \l_tmpa_coffin - { \__codedesc_describelabel_wd_dim } - { ~\ ~ } - \coffin_attach:NnnNnnnn - \l_tmpa_coffin {r}{t} - \l_tmpb_coffin {r}{t} - {0pt}{0pt} - - } - { - \vcoffin_set:Nnn \l_tmpa_coffin - { \__codedesc_describelabel_wd_dim } - { - \__codedesc_metafmt:o { \__codedesc_listkind_tl } - \noindent\__codedesc_ragged_tl: \__codedesc_typeset_tl:n {#1} - } - } - + } + { + \vcoffin_set:Nnn \l_tmpa_coffin + { \__codedesc_describelabel_wd_dim } + { + \__codedesc_metafmt:o { \__codedesc_listkind_tl } + \noindent\__codedesc_ragged_tl: \__codedesc_typeset_tl:n {#1} + } + } \vcoffin_set:Nnn \l_tmpb_coffin { \__codedesc_describelist_wd_dim } { @@ -772,26 +859,21 @@ \begin{minipage}[t]{ \__codedesc_describelist_wd_dim } #2 \end{minipage} - } - - + } \__codedesc_join_tl: \l_tmpb_coffin {l}{t} \l_tmpa_coffin {r}{t} {-\marginparsep}{0pt} - \mode_if_horizontal:TF { - \\ -% \tl_set:Nn \l_tmpa_tl {~\ ~} - } - { -% \tl_set:Nn \l_tmpa_tl {~\ ~} + \\[-\baselineskip] } - \noindent%\vspace*{-1ex} + { } + + \noindent \coffin_typeset:Nnnnn \l_tmpb_coffin {l}{t} {0pt}{0pt} - \\[-0.5\baselineskip] + \\ } @@ -804,8 +886,11 @@ \NewDocumentCommand \typesetargs {O{meta}m} { - \keys_set:nn {codedesc / delimiters}{#1} - \__codedesc_args_typeset:nnnn {#1} \__codedesc_open_delimit_tl {#2} \__codedesc_close_delimit_tl +% \keys_set:nn {codedesc / delimiters}{#1} + \group_begin: + \__codedesc_metafmt:n {#1} + \__codedesc_args_typeset:nnnn {#1} {\__codedesc_Lbracket_tl} {#2} {\__codedesc_Rbracket_tl} + \group_end: } \cs_new_eq:NN \tsargs \typesetargs @@ -847,7 +932,6 @@ \NewDocumentEnvironment {tsremark} {O{Note:}} { -% \par\vspace*{0.5\baselineskip} \mode_if_horizontal:TF {\par\vspace*{0.25\baselineskip}}%\vspace*{-1.5ex}} {\vspace*{0.75\baselineskip}} @@ -861,7 +945,7 @@ { \end{minipage} \group_end: - \par + \\[0.5\baselineskip] } @@ -870,20 +954,20 @@ \keys_define:nn { codedesc / title } { title .usage:n = general , + title .value_required:n = true , title .tl_set:N = \l__codedesc_title_tl , author .usage:n = general , + author .value_required:n = true , author .tl_set:N = \l__codedesc_author_tl , date .usage:n = general , + date .value_required:n = true , date .tl_set:N = \l__codedesc_descdate_tl , - - abstract .usage:n = general , - abstract .tl_set:N = \l__codedesc_abstract_tl , } -\cs_new:Npn \__codedesc_make_title: {% +\cs_new_protected:Npn \__codedesc_make_title: {% \newpage \null \vskip 2em% @@ -904,6 +988,29 @@ } + +\NewDocumentCommand \typesetdate {} + { + \int_case:nn {\month} + { + {1}{January} + {2}{February} + {3}{March} + {4}{April} + {5}{May} + {6}{June} + {7}{July} + {8}{August} + {9}{September} + {10}{October} + {11}{November} + {12}{December} + } + \use:n {~} \int_to_arabic:n {\year} + } + +\cs_new_eq:NN \tsdate \typesetdate + %%%ARGH !!!!! %%% 'adapted' from 'abstract.cls' %%% diff --git a/macros/latex/contrib/codedescribe/latex/codelisting.sty b/macros/latex/contrib/codedescribe/latex/codelisting.sty index ede0132e3e..c02633d912 100644 --- a/macros/latex/contrib/codedescribe/latex/codelisting.sty +++ b/macros/latex/contrib/codedescribe/latex/codelisting.sty @@ -12,43 +12,51 @@ %% %% The Current Maintainer of this work is Alceu Frigeri %% -%% This is version 1.0 (2023/05/11) +%% This is version 1.1 (2023/05/16) %% %% The list of files that compose this work can be found in the README.md file at %% https://ctan.org/pkg/codedescribe %% %%%============================================================================== \NeedsTeXFormat{LaTeX2e}[2022/06/01] - \RequirePackage{ expl3 } \ProvidesExplPackage {codelisting} - {2023/05/11} - {1.0} + {2023/05/16} + {1.1} {LaTeX Code Listing} -\prop_if_exist:NTF \g__codedesc_pkg_prop - {} - { \prop_new:N \g__codedesc_pkg_prop } - -\prop_put_from_keyval:Nn \g__codedesc_pkg_prop +%%%%%%% +%%% +%%% Just an attempt of having my packages info in a regular way +%%% Idea being: { <pck-name> / pkg info } for each and all. +%%% +%%%%%%% +\keys_define:nn { codelisting / pkg info} { - codelist . name = codelisting , - codelist . prefix = codelist , - codelist . date = 2023/05/11 , - codelist . version = 1.0 , - codelist . description = LaTeX Code Listing + name .code:n = codelisting , + prefix .code:n = codelist , + date .code:n = 2023/05/16 , + version .code:n = 1.1 , + description .code:n = \LaTeX~Code~Listing } - -\cs_gset:Npn \__codedesc_pkg_info:nn #1#2 +\cs_if_exist:NF \__codedesc_pkg_info:nn { - \prop_item:Nn \g__codedesc_pkg_prop {#1.#2} + \cs_new_protected:Npn \__codedesc_pkg_info:nn #1#2 + { \keys_set:nn {#1 / pkg info}{#2} } } +\cs_if_exist:NF \PkgInfo + { \NewDocumentCommand \PkgInfo {mm} { \keys_set:nn {#1 / pkg info}{#2} } } +%%%%%%% +%%% End of cut-n-paste +%%%%%%% + -\RequirePackage{listings,scontents} +\RequirePackage{listings,scontents} + \dim_new:N \l__codelist_demo_parindent_dim \dim_new:N \l__codelist_org_parindent_dim @@ -277,6 +285,9 @@ } +%%%%%% +%%% This one can't be proteced +%%%%%% \cs_new:Npn \__codelist_set_options:n #1 {\keys_set:nn {CodeListingOptions}{#1}} \__codelist_set_options:n{default} @@ -461,6 +472,9 @@ \cs_undefine:c{endverbatimsc} \lstnewenvironment{verbatimsc}{\lstset{style=codestyle}}{} +%%%%%% +%%% This one can't be proteced +%%%%%% \cs_new:Npn \__codelist_set_verbsc:n #1 { \cs_undefine:c{verbatimsc} |