diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/exsheets/cntformats_en.tex')
-rw-r--r-- | Master/texmf-dist/doc/latex/exsheets/cntformats_en.tex | 555 |
1 files changed, 229 insertions, 326 deletions
diff --git a/Master/texmf-dist/doc/latex/exsheets/cntformats_en.tex b/Master/texmf-dist/doc/latex/exsheets/cntformats_en.tex index 98a1605aa48..8fa6ed82b38 100644 --- a/Master/texmf-dist/doc/latex/exsheets/cntformats_en.tex +++ b/Master/texmf-dist/doc/latex/exsheets/cntformats_en.tex @@ -1,11 +1,11 @@ % arara: pdflatex -% arara: biber -% arara: pdflatex +% !arara: biber +% !arara: pdflatex % arara: pdflatex % -------------------------------------------------------------------------- -% the TRANSLATIONS package +% the CNTFORMATS package % -% +% A different way to read counters % % -------------------------------------------------------------------------- % Clemens Niederberger @@ -31,94 +31,50 @@ % If you have any ideas, questions, suggestions or bugs to report, please % feel free to contact me. % -------------------------------------------------------------------------- -% -% if you want to compile this documentation you'll need the document class -% `cnpkgdoc' which you can get here: -% https://bitbucket.org/cgnieder/cnpkgdoc/ -% the class is licensed LPPL 1.3 or later -% -% use `pdflatex' and `biber' for compilation -% -\PassOptionsToPackage{supstfm=libertinesups}{superiors} -\documentclass[toc=index,toc=bib,numbers=noendperiod]{cnpkgdoc} -% ---------------------------------------------------------------------------- -% document layout and typographic features -\docsetup{ - pkg = {cntformats} , +\documentclass[load-preamble+]{cnltx-doc} +\usepackage{cntformats} + +\setcnltx{ + package = {cntformats} , + authors = Clemens Niederberger , + email = {contact@mychemistry.eu} , url = {https://bitbucket.org/cgnieder/exsheets/} , - subtitle = {{\small part of the \href{exsheets_en.pdf}{\ExSheets} bundle}\\[\baselineskip]a different way to read counters} , - language = en , - modules = true , - code-box = { - backgroundcolor = gray!7!white , - skipbelow = .6\baselineskip plus .5ex minus .5ex , - skipabove = .6\baselineskip plus .5ex minus .5ex + info = {% + {\small part of the \href{exsheets_en.pdf}{\ExSheets} + bundle}\\[\baselineskip] + a different way to read counters% } , - gobble = 1 + add-cmds = { + @cntfmts@parsed@pattern, AddCounterPattern, + eSaveCounterPattern, + NewCounterPattern, NewPatternFormat, + ReadCounterFrom, ReadCounterPattern, ReadCounterPatternFrom, + SaveCounterPattern + } , + add-silent-cmds = { + alphalph, + cs, + ExplSyntaxOff, ExplSyntaxOn, + int, + myoddnumber, + numexpr, ordinalnum, + relax, + somesetupcommand, + tmpa, tmpb, the + } } -\usepackage{libertinehologopatch} -\cnpkgusecolorscheme{friendly} + +\defbibheading{bibliography}[\bibname]{\addsec{#1}} + +\newpackagename\ExSheets{ExSheets} +\def\at{\cnltxat} \usepackage[biblatex]{embrac}[2012/06/29] \ChangeEmph{[}[,.02em]{]}[.055em,-.08em] \ChangeEmph{(}[-.01em,.04em]{)}[.04em,-.05em] -\usepackage{microtype} -\usepackage[multiple]{fnpct} - -\renewcommand*\othersectionlevelsformat[3]{\textcolor{main}{#3\autodot}\enskip} -\renewcommand*\partformat{\textcolor{main}{\partname~\thepart\autodot}} - -\pagestyle{headings} - -\setcapindent{1.5em} -\setkomafont{caption}{\normalfont\footnotesize\sffamily} -\setkomafont{captionlabel}{\normalfont\footnotesize\sffamily\scshape} \usepackage{booktabs,array,ragged2e} - -% ---------------------------------------------------------------------------- -% code examples -\addcmds{ - @cntfmts@parsed@pattern, AddCounterPattern, alphalph, - cs, eSaveCounterPattern, ExplSyntaxOff, ExplSyntaxOn, int, - myoddnumber, NewCounterPattern, NewPatternFormat, numexpr, ordinalnum, - ReadCounterFrom, ReadCounterPattern, ReadCounterPatternFrom, relax, - SaveCounterPattern, somesetupcommand, - tmpa, tmpb, the -} - -% ---------------------------------------------------------------------------- -% other packages, bibliography, index -\usepackage{xcoffins,wasysym,enumitem,booktabs,siunitx} -\usepackage[accsupp]{acro} -\DeclareAcronym{id}{ - short = id , - long = Identifier , - format = \scshape , - pdfstring = ID , - accsupp = ID -} - -\usepackage{filecontents} -\usepackage{imakeidx} -\begin{filecontents*}{\jobname.ist} - heading_prefix "{\\bfseries " - heading_suffix "\\hfil}\\nopagebreak\n" - headings_flag 1 - delim_0 "\\dotfill\\hyperpage{" - delim_1 "\\dotfill\\hyperpage{" - delim_2 "\\dotfill\\hyperpage{" - delim_r "}\\textendash\\hyperpage{" - delim_t "}" - suffix_2p "\\nohyperpage{\\,f.}" - suffix_3p "\\nohyperpage{\\,ff.}" -\end{filecontents*} -\indexsetup{othercode=\footnotesize} -\makeindex[options={-s \jobname.ist},intoc,columns=3,columnsep=1em] - -\usepackage{csquotes} -\usepackage[backend=biber,style=alphabetic]{biblatex} - +\usepackage{subcaption} % ---------------------------------------------------------------------------- % example definitions that have to be done in the preamble: @@ -130,278 +86,225 @@ \NewPatternFormat{x}{\myoddnumber} \NewCounterPattern{testa}{ta} -% ---------------------------------------------------------------------------- -% custom commands -\newcommand*\ExSheets{{\scshape\textcolor{main}{ExSheets}}\xspace} - -\newcommand*\Default[1]{% - \hfill\llap - {% - \ifblank{#1}% - {(initially~empty)}% - {Default:~\code{#1}}% - }% - \newline -} -\newcommand*\required{\hfill\llap{required}\newline} -\newcommand*\optional{\hfill\llap{optional}\newline} - -\newcommand*\nooption[2]{\item[\code{\textcolor{key}{#1} = #2}] \cnpkgdocarrow\ } - -\newcommand*\unexpsign{$\RHD$} -\newcommand*\expsign{\textcolor{red}{$\rhd$}} -\renewcommand*\cnpkgdoctriangle{\unexpsign} -\newcommand*\expandable{% - \def\cnpkgdoctriangle{% - \expsign - \gdef\cnpkgdoctriangle{\unexpsign}}} - -\usepackage{marginnote} -\makeatletter -\newcommand*\sinceversion[1]{% - \@bsphack - \marginnote{% - \footnotesize\sffamily\RaggedRight - \textcolor{black!75}{Introduced in version~#1}}% - \@esphack} -\newcommand*\changedversion[1]{% - \@bsphack - \marginnote{% - \footnotesize\sffamily\RaggedRight - \textcolor{black!75}{Changed in version~#1}}% - \@esphack} -\makeatother - -\pdfstringdefDisableCommands{\def\llap#1{#1\space}\def\bigstar{*}} - -% ---------------------------------------------------------------------------- -% title page -% \TitlePicture{% -% \parbox{.8\linewidth}{% -% }% -% } - \begin{document} -\section{Motivation}\secidx{Motivation} -\cntformats provides a way to format counters with what I will call patterns. -This does not in any way effect the usual \LaTeXe\ way of treating counters and -does not use \cmd*{the<counter>} nor is it affected by the redefinition of them. +\section{Motivation} +\cntformats\ provides a way to format counters with what I will call patterns. +This does not in any way effect the usual \LaTeXe\ way of treating counters +and does not use \cs*{the\meta{counter}} nor is it affected by the redefinition of +them. This package is aimed at package or class authors and probably not very useful for document authors. When I first had the idea for this package the idea of what it does already -existed as part of the \ExSheets package. I can't recall why I came up with +existed as part of the \ExSheets\ package. I can't recall why I came up with the idea in the first place or why I originally wanted a new syntax for -formatting the \code{question} counter. Anyway, here we are. -\secidx*{Motivation} +formatting the \code{question} counter. I am also not convinced any more that +it is a good idea. Anyway, here we are. -\section{License and Requirements}\label{sec:license}\secidx{Requirements} -\cntformats is placed under the terms of the \LaTeX{} Project Public License, -version 1.3 or later (\url{http://www.latex-project.org/lppl.txt}). It has the -status ``maintained.'' +\section{License and Requirements}\label{sec:license} +\license -\cntformats requires the \paket{etoolbox} package. -\secidx*{Requirements} +\cntformats\ requires the \needpackage{etoolbox} package~\cite{pkg:etoolbox} +and the \pkg*{cnltx-base}\footnote{\CTANurl{cnltx}} package~\cite{bnd:cnltx}. -\section{Example}\secidx{Example} +\section{Example} A use case typically looks as follows: -\begin{beispiel} - \ReadCounterPattern{se.sse} -\end{beispiel} -where the key \code{se} stands for the current value of the \code{section} counter -and \code{sse} for \code{subsection}, respectively. \code{se.sse} is an example -for what will be called \emph{pattern}. The keys for the counters can have optional -arguments that specify the format: -\begin{beispiel} - \stepcounter{subsection} - \ReadCounterPattern{se[A](sse[r])} -\end{beispiel} -\code{A} stands for \cmd{Alph} and \code{r} for \cmd{roman}. A complete list can -be found in table~\ref{tab:predefined:formats} on page~\pageref{tab:predefined:formats}. -As you can see you can insert arbitrary other tokens in a pattern that won't be -changed. It is important to notice, though, that the patterns are only replaced -if they're \emph{not} placed in a braced group! - -\begin{beispiel} - \ReadCounterPattern{{se[A](sse[r])}} -\end{beispiel} - -I would imagine that the argument to \cmd{ReadCounterPattern} is usually +\begin{example}[side-by-side] + \ReadCounterPattern{se.sse} +\end{example} +where the key \code{se} stands for the current value of the \code{section} +counter and \code{sse} for \code{subsection}, respectively. \code{se.sse} is +an example for what will be called \emph{pattern}. The keys for the counters +can have optional arguments that specify the format: +\begin{example}[side-by-side] + \stepcounter{subsection} + \ReadCounterPattern{se[A](sse[r])} +\end{example} +\code{A} stands for \cs*{Alph} and \code{r} for \cs*{roman}. A complete list +can be found in table~\ref{tab:predefined:formats} on +page~\pageref{tab:predefined:formats}. As you can see you can insert +arbitrary other tokens in a pattern that won't be changed. It is important to +notice, though, that the patterns are only replaced if they're \emph{not} +placed in a braced group! + +\begin{example}[side-by-side] + \ReadCounterPattern{{se[A](sse[r])}} +\end{example} + +I would imagine that the argument to \cs{ReadCounterPattern} is usually supplied by a user setting an option \ldots -\begin{beispiel}[code only] - \somesetupcommand{ - counter-format = se[A](sse[r]) - } -\end{beispiel} +\begin{sourcecode} + \somesetupcommand{ + counter-format = se[A](sse[r]) + } +\end{sourcecode} \ldots{} and then internally used by the corresponding package or class. -\secidx*{Example} -\section{Usage}\secidx{Usage} -In the following description of the available commands the symbol \expsign{} -means that the command is expandable, \unexpsign{} means that it isn't. -In order to make counters known to \cntformats the following commands are used: -\begin{beschreibung} - \Befehl{AddCounterPattern}*[<module>]{<counter>}\ma{<pattern>}\newline - This command will make the (existing) counter \code{<counter>} known to - \cntformats and assign the pattern \code{<pattern>} to it. - \Befehl{NewCounterPattern}*[<module>]{<counter>}\ma{<pattern>}\newline - This command will create a new counter \code{<counter>}, make it known to - \cntformats and assign the pattern \code{<pattern>} to it. - \Befehl{ReadCounterFrom}[<module>]{<counter>}\ma{<internal cmd>}\newline - If you use one of the commands above with the starred version the number for - the pattern is not automatically fetched from the internal \cmd*{c@<counter>}. - This can now be assigned with \cmd{ReadCounterFrom} where \code{<internal cmd>} - is the macro that holds the number. -\end{beschreibung} +\section{Usage} +In the following description of the available commands the symbol +\textcolor{expandable}{\expandablesign} means that the command is expandable. + +In order to make counters known to \cntformats\ the following commands are used: +\begin{commands} + \command{AddCounterPattern}[\sarg\oarg{module}\marg{counter}\marg{pattern}] + This command will make the (existing) counter \meta{counter} known to + \cntformats\ and assign the pattern \meta{pattern} to it. + \command{NewCounterPattern}[\sarg\oarg{module}\marg{counter}\marg{pattern}] + This command will create a new counter \meta{counter}, make it known to + \cntformats\ and assign the pattern \meta{pattern} to it. + \command{ReadCounterFrom}[\oarg{module}\marg{counter}\marg{internal cmd}] + If you use one of the commands above with the starred version the number + for the pattern is not automatically fetched from the internal + \cs*{c@\meta{counter}}. This can now be assigned with + \cs{ReadCounterFrom} where \meta{internal cmd} is the macro that holds + the number. +\end{commands} The commands above can only be used in the document preamble. After the creation of these pattern markers one wants to be able to use them. There are a number of macros that allow different aspects of usage. -\begin{beschreibung} - \Befehl{ReadCounterPattern}[<module>]{<pattern>}\newline - Reads, interprets and prints a pattern. - \expandable\Befehl{@cntfmts@parsed@pattern}\newline - After \cmd{ReadCounterPattern} has been used the current pattern interpretation - is stored in this macro. The \emph{interpretation} is \emph{not} what is printed. - See the examples below for details. - \Befehl{ReadCounterPatternFrom}[<module>]{<macro that holds pattern>}\newline - Reads, interprets and prints a pattern that's stored in a macro.\\ - Otherwise the same as \cmd{ReadCounterPattern}. - \Befehl{SaveCounterPattern}{<cmd a>}\ma{<cmd b>}\ma{<pattern>}\newline - Saves the \code{<pattern>} in \code{<cmd a>} and the interpreted pattern in - \code{<cmd b>}. - \Befehl{eSaveCounterPattern}[<module>]{<cmd a>}\ma{<cmd b>}\ma{<pattern>}\newline - Saves the \code{<pattern>} in \code{<cmd a>} and the expanded pattern in - \code{<cmd b>}. - \Befehl{SaveCounterPatternFrom}[<module>]{<cmd a>}\ma{<cmd b>}\ma{<macro that - holds pattern>}\newline - Like \cmd{SaveCounterPattern} but reads the pattern from a macro. - \Befehl{eSaveCounterPatternFrom}[<module>]{<cmd a>}\ma{<cmd b>}\ma{<macro that - holds pattern>}\newline - Like \cmd{eSaveCounterPattern} but reads the pattern from a macro. -\end{beschreibung} - -The optional argument \code{<module>} should be specific for a package, say, so +\begin{commands} + \command{ReadCounterPattern}[\oarg{module}\marg{pattern}] + Reads, interprets and prints a pattern. + \expandable\command{\at cntfmts\at parsed\at pattern} + After \cs{ReadCounterPattern} has been used the current pattern + interpretation is stored in this macro. The \emph{interpretation} is + \emph{not} what is printed. See the examples below for details. + \command{ReadCounterPatternFrom}[\oarg{module}\marg{macro that holds + pattern}] + Reads, interprets and prints a pattern that's stored in a macro.\\ + Otherwise the same as \cs{ReadCounterPattern}. + \command{SaveCounterPattern}[\marg{cmd a}\marg{cmd b}\marg{pattern}] + Saves the \meta{pattern} in \meta{cmd a} and the interpreted pattern in + \meta{cmd b}. + \command{eSaveCounterPattern}[\oarg{module}\marg{cmd a}\marg{cmd + b}\marg{pattern}] + Saves the \meta{pattern} in \meta{cmd a} and the expanded pattern in + \meta{cmd b}. + \command{SaveCounterPatternFrom}[\oarg{module}\marg{cmd a}\marg{cmd + b}\marg{macro that holds pattern}] + Like \cs{SaveCounterPattern} but reads the pattern from a macro. + \command{eSaveCounterPatternFrom}[\oarg{module}\marg{cmd a}\marg{cmd + b}\marg{macro that holds pattern}] + Like \cs{eSaveCounterPattern} but reads the pattern from a macro. +\end{commands} + +The optional argument \meta{module} should be specific for a package, say, so that different patterns for the \code{section} for example don't interfer with -each other. If you leave the argument the default module \code{cntfmts} is used. +each other. If you leave the argument the default module \code{cntfmts} is +used. -The \ExSheets packages uses the commands with the module \code{exsheets}. +The \ExSheets\ packages uses the commands with the module \code{exsheets}. You can find the following lines in \ExSheets' code: -\begin{beispiel}[code only] - \AddCounterPattern*[exsheets]{section}{se} - \ReadCounterFrom[exsheets]{section} \l__exsheets_counter_sec_int - \NewCounterPattern*[exsheets]{question}{qu} - \ReadCounterFrom[exsheets]{question} \l__exsheets_counter_qu_int -\end{beispiel} +\begin{sourcecode} + \AddCounterPattern*[exsheets]{section}{se} + \ReadCounterFrom[exsheets]{section} \l__exsheets_counter_sec_int + \NewCounterPattern*[exsheets]{question}{qu} + \ReadCounterFrom[exsheets]{question} \l__exsheets_counter_qu_int +\end{sourcecode} Now let's see a short example that hopefully explains what the macros do: -\begin{beispiel} - % preamble - % \NewCounterPattern{testa}{ta} - \setcounter{testa}{11} - \ReadCounterPattern{ta} - \ReadCounterPattern{ta[a]} \\ - \ttfamily\makeatletter - \meaning\@cntfmts@parsed@pattern - - \bigskip - \SaveCounterPattern\tmpa\tmpb{ta[a]} - \meaning\tmpa \\ - \meaning\tmpb - - \bigskip - \eSaveCounterPattern\tmpa\tmpb{ta[a]} - \meaning\tmpa \\ - \meaning\tmpb -\end{beispiel} -You can see that somehow additional (empty) groups and a \cmd*{relax} found their -way into the interpreted and thus the expanded pattern. This is due to the fact -that reading optional arguments expandably isn't easy and must have some safety -net. -\secidx*{Usage} - -\section{Predefined and New Patterns and Format Keys}\secidx{Predefined Patterns} +\begin{example} + % preamble + % \NewCounterPattern{testa}{ta} + \setcounter{testa}{11} + \ReadCounterPattern{ta} + \ReadCounterPattern{ta[a]} \\ + \ttfamily\makeatletter + \meaning\@cntfmts@parsed@pattern + + \bigskip + \SaveCounterPattern\tmpa\tmpb{ta[a]} + \meaning\tmpa \\ + \meaning\tmpb + + \bigskip + \eSaveCounterPattern\tmpa\tmpb{ta[a]} + \meaning\tmpa \\ + \meaning\tmpb +\end{example} +You can see that somehow an additional \cs*{@empty} found its way into the +interpreted pattern. This is due to the fact that reading optional arguments +expandably isn't easy and must have some safety net. + +\section{Predefined and New Patterns and Format Keys} \subsection{Predefined Patterns and Format Keys} -\cntformats predefines a number of pattern keys. These are listed in +\cntformats\ predefines a number of pattern keys. These are listed in table~\ref{tab:predefined:patterns}. -\begin{multicols}{2} -\begin{center} - \centering - \captionof{table}{Predefined Patterns for the module \code{cntfmts}.}\label{tab:predefined:patterns} - \begin{tabular}{>{\ttfamily}l>{\ttfamily}l} - \toprule - \normalfont\bfseries counter & \normalfont\bfseries pattern \\ - \midrule - chapter & ch \\ - section & se \\ - subsection & sse \\ - subsubsection & ssse \\ - paragraph & pg \\ - \bottomrule - \end{tabular} - - \captionof{table}{Predefined Format Keys}\label{tab:predefined:formats} - \begin{tabular}{>{\ttfamily}ll} - \toprule - \normalfont\bfseries key & \normalfont\bfseries format \\ - \midrule - 1 & \cmd{arabic} \\ - a & \cmd{alph} \\ - A & \cmd{Alph} \\ - r & \cmd{roman} \\ - R & \cmd{Roman} \\ - \bottomrule - \end{tabular} -\end{center} -\end{multicols} - \subsection{New Patterns and Format Keys} -Table~\ref{tab:predefined:formats} lists the predefined formats. If you want you -can add own formats. -\begin{beschreibung} - \Befehl{NewPatternFormat}{<pattern>}\ma{<format>}\newline - \code{<format>} is a number presentation command like \cmd{@alph}, \textit{i.e.}, - it needs a mandatory argument that takes a number. It is used in \code{<format>} - \emph{without} its argument. This command can only be used in the preamble. -\end{beschreibung} +Table~\ref{tab:predefined:formats} lists the predefined formats. If you want +you can add own formats. +\begin{commands} + \command{NewPatternFormat}[\marg{pattern}\marg{format}] + \meta{format} is a number presentation command like \cs*{@alph}, \ie, + it needs a mandatory argument that takes a number. It is used in + \meta{format} \emph{without} its argument. This command can only be used + in the preamble. +\end{commands} + +\begin{table} + \centering + \caption{Predefined Patterns and Format Keys.} + \addtocounter{table}{-1}% necessary fix for subcaption and KOMA + \begin{minipage}{.48\linewidth} + \centering + \subcaption{Predefined Patterns for the module \code{cntfmts}.} + \label{tab:predefined:patterns} + \begin{tabular}{>{\ttfamily}l>{\ttfamily}l} + \toprule + \normalfont\bfseries counter & \normalfont\bfseries pattern \\ + \midrule + chapter & ch \\ + section & se \\ + subsection & sse \\ + subsubsection & ssse \\ + paragraph & pg \\ + \bottomrule + \end{tabular} + \end{minipage} + \begin{minipage}{.48\linewidth} + \centering + \subcaption{Predefined Format Keys} + \label{tab:predefined:formats} + \begin{tabular}{>{\ttfamily}ll} + \toprule + \normalfont\bfseries key & \normalfont\bfseries format \\ + \midrule + 1 & \cs*{arabic} \\ + a & \cs*{alph} \\ + A & \cs*{Alph} \\ + r & \cs*{roman} \\ + R & \cs*{Roman} \\ + \bottomrule + \end{tabular} + \end{minipage} +\end{table} Here are now a few examples of possible new patterns. Suppose the following code in the preamble: -\begin{beispiel}[code only] - \usepackage{alphalph,fmtcount} - \newcommand*\myoddnumber[1]{\the\numexpr2*(#1)-1\relax} - - \NewPatternFormat{aa}{\alphalph} - \NewPatternFormat{o}{\ordinalnum} - \NewPatternFormat{x}{\myoddnumber} - - \newcounter{testa} - \NewCounterPattern{testa}{ta} - \setcounter{testa}{4} -\end{beispiel} - -Then we can use the new pattern and the new formats as follows:\setcounter{testa}{4} -\begin{beispiel} - \ReadCounterPattern{ta[aa]} - \ReadCounterPattern{ta[o]} - \ReadCounterPattern{ta[x]} -\end{beispiel} -\secidx*{Predefined Patterns} - -\section{Implementation} -In the following code the lines 1--30 have been omitted. They only repeat the -license statement which has already been mentioned in section~\ref{sec:license}. - -\implementation[linerange={31-1000},firstnumber=31] - -\indexprologue{\noindent Section titles are indicated \textbf{bold}, packages -\textsf{sans serif}, commands \code{\textbackslash\textcolor{code}{brown}} - and options \textcolor{key}{\code{yellow}}.\par\bigskip} - -\printindex - -\end{document}
\ No newline at end of file +\begin{sourcecode} + \usepackage{alphalph,fmtcount} + \newcommand*\myoddnumber[1]{\the\numexpr2*(#1)-1\relax} + + \NewPatternFormat{aa}{\alphalph} + \NewPatternFormat{o}{\ordinalnum} + \NewPatternFormat{x}{\myoddnumber} + + \newcounter{testa} + \NewCounterPattern{testa}{ta} + \setcounter{testa}{4} +\end{sourcecode} + +Then we can use the new pattern and the new formats as +follows:\setcounter{testa}{4} +\begin{example} + \ReadCounterPattern{ta[aa]} + \ReadCounterPattern{ta[o]} + \ReadCounterPattern{ta[x]} +\end{example} + +\end{document} |