diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/cnltx/cnltx_en.tex')
| -rw-r--r-- | Master/texmf-dist/doc/latex/cnltx/cnltx_en.tex | 2468 |
1 files changed, 2468 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/cnltx/cnltx_en.tex b/Master/texmf-dist/doc/latex/cnltx/cnltx_en.tex new file mode 100644 index 00000000000..211bd4f9d0a --- /dev/null +++ b/Master/texmf-dist/doc/latex/cnltx/cnltx_en.tex @@ -0,0 +1,2468 @@ +% arara: pdflatex +% !arara: biber +% !arara: pdflatex +% arara: pdflatex +% -------------------------------------------------------------------------- +% the CNLTX bundle +% +% LaTeX source code and output +% +% -------------------------------------------------------------------------- +% Clemens Niederberger +% Web: https://github.com/cgnieder/cnltx/ +% E-Mail: contact@mychemistry.eu +% -------------------------------------------------------------------------- +% Copyright 2013 Clemens Niederberger +% +% This work may be distributed and/or modified under the +% conditions of the LaTeX Project Public License, either version 1.3 +% of this license or (at your option) any later version. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3 or later is part of all distributions of LaTeX +% version 2005/12/01 or later. +% +% This work has the LPPL maintenance status `maintained'. +% +% The Current Maintainer of this work is Clemens Niederberger. +% -------------------------------------------------------------------------- +% If you have any ideas, questions, suggestions or bugs to report, please +% feel free to contact me. +% -------------------------------------------------------------------------- +\documentclass[load-preamble+,babel-options={ngerman,english}]{cnltx-doc} +\usepackage[utf8]{inputenc} + +\usepackage{varioref} + +\usepackage{array,booktabs} +\usepackage{tikz} +\usetikzlibrary{chains} + +\setcnltx{ + name = cnltx , + title = the cnltx bundle , + version = \csname cnltx@@version\endcsname , + date = \csname cnltx@@date\endcsname , + subtitle = Documentation for \LaTeXe\ Packages or Classes , + info = \LaTeX\ tools and documenting facilities the + \texorpdfstring{\textsc{cn}}{CN} way , + authors = Clemens Niederberger , + email = contact@mychemistry.eu , + url = https://github.com/cgnieder/cnltx , + abstract = {% + A versatile bundle of packages and classes for consistent formatting of + control sequences, package options, source code examples, and writing a + package manual (including an index containing the explained control + sequences, options, \ldots).\par + The bundle also provides several other small ideas of mine such as a + mechansim for providing abbreviations \etc. Not at least it provides a + number of programming tools.% + } , + index-setup = { othercode=\footnotesize,level=\section}, + add-cmds = { + % internal macros: + cnltx@babel@options, + cnltx@bibtex@listings@style, + cnltx@caption@font,cnltx@captionlabel@font, + cnltx@define@colorscheme, + cnltx@gobble, + cnltx@ifisnum, + cnltx@ifpunctuation, + cnltx@ifsym, + cnltx@listings@style, + cnltx@mdframed@options, + cnltx@scrartcl@options, + cnltx@trailpunct, + cnltx@treat@lst@index, + % official macros: + AD,AM,BC, + changedversion,cls, + cnltxacronym, + cnltxat,cnltxbang,cnltxequal, + code,codefont,command,cs,csidx, + ctan,CTAN,CTANurl, + darg, + DeclareCounterRepresentation, + Default,default, + definecolorscheme, + dsh, + eg,env,envidx,environment, + expandable, + indexcs, + inputexample,inputsidebyside,inputsourcecode, + key,keybool,keychoice,keyval, + lppl,LPPL, + marg,Marg,module,Module, + newabbr,newarg, + newcounterrepresentation, + newname, + newnote, + newpackagename, + newinputsourcefilecmd, + newsourcecodeenv, + oarg,opt,option, + PM,pkg, + providecounterrepresentation, + renewcounterrepresentation, + sarg,setcnltx,sinceversion,sourceformat, + unexpandable, + usf,usw, + vgl,Vgl, + zB,ZB + }, + add-silent-cmds = { + @foo, + ab,AB, + at, + carlisle, + cd, + circled,circlenumber, + cnltx, + foo, + foothree, + GetTranslation, + minusone,multoffourrm, + nohyperpage, + superiors@spaced, + textsu, + twodigits + } , + add-envs = { + commands, + environments, + example, + options, + sidebyside,sourcecode + }, + add-frame-options = { + innerleftmargin=2em + } +} + +\defbibheading{bibliography}[\bibname]{\section{#1}} + +\makeatletter +\newcommand*\cnltxhyphen{\texorpdfstring{\cnltx@hyphen}{-}} +\newrobustcmd*\cnltx@hyphen{\penalty\@M-\hskip\z@skip} +\makeatother + +\newpackagename\cnltxbase{cnltx\cnltxhyphen base} +\newpackagename\cnltxcsnames{cnltx\cnltxhyphen csnames} +\newpackagename\cnltxdoc{cnltx\cnltxhyphen doc} +\newpackagename\cnltxexample{cnltx\cnltxhyphen example} +\newpackagename\cnltxlistings{cnltx\cnltxhyphen listings} +\newpackagename\cnltxtools{cnltx\cnltxhyphen tools} + +\newnote*\bypackage[1]{provided by \csname cnltx#1\endcsname} +\newnote*\byclass{provided by \cnltxdoc} + +\newname\oberdiek{Heiko}{Oberdiek} +\newname\egreg{Enrico}{Gregorio} +\newname\heinz{Carsten}{Heinz} +\newname\moses{Brooks}{Moses} +\newname\hoffmann{Jobst}{Hoffmann} +\newname\daniel{Marco}{Daniel} + +\newcommand*\file[1]{\code{#1}} +\newcommand*\latin[1]{\cnltxlatin{#1}} + +\newcommand*\PDF{\cnltxacronym{PDF}{pdf}} + +\newenvironment{colors} + {% + \def\colour##1{\item[]\code{\textcolor{##1}{##1}}\hfill\newline}% + \cnltxlist + } + {\endcnltxlist} + +\def\at{\cnltxat} +\def\bang{\cnltxbang} +\def\equal{\cnltxequal} + +\newcommand*\BibTeX{\texorpdfstring{\hologo{BibTeX}}{BibTeX}} + +\begin{document} + +\part{About The Bundle} + +\section{Background} + +The \cnltx\ bundle contains different packages and classes\footnote{Well, + \emph{one} class for the time being,}. I developed it as a successor of my +class \cls{cnpkgdoc}~\cite{cls:cnpkgdoc} that I used until now for writing the +documentation of my packages. The intention behind the new bundle is a +cleaner interface and less unnecessary ballast, hence the separation into +packages and classes. This is actually a bit of a contradiction: the document +class \cnltxdoc\ loads \emph{all} packages of the bundle which makes it more +feature-rich than \cls{cnpkgdoc} eber used to be. The bundle provides source +code environments that also print the output and defines quite a lot of macros +for formatting of control sequence names, package names, package options and +so on. + +Part of the motivation is also that users have asked me how I created the +manuals for my packages. Now I can refer to this bundle. + +Another reason for the splitting into separate packages is -- besides the +advantage of easier maintenance -- is that I wanted to add programming tools +that I often use into \cnltxbase\ which may allow me (and others) to use them +for other packages, too, without having to define them each time. So it is +quite likely that \cnltxbase\ will get extended in the future. + +The bundle provides \pkg{listings} style for \LaTeX\ code, bibliography +database files and index style files. It provides a \pkg{biblatex} citation +and bibliography style closely linked to \cnltxdoc. It provides a +bibliography database file containing many \LaTeX\ packages. It +provides\ldots\ Let's stop here. You see that the bundle provides a lot of +different features which explains why this manual is more than 50~pages long. + +The most detailed documentation for the bundle is as always the source code of +the \file{sty} and \file{cls} files but I'm trying to provide a documentation +as comprehensive as possible. Reading the source files may show how things +are implemented but the intended use only becomes clear when you read this +manual. + +The bundle reflects the fact that I haven't started using literate +programming, yet. I don't use \code{docstrip} and don't write \file{dtx} +files but always write the \file{sty} or \code{cls} files directly. I write +the manual always at the same time but as a separate file. While I'm entirely +aware of the advantages of literate programming I never could bring myself to +start to use it myself. As a consequence I have no idea if this bundle can be +used for it or not. + +Source code formatting is done with the help of the powerful +\pkg{listings} package~\cite{pkg:listings} by \heinz\ and later \moses, now +maintained by \hoffmann. The only real drawback I have found with it is +recognizing starred und un-starred versions of an environment as different +keywords. This does not seem to be possible which is why indexing of such +environments will lead to wrong page numbers. + +The fancy frames of the source code examples are realized with the +\pkg{mdframed} package by \daniel~\cite{pkg:mdframed}, loaded with the option +\keyis*{framemethod}{tikz}. + +Besides all this I included some other ideas of mine in this bundle which are +all provided by \cnltxtools. This includes a mechansim for defining clever +abbreviations or macros that make it easy to index names the same way +\pkg{biblatex} does. + + +\section{Bundled Packages, Classes and Files} + +The \cnltx\ bundle currently bundles the following packages, classes and +files: +\begin{itemize} + \item \cnltxbase\ -- a package that defines base macros for error-messaging, + expansion control, tokenlist manipulation and defining of expandable + macros. It also provides color definitions and defines a few color + schemes for the \cnltxdoc\ class. All other packages and classes of the + \cnltx\ bundle load this package. This package can be used + stand-alone. \\ + \verbcode+\usepackage{cnltx-base}+ + \item \cnltxdoc\ -- a class for writing package manuals. Loads + \cnltxexample\ and \cnltxtools\ and implicitly all other files of the + bundle. \\ + \verbcode+\documentclass{cnltx-doc}+ + \item \cnltxexample\ -- a package that defines macros and environments for + describing control sequences and options and for including source code. + Loads \cnltxlistings. This package can be used stand-alone. \\ + \verbcode+\usepackage{cnltx-example}+ + \item \sinceversion{0.4}\cnltxlistings\ -- a package that defines the + listings language `BibTeX'. Also defines a list of highlighted control + sequence names and environment names, loaded by \cnltxexample. The + additional control sequence and environment names used to be defined in + \cnltxcsnames. That package got removed and its contents are now provided + by \cnltxlistings. This package can be used stand-alone. \\ + \verbcode+\usepackage{cnltx-listings}+ + \item \sinceversion{0.2}\cnltxtools\ -- a package that defines tools used by + \cnltxdoc\ that are unrelated to \LaTeX\ documentation \latin{per se}. + This package can be used stand-alone. \\ + \verbcode+\usepackage{cnltx-tools}+ + \item \file{cnltx.ist} -- an index style file that is used when the option + \option{add-index} for \cnltxdoc\ is activated and the option + \option{index-style} is not used. + \item \sinceversion{0.4}\file{cnltx.bib} -- a bibliography file that + contains a small but growing number of package entries. Used by + \cnltxdoc\ when the \option{add-bib} is used. + \item \sinceversion{0.4}\file{cnltx.bbx}, \file{cnltx.cbx} and + \file{cnltx.dbx} -- files related to the \pkg{biblatex} style + \code{cnltx}. The \pkg{biblatex} style defined in those files is used + when the \option{add-bib} for \cnltxdoc\ is used. +\end{itemize} + +\section{License and Requirements}\label{sec:license} +\license + +The \cnltxbase\ package loads the following packages: +\needpackage{pgfopts}~\cite{pkg:pgfopts}, +\needpackage{etoolbox}~\cite{pkg:etoolbox}, +\pkg{ltxcmds}\footnote{\CTANurl{oberdiek}}~\cite{pkg:ltxcmds}, +\needpackage{trimspaces}~\cite{pkg:trimspaces} and +\needpackage{xcolor}~\cite{pkg:xcolor}. + +The \cnltxdoc\ class loads the packages \cnltxbase, \cnltxexample, +\needpackage{ulem}~\cite{pkg:ulem}, +\pkg{translations}~\cite{pkg:translations}, +\needpackage[macros/latex/required/tools]{multicol}~\cite{pkg:multicol}, +\needpackage[macros/latex/contrib/ms]{ragged2e}~\cite{pkg:ragged2e}, +\needpackage{marginnote}~\cite{pkg:marginnote} and +\needpackage{hyperref}~\cite{pkg:hyperref}. It is a wrapper class for the +\KOMAScript\ class +\cls{scrartcl}\footnote{\CTANurl{koma-script}}~\cite{bnd:koma-script}. The +class has the option \option{load-preamble} which when used will load +additional packages, see section~\vref{sec:preamble} for details. + +The \cnltxexample\ package loads the packages: \cnltxbase, \cnltxlistings, +\cnltxtools, \needpackage{translations}, +\needpackage{mdframed}~\cite{pkg:mdframed} and +\needpackage{idxcmds}~\cite{pkg:idxcmds}. + +The \cnltxlistings\ package loads the packages \cnltxbase, +\needpackage{listings}~\cite{pkg:listings} and +\needpackage{catchfile}~\cite{pkg:catchfile}. + +The \cnltxtools\ package loads the packages \cnltxbase\ and +\needpackage[macros/latex/contrib/oberdiek]{accsupp}~\cite{pkg:accsupp}. + +All other packages that are loaded are loaded by the mentioned packages and +not directly by any of the packages or classes of the \cnltx\ bundle. Like +all of my packages \cnltx\ implicitly relies on an up to date \TeX\ +distribution. + +\part{Details of Available Commands, Environments and Options} + +\section{Options and Setup} +The \cnltx\ bundle has a large number of options. The \cnltxdoc\ class only +knows a few options (described in section~\vref{sec:class:options}) as +\emph{class} options, though. All other options regardless if they're defined +by a package or a class can and should be set with the setup command: +\begin{commands} + \command{setcnltx}[\marg{options}] + Setup command for the \cnltx\ bundle. This command is provided by + \cnltxbase. +\end{commands} +The source code environments defined by the \cnltxexample\ package also have +optional arguments that can be used to set the options for the environment +locally. + +\section{Available Commands} +\subsection{Description of Macros, Environments and Options}\label{sec:cmds:macros} + +The commands described in this section all are provided by the \cnltxexample\ +package\bypackage{example}. They all are related to the typesetting of +provided macros, options and the like. + +\begin{commands} + \command{code}[\marg{arg}] + Formatting of source code. This is \emph{no} verbatim command. Used + internally in the following commands. + \command{verbcode}[\meta{char}\meta{code}\meta{char}] + \sinceversion{0.2}A verbatim command that uses the same formatting as the + source code example environments, \cf\ section~\ref{sec:usage:examples}. + This is a wrapper for \cs*{lstinline} which loads the corresponding + style. + \command{cs}[\sarg\marg{name}] + Format the control sequence \meta{name}, \cs{cs}\Marg{name}: + \cs*{name}. Adds a corresponding index entry. The starred form does not + add an index entry. + \command{csidx}[\marg{name}] + Adds an index entry but does not typeset the control sequence + \meta{name}. + \command{env}[\sarg\marg{name}] + Format the environment \meta{name}, \cs{env}\Marg{name}: + \env*{name}. Adds a corresponding index entry with a hint that the entry + refers to an environment. The starred form does not add an index entry. + \command{envidx}[\marg{name}] + Adds an index entry but does not typeset the environment \meta{name}. + \command{meta}[\marg{meta}] + Description of an argument, \cs{meta}\Marg{meta}: \meta{meta}. + \command{marg}[\marg{arg}] + A mandatory argument. \meta{arg} is formatted with \cs{meta} if it is not + blank, \cs{marg}\Marg{arg}: \marg{arg}. + \command{Marg}[\marg{arg}] + \sinceversion{0.2}A mandatory argument. \meta{arg} is formatted with + \cs{code} if it is not blank, \cs{Marg}\Marg{arg}: \Marg{arg}. + \command{oarg}[\marg{arg}] + An optional argument. \meta{arg} is formatted with \cs{meta} if it is not + blank, \cs{oarg}\Marg{arg}: \oarg{arg}. + \command{Oarg}[\marg{arg}] + \sinceversion{0.2}An optional argument. \meta{arg} is formatted with + \cs{code} if it is not blank, \cs{Oarg}\Marg{arg}: \Oarg{arg}. + \command{darg}[\marg{arg}] + An argument with parentheses as delimiters. \meta{arg} is formatted with + \cs{meta} if it is not blank, \cs{darg}\Marg{arg}: \darg{arg}. + \command{Darg}[\marg{arg}] + \sinceversion{0.2}An argument with parentheses as delimiters. \meta{arg} + is formatted with \cs{code} if it is not blank, \cs{Darg}\Marg{arg}: + \Darg{arg}. + \command{sarg} + An optional star argument, \cs{sarg}: \sarg. + \command{option}[\sarg\marg{name}] + An option \meta{name}, \cs{option}\Marg{name}: \option{name}. Adds a + corresponding index entry. The starred form does not add an index entry. + \command{optionidx}[\marg{name}] + Adds an index entry but does not typeset the option \meta{name}. + \command{module}[\sarg\marg{name}] + A module \meta{name}, \cs{module}\Marg{name}: \module{name}. Adds a + corresponding index entry. The starred form does not add an index entry. + In some of my packages I like to organize options by grouping them in + different classes that I call ``modules''. This command refers to those + modules. + \command{moduleidx}[\sarg\marg{name}] + Adds an index entry but does not typeset the option \meta{name}. + \command{key}[\sarg\code{-}\marg{name}\marg{value}] + A key \meta{name} with value \meta{value}, the optional star prevents an + index entry, the optional \code{-} strips the braces around \meta{value}; + \cs{key}\Marg{key}\Marg{value}: \key{key}{value}; + \cs{key}\code{-}\Marg{key}\Marg{value}: \key-{key}{value} + \command{keyis}[\sarg\marg{name}\marg{value}] + \sinceversion{0.2}A key \meta{name} set to value \meta{value}, the + optional star prevents an index entry, \cs{key}\Marg{keyis}\Marg{value}: + \keyis{key}{value}. + \command{choices}[\marg{clist of choices}] + A list of choices, \cs{choices}\Marg{one,two,three}: + \choices{one,two,three} + \command{choicekey}[\marg{name}\marg{clist of choices}] + A key \meta{name} with a list of possible values, + \cs{choicekey}\Marg{key}\Marg{one,two,three}: + \choicekey{key}{one,two,three} + \command{boolkey}[\marg{name}] + A boolean key \meta{name} with choices \code{true} and \code{false}, + \cs{boolkey}\Marg{key}: \boolkey{key} + \command{default}[\marg{value}] + Markup for a default choice, + \cs{choices}\Marg{one,\cs{default}\Marg{two},three}: + \choices{one,\default{two},three} +\end{commands} + + +\subsection{Versioning Commands, Licensing and Related Stuff}\label{sec:cmds:versioning} + +The commands described in this section are provided by the \cnltx\ +class\byclass\ except where indicated differently. These commands are related +to information about the legal stuff of a package and where to find it on th +world wide web. + +\begin{commands} + \command{sinceversion}[\marg{version}] + \sinceversion{0.0}Gives a sidenote like the one on the left. + \command{changedversion}[\marg{version}] + \changedversion{0.0}Gives a sidenote like the one on the left. + \command{newnote}[\sarg\marg{cs}\oarg{num}\oarg{optional}\marg{definition}] + Defines a note like \cs{sinceversion}. The syntax of the command is the + same as the one of \cs*{newcommand}. \cs{sinceversion} was defined as + follows:\\ + \verbcode+\newnote*\sinceversion[1]{Introduced in version~#1}+ + \command{newpackagename}[\marg{cs}\marg{name}] + Define a comand \meta{cs} that prints \meta{name} formatted like \cnltx, + \ie\ in small caps and colored with the color \code{cnltx} (see + section~\ref{sec:actual-used-color}). + \command{lppl} + Typesets ``\lppl'' and adds a corresponding index entry. + \command{LPPL} + Typesets ``\LPPL'' and adds the same index entry as \cs{lppl}. + \command{license}[\sarg\oarg{maintenance status}]\Default{maintained} + \changedversion{0.2}Typesets `\license*'. The un-starred variant adds a + \cs*{par}. + \command{ctan} + Typesets ``\ctan'' and adds a corresponding index entry. + \command{CTAN} + Typesets ``\CTAN'' and adds the same index entry as \cs{ctan}. + \command{pkg}[\sarg\marg{package}] + \bypackage{example}Format the package name \meta{package} and add an + index entry. The starred variant adds nothing to the index. + \command{pkgidx}[\marg{package}] + \bypackage{example}Add an index entry for the package \meta{package}. + \command{cls}[\sarg\marg{class}] + \bypackage{example}Format the class name \meta{class} and add an index + entry. The starred variant adds nothing to the index. + \command{clsidx}[\marg{class}] + \bypackage{example}Add an index entry for the class \meta{class}. + \command{CTANurl}[\oarg{directory}\marg{name}] + Writes a \ctan\ link like the ones in section~\vref{sec:license} in the + footnotes. The predefined directory is \code{macros/latex/contrib}. The + link address will be:\par + \code{http://mirrors.ctan.org/\meta{directory}/\meta{name}/}. + \command{needpackage}[\oarg{directory}\marg{name}] + \sinceversion{0.2}A wrapper for + \verbcode+\pkg{#2}\footnote{\CTANurl[#1]{#2}}+ + \command{needclass}[\oarg{directory}\marg{name}] + \sinceversion{0.2}A wrapper for + \verbcode+\cls{#2}\footnote{\CTANurl[#1]{#2}}+ +\end{commands} + +\begin{example} + \newpackagename{\foothree}{foo-3}% + now \foothree\ looks like \cnltx. +\end{example} + +\subsection{Input Source Code Files} +Similar to the environments described in section~\vref{sec:envs:sourcecode} +\cnltxexample\ provides a few commands for inputting source code files, +formatting and printing the source code and inputting the file directly. +\begin{commands} + \command{inputexample}[\oarg{options}\marg{file name}] + The equivalent of the \env{example} environment, see + section~\vref{sec:envs:sourcecode}. + \command{inputsidebyside}[\oarg{options}\marg{file name}] + The equivalent of the \env{sidebyside} environment, see + section~\vref{sec:envs:sourcecode}. + \command{inputsourcecode}[\oarg{options}\marg{file name}] + The equivalent of the \env{sourcecode} environment, see + section~\vref{sec:envs:sourcecode}. + \command{implementation}[\oarg{options}\marg{file name}] + \sinceversion{0.5}A wrapper for + \verbcode+\lstinputlisting[style=cnltx,#1]{#2}+ +\end{commands} + +It is possible to define further commands like this: +\begin{commands} + \command{newinputsourcefilecmd}[\oarg{option}\marg{control sequence}] + Defines \meta{control sequence} as a new source code input command where + \meta{options} are preset. +\end{commands} + +The existing commands have been defined like this: +\begin{sourcecode} + \newinputsourcefilecmd\inputexample + \newinputsourcefilecmd[side-by-side]\inputsidebyside + \newinputsourcefilecmd[code-only]\inputsourcecode +\end{sourcecode} + +\section{Available Environments}\label{sec:envs} +\subsection{Description Environments}\label{sec:envs:description} +\cnltxdoc\ defines some description environments used to describe macros, +environments or options. + +\begin{environments} + \environment{commands} + A description-like environment for describing commands. While this + environment is a list internally and thus recognizes \cs*{item} own + commands are used to describe macros. They are explained in + section~\vref{sec:usage:commands}. + \environment{options} + A description-like environment for describing options. While this + environment is a list internally and thus recognizes \cs*{item} own + commands are used to describe options. They are explained in + section~\vref{sec:usage:options}. + \environment{environments} + A description-like environment for describing environments. While this + environment is a list internally and thus recognizes \cs*{item} own + commands are used to describe environments. They are explained in + section~\vref{sec:usage:environments}. +\end{environments} + +These environments are lists all using the same internal \cs*{list}. The +setup of this list can be changed via an option: + +\begin{options} + \keyval{list-setup}{definitions}{} + \Default{\cs*{leftmargin}=0pt \cs*{labelwidth}=2em \cs*{labelsep}=0pt + \cs*{itemindent}=-1em } + The setup of the \cs*{list} used by the \env{commands}, \env{options} and + \env{environments} environments. +\end{options} + +\subsection{Source Code Environments}\label{sec:envs:sourcecode} +\cnltxexample\ defines the following environments that are used to display +source code and possibly the output of the source code, too. + +\begin{environments} + \environment{example}[\oarg{options}] + This environment is a formatted verbatim environment that also inputs the + output of the inputted code. This environment is described in + section~\vref{sec:usage:examples}. + \environment{sidebyside}[\oarg{options}] + This environment is a formatted verbatim environment that also inputs the + output of the inputted code. Source and output are printed side-by-side. + This environment is described in section~\vref{sec:usage:examples}. + \environment{sourcecode}[\oarg{options}] + This environment is a formatted verbatim environment. This environment is + described in section~\vref{sec:usage:examples}. +\end{environments} + +\sinceversion{0.2}In each of these environments certain hooks are provided +that can be used to add definitions you like: +\begin{options} + \keyval{pre-code}{definitions} + \meta{definitions} are placed before the source code is inserted. + \keyval{after-code}{definitions} + \meta{definitions} are placed after the source code is inserted. + \keyval{pre-source}{definitions} + \meta{definitions} are placed before the output of the source code is + inserted. + \keyval{after-source}{definitions} + \meta{definitions} are placed after the output of the source code is + inserted. +\end{options} + +It is possible to define further environments like this: +\begin{commands} + \command{newsourcecodeenv}[\oarg{option}\marg{name}] + Defines \meta{name} as a new source code environment where + \meta{options} are preset. +\end{commands} + +The existing environments have been defined like this: +\begin{sourcecode} + \newsourcecodeenv{example} + \newsourcecodeenv[side-by-side]{sidebyside} + \newsourcecodeenv[code-only]{sourcecode} +\end{sourcecode} + +\section{Usage of the Various Functions} +\subsection{Command Descriptions}\label{sec:usage:commands} +Inside of the environment \env{commands} that was introduced in +section~\vref{sec:envs:description} items are input via the following command: +\begin{commands} + \command{command}[\sarg\marg{name}\oarg{stuff after}] + This macro formats a control sequence with \cs{cs} and puts a line break + after it. The optional argument allows printing things directly after the + command name and can thus be used for adding arguments. The star prevents + the creation of an index entry. + \command{Default}[\sarg\code{!}\marg{code}] + \changedversion{0.3}This command can be placed after \cs{command} or + \cs{opt} in order to give a default definition of a macro or a default + value of an option. The definition will then be placed on the same line + flush right. The star prevents the insertion of \cs*{newline} after it. + The optional bang adds the information that an option is mandatory, \ie\ + has to be set. + \command{expandable} + \sinceversion{0.5}Adds the symbol \textcolor{expandable}{\expandablesign} + to the left of a command in the margin to indicate that the command is + expandable. This command should be used \emph{immediately} before + \cs{command}. + \command{unexpandable} + \sinceversion{0.5}Adds the symbol \textcolor{unexpandable}{\expandablesign} + to the left of a command in the margin to indicate that the command is not + expandable. This command should be used \emph{immediately} before + \cs{command}. + \command{expandablesign}\Default{\cs*{textasteriskcentered}} + \sinceversion{0.5}The macro that holds the sign used by \cs{expandable} + and \cs{unexpandable}. +\end{commands} + +\begin{example} + \begin{commands} + \command{cs} + This is about foo bar baz. + \command{cs}[\marg{arg}] + This one has an argument. + \command{cs}[\sarg\oarg{option}] + This has a star variant and an optional argument. + \command{cs}\Default{foo bar} + This one has the default replacement text \code{foo bar} + \expandable\command{cs} + This macro is expandable. + \end{commands} +\end{example} + +The \cs{expandablesign} can of course be redefined to something else you like +better. For the sake of completeness there is an option that does exactly +this: +\begin{options} + \keyval{expandable-sign}{definition}\Default{\cs*{textasteriskcentered}} + \sinceversion{0.5}Redefines \cs{expandablesign} to \meta{definition}. +\end{options} + +\subsection{Option Descriptions}\label{sec:usage:options} +The \env{options} environment knows a few more commands to meet all the +different kinds of options. +\begin{commands} + \command{opt}[\sarg] + An option. The star prevents an index entry. + \command{keyval}[\sarg\code{-}\marg{key}\marg{value}] + A key/value option. The optional star prevents an index entry. The + optional \code{-} strips the braces around \meta{value}, see the example + below. + \command{keychoice}[\sarg\marg{key}\marg{list of choices}] + A key/value option where the value is one of a list of choices. The star + prevents an index entry. + \command{keybool}[\sarg\marg{name}] + A boolean key, that ist a choice key with choices \code{true} and + \code{false}. The star prevents an index entry. + \command{Default}[\sarg\code{!}\marg{code}] + \changedversion{0.3}This command can be placed after \cs{command} or + \cs{opt} (or any of the other commands for adding an option to the + \env{options} list) in order to give a default definition of a macro or a + default value of an option. The definition will then be placed on the + same line flush right. The star prevents the insertion of \cs*{newline} + after it. The optional bang adds the information that an option is + mandatory, \ie, it has to be set. + \command{Module}[\sarg\code{!}\marg{name}] + \sinceversion{0.3}This command can be placed after \cs{option} but before + \cs{Default} in order to determine the module the option belongs to. It + will be written in the left margin next to the option name. The star + prevents the insertion of \cs*{newline} after it. The optional bang + \emph{adds} an index entry for the module. This is somehow inconsistent + with many of the other commands where an optional star \emph{prevents} an + index entry but it fits to the functionality of \cs{Default} which is why + this syntax was chosen. +\end{commands} + +The following demonstrates how the commands would be used to create option +descriptions: +\begin{sourcecode} + \begin{options} + \opt{foo} + This makes stuff. Let's add a few more words so that the line gets + filled and we can see how the output actually looks. + \opt*{foo}\Default{bar} + This makes stuff. Let's add a few more words so that the line gets + filled and we can see how the output actually looks. + \opt{foo}\Module{bar} + This option belongs to \module*{bar}. Let's add a few more words so + that the line gets filled and we can see how the output actually + looks. + \opt{foo}\Module{bar}\Default{baz} + This option belongs to \module*{bar}. Let's add a few more words so + that the line gets filled and we can see how the output actually + looks. + \keyval{foo}{bar}\Default + This makes stuff. Let's add a few more words so that the line gets + filled and we can see how the output actually looks. + \keyval{foo}{bar}\Default! + This makes stuff. Let's add a few more words so that the line gets + filled and we can see how the output actually looks. + \keyval*{foo}{bar} + This makes stuff. Let's add a few more words so that the line gets + filled and we can see how the output actually looks. + \keyval-{foo}{bar} + This makes stuff. Let's add a few more words so that the line gets + filled and we can see how the output actually looks. + \keychoice{foo}{one,two,three} + This makes stuff. Let's add a few more words so that the line gets + filled and we can see how the output actually looks. + \keybool{foo} + This makes stuff. Let's add a few more words so that the line gets + filled and we can see how the output actually looks. + \end{options} +\end{sourcecode} + +The code above gives the following output: +\begin{options} + \opt{foo} + This makes stuff. Let's add a few more words so that the line gets + filled and we can see how the output actually looks. + \opt*{foo}\Default{bar} + This makes stuff. Let's add a few more words so that the line gets + filled and we can see how the output actually looks. + \opt{foo}\Module{bar} + This option belongs to the module \module{bar}. Let's add a few more + words so that the line gets filled and we can see how the output actually + looks. + \opt{foo}\Module{bar}\Default{baz} + This option belongs to the module \module{bar}. Let's add a few more + words so that the line gets filled and we can see how the output actually + looks. + \keyval{foo}{bar}\Default + This makes stuff. Let's add a few more words so that the line gets + filled and we can see how the output actually looks. + \keyval{foo}{bar}\Default! + This makes stuff. Let's add a few more words so that the line gets + filled and we can see how the output actually looks. + \keyval*{foo}{bar} + This makes stuff. Let's add a few more words so that the line gets + filled and we can see how the output actually looks. + \keyval-{foo}{bar} + This makes stuff. Let's add a few more words so that the line gets + filled and we can see how the output actually looks. + \keychoice{foo}{one,two,three} + This makes stuff. Let's add a few more words so that the line gets + filled and we can see how the output actually looks. + \keybool{foo} + This makes stuff. Let's add a few more words so that the line gets + filled and we can see how the output actually looks. +\end{options} + +\subsection{Environment Descriptions}\label{sec:usage:environments} +Environment descriptions are made -- unsurprisingly -- with the +\env{environments} environment. It knows the command \cs{environment}: + +\begin{commands} + \command{environment}[\sarg\marg{name}\oarg{stuff after}] + This macro prints the environment name and puts a line break + after it. The optional argument allows printing things directly after the + environment name and can thus be used for adding arguments. +\end{commands} + +\begin{example} + \begin{environments} + \environment*{foobar}[\oarg{options}] + This is environment \env*{foobar}. The star prevents it from being + added to the index. + \end{environments} +\end{example} + +\subsection{Code Examples}\label{sec:usage:examples} +Code examples can be included through the \env{example} environment or the +\env{sourcecode} environment. The \env{sourcecode} only shows the piece of +\LaTeX code while the \env{example} environment also shows the output of the +\LaTeX\ code. +\begin{sourcecode} + \begin{example} + a \LaTeX\ code example + \end{example} +\end{sourcecode} +This example would give: + +\begin{example} + a \LaTeX\ code example +\end{example} + +Both environments can be influenced by options: +\begin{options} + \keybool{code-only}\Default{false} + Only typeset the code as code but don't include it afterwards. The + code box above is an example for the usage of this option. This option + has no effect on the \env{sourcecode} environment: is is already set for + this environment. + \keybool{side-by-side}\Default{false} + Typeset source and output side by side. The code is input on the left and + the output on the right. Side by side examples are typeset in + \env*{minipage} environments with all consequences that come with them + (think of \cs*{parindent}, page breaks \ldots). Since a \code{minipage} + cannot be broken across pages the surrounding \pkg{mdframed} frame gets + the option \keyis*{nobreak}{true}. This option has no effect on the + \env{sourcecode} environment. + \keybool{code-left}\Default{true} + If \code{true} and the option \option{side-by-side} is chosen the source + code is printed on the right side else on the left. This option has no + effect on the \env{sourcecode} environment. + \keyval{code-sep}{definition}\Default{\cs*{hrulefill}} + Code that is inserted between a source code and the corresponding output + when printed below each other. This option has no effect on the + \env{sourcecode} environment. +\end{options} + +The same example again, this time using \option{side-by-side} (which is the +same as using the \env{sidebyside} environment): + +\begin{example}[side-by-side] + a \LaTeX\ code example +\end{example} + +\option{side-by-side} and \keyis{code-left}{false}: + +\begin{example}[side-by-side,code-left=false] + a \LaTeX\ code example +\end{example} + +The frame around the examples is done by the +\pkg{mdframed} package~\cite{pkg:mdframed}. It is of course possible to +customize it: +\begin{options} + \keyval{add-frame-options}{\pkg{mdframed} options}\Default + Add options to the predefined settings. + \keyval{frame-options}{\pkg{mdframed} options}{} + \Default{backgroundcolor=cnltxbg,linecolor=cnltx,roundcorner=5pt} + Overwrite the settings with new ones. +\end{options} + +The source code is formatted using the great \pkg{listings} +package~\cite{pkg:listings} by \heinz, \moses, and \hoffmann. Similar options +exist to adapt \pkg{listings}' options that are used for formatting the source +code. The predefined style has many options that will not be mentioned here. +If you're interested you can find them in \file{cnltx-example.sty} or in +section~\vref{sec:listings-sourcecode}. +\begin{options} + \keyval-{gobble}{integer}\Default{2} + The number of initial characters that is gobbled from each line. + \keyval{add-cmds}{list of csnames}\Default + A list of control sequence names that should be recognized as a command + sequence in the source code examples and should be formatted accordingly. + The control sequence names in this list will also get an index entry when + they're used in the source example. This is done internally via + \cs{csidx}. The option should be used to add the new commands that are + defined by the package for which you are writing the manual for. + \keyval{add-silent-cmds}{list of csnames} + A list of control sequence names that should be recognized as a command + sequence in the source code examples and should be formatted accordingly. + The control sequence names in this list will \emph{not} get an index entry + when they're used in the source example. There already is quite a large + but far from comprehensive list of silent commands but many are still + missing. This option allows you to extend the list on a per document + basis. + \keyval{add-listings-options}{\pkg{listings} options}\Default + Additional options for the \pkg{listings}~\cite{pkg:listings} + environments. \emph{This redefines the \code{cnltx} \pkg{listings} style + which will affect all sourcecode environments!} + \keyval{listings-options}{\pkg{listings} options} + Overwrite existing options with new ones. This can be used to build an own + style from scratch. \emph{This redefines the \code{cnltx} \pkg{listings} + style which will affect all sourcecode environments!} + \keyval{sourcecode-options}{\pkg{listings} options} + \sinceversion{0.4}These options are added to the \pkg{listings} options of + the source code environments without redefing the main style. Hence it + can be used to locally add options to a source code environment. + \keyval{add-envs}{list of environment names}\Default + Like \option{add-cmds} but for environment names. + \keyval{add-silent-envs}{list of environment names} + Like \option{add-silent-cmds} but for environment names. +\end{options} + +\subsection{Example File} +Let's say you're documenting a package called \code{mypackage} that provides +the command \cs*{mycommand} and the environment \env*{myenv}. The basic +manual setup could then look something like this: + +\begin{sourcecode} + \documentclass[load-preamble]{cnltx-doc} + \usepackage[T1]{fontenc} + \usepackage[utf8]{inputenc} + \setcnltx{ + package = mypackage , + authors = John Doe , + email = john@doe.com , + add-cmds = {mycommand} , + add-envs = {myenv} + } + \begin{document} + ... + \end{document} +\end{sourcecode} + +\subsection{Additional Functionality Provided by \cnltxbase} +The \cnltxbase\ package's main purpose is to provide programming facilities. +Most of its macros are listed in section~\ref{sec:defined-cnltxbase}. +However, I like to explain some of its features in a bit more detail. + +\subsubsection{Looking for Trailing Punctuation} +The command \cs{cnltx\at ifpunctuation} is is a conditional that detects if a +punctuaction mark follows and acts depending on it. What counts as a +punctuation mark can be set by the user. + +\begin{commands} + \command{cnltx\at ifpunctuation}[\sarg\oarg{punctuation + marks}\marg{true}\marg{false}\meta{trailing punctuation}] + The starred version does not gobble the trailing punctuation while the + unstarred does. That's why in the unstarred version you can also use + \cs{cnltx\at trailpunct} to access the gobbled punctuation mark. The + optional argument sets the punctuation marks that should be considered for + this use only. +\end{commands} +\begin{options} + \keyval{set-trail-punct}{punctuation marks}\Default{,.!?;:} + Sets the default list of punctuation marks that should be checked if the + optional argument of \cs{cnltx\at ifpunctuation} is not used. +\end{options} + +The usage is probably self-explaining: +\begin{example} + \makeatletter + \cnltx@ifpunctuation{(test\cnltx@trailpunct)}{(test)}!\par + \cnltx@ifpunctuation[.]{(test\cnltx@trailpunct)}{(test)}!\par + a punctuation mark \cnltx@ifpunctuation*{follows}{doesn't follow}!\par + a full stop \cnltx@ifpunctuation*[.]{follows}{doesn't follow}! +\end{example} + +If the non-starred variant has gobbled a \cs*{par} the \cs*{par} is placed +back: + +\begin{example} + \makeatletter + \def\test{\cnltx@ifpunctuation{(test\cnltx@trailpunct)}{(test)}}% + \makeatother + \test + + \test. + + \test{} . +\end{example} + +\subsubsection{Counter Representation Commands}\label{sec:count-repr-comm} +\minisec{Background} + +A counter representation command like \cs*{arabic}\Marg{section} always is a +command that calls an associated internal command (\cs*{@arabic} in the case +of our example) that acts on the count associated with the counter: +\begin{sourcecode} + \def\arabic#1{\expandafter\@arabic\csname c@#1\endcsname} + \def\@arabic#1{\number #1} +\end{sourcecode} +The command \cs*{arabic}\marg{counter} builds a command sequence +\cs*{c@\meta{counter}} from its argument \meta{counter}. It then calls the +internal command \cs*{@arabic} that takes this command sequence as an +argument. The command sequence \cs*{c@\meta{counter}} is the count (in the +\TeX\ sense) that is associated with the counter \meta{counter}, \ie, it holds +the actual number. The command \cs*{@arabic} now simply typesets the integer +value of the count. + +The same holds for every counter representation command. The principle always +is as follows: +\begin{sourcecode} + \def\foo#1{\expandafter\@foo\csname c@#1\endcsname} + \def\@foo#1{do something with #1 (where #1 is a count)} +\end{sourcecode} +This means in order to get a new counter representation command you actually +need to define \emph{two} macros. + +\cnltxbase\ defines an interface that allows to define both commands at once +without having to think about \cs*{expandafter}, associated counts, internal +command names and so on. The only thing left to do is choosing a name for the +counter representation and providing a valid definition of what should happen +with the (integer) value of the counter. + +\minisec{New Commands} + +\begin{commands} + \command{DeclareCounterRepresentation}[\marg{command}\marg{definition}] + Declares a new counter representation command and its internal equivalent. + In the \meta{definition} \code{\#1} is used to refer to the counter + \emph{number}, that is, the value of \cs*{c@\meta{counter}}. This command + will silently overwrite any existing definition. + \command{newcounterrepresentation}[\marg{command}\marg{definition}] + Defines a new counter representation command and its internal equivalent. + In the \meta{definition} \code{\#1} is used to refer to the counter + \emph{number}, that is, the value of \cs*{c@\meta{counter}}. This command + will issue an error if either the user command or the internal command + (\cf\ \cs*{arabic} and \cs*{@arabic}) already exist. + \command{providecounterrepresentation}[\marg{command}\marg{definition}] + Provides a new counter representation command and its internal equivalent. + In the \meta{definition} \code{\#1} is used to refer to the counter + \emph{number}, that is, the value of \cs*{c@\meta{counter}}. This command + will define the commands only if neither the user command nor the internal + command (\cf\ \cs*{arabic} and \cs*{@arabic}) already exist and will do + nothing if either of them exist. + \command{renewcounterrepresentation}[\marg{command}\marg{definition}] + Redefines an existing counter representation command and its internal + equivalent. In the \meta{definition} \code{\#1} is used to refer to the + counter \emph{number}, that is, the value of \cs*{c@\meta{counter}}. This + command will issue an error if either the user command or the internal + command (\cf\ \cs*{arabic} and \cs*{@arabic}) or both already exist. +\end{commands} + +Let's take a look at what is actually defined by these commands: +\begin{example} + \makeatletter\ttfamily + before:\par + \meaning\arabic\par + \meaning\@arabic + + \renewcounterrepresentation\arabic{\the\numexpr#1\relax}% + after:\par + \meaning\arabic\par + \meaning\@arabic +\end{example} + +As you can see nothing bad happens. The commands are only a convenient +interface. Let's take a look at some more realistic examples. The above +redefinition was only a demonstration. For example you may want to have a +representation which calculates the displayed value from the counter value? + +\begin{example} + \newcounterrepresentation\minusone{\the\numexpr#1-1\relax}% + \newcounterrepresentation\multoffourrm{\romannumeral\numexpr(4*#1)-4\relax}% + % \newrobustcmd is provided by the `etoolbox' package + \newrobustcmd*\circlenumber[1]{% + \tikz[baseline]\node[anchor=base,draw,shape=circle]{\number#1};}% + \newcounterrepresentation\circled{\circlenumber{#1}}% + \makeatletter + \newcounterrepresentation\twodigits{\two@digits{#1}}% + \makeatother + \newcounter{test}% + \setcounter{test}{9} + + \minusone{test}\par + \multoffourrm{test}\par + \circled{test}\par + \twodigits{test} +\end{example} + +\subsubsection{Expandable Document Commands} +The commands presented in this section are highly experimental. \emph{Use them + \emph{only} if you really have to!} +\begin{commands} + \command{newexpandablecmd}[\sarg\marg{cs}\oarg{num args}\oarg{default + opt}\marg{definition}] + \sinceversion{0.7}This command has the same syntax as \cs*{newcommand}. + The difference is that if \meta{cs} is defined with an optional argument + it is still fully expandable. This comes with a cost: in order to still + being able to check for the optional argument it needs to see a following + token as argument. If it is used without optional argument and has no + mandatory arguments it may be necessary to add a trailing \cs*{empty} or + something. There's another drawback: a command \cs*{test} thus defined + cannot distinguish between \verbcode+\test[]+ and \verbcode+\test{[}]+ and + will misinterpret the second as a present optional argument. + + My recommendation is to never use this for defining a user + command.\footnote{I can see the contradiction here: if a command is no + user command there is no need for an optional argument.} Use it in code + you can control and only if you have to. + + If you define a command \emph{without} optional argument this command + falls back to \cs*{newcommand}. + \command{renewexpandablecmd}[\sarg\marg{cs}\oarg{num args}\oarg{default + opt}\marg{definition}] + \sinceversion{0.7}The equivalent of \cs*{renewcommand}. See description of + \cs{newexpandablecmd} for further details. + is to \cs*{newcommand}. + \command{provideexpandablecmd}[\sarg\marg{cs}\oarg{num args}\oarg{default + opt}\marg{definition}] + \sinceversion{0.7}The equivalent of \cs*{providecommand}. See description + of \cs{newexpandablecmd} for further details. +\end{commands} + +\subsection{Additional Functionality Provided by \cnltxtools} +\subsubsection{Commands for Defining Different Document Macros} +\label{sec:prov-defin-comm} + +The \cnltxtools\ package defines some additional macros which provide useful +functionality also in contexts \emph{not} documenting a \LaTeX\ package. + +\begin{commands} + \command{newname}[\marg{cs}\marg{first name}\marg{second name}] + Defines \meta{cs} to write out the full name and add an index entry sorted + by the last name. Also defines a starred variant of \meta{cs} that only + writes the last name but still adds the full index entry. + \command{cnltxacronym}[\marg{pdf and sort string}\marg{acronym}] + Typesets \meta{acronym} with small caps and uses \meta{pdf and sort + string} as \PDF\ string and for sorting the index entry that is added. + This command was used to define \cs{lppl} and \cs{ctan}. \emph{This is + not intended as a replacement for packages like + \pkg*{acro}~\cite{pkg:acro} or \pkg*{glossaries}\cite{pkg:glossaries}!} + In fact it is a ``poor man's'' solution that allows me not to require one + of those packages. + \command{newabbr}[\sarg\marg{control sequence}\marg{definition}] + Defines the abbreviation \meta{control sequence} with the definition + \meta{definition}. The star argument prevents that a dot is added at the + end of the definition. An error is raised if \meta{control sequence} + already exists. + \command{renewabbr}[\sarg\marg{control sequence}\marg{definition}] + Redefines the abbreviation \meta{control sequence} with the definition + \meta{definition}. The star argument prevents that a dot is added at the + end of the definition. An error is raised if \meta{control sequence} does + not exist already. + \command{defabbr}[\sarg\marg{control sequence}\marg{definition}] + Defines or overwrites the abbreviation \meta{control sequence} with the + definition \meta{definition}. The star argument prevents that a dot is + added at the end of the definition. + \command{cnltxtimeformat}[\marg{abbreviation}]\Default{\cs*{textsc}\Marg{\cs*{,}\#1}} + Used in some predefined abbreviations. + \command{cnltxlatin}[\marg{abbreviation}]\Default{\cs*{textit}\Marg{\#1}} + Used in some localization strings. +\end{commands} + +\begin{options} + \keyval{acronym-format}{definition}\Default{\cs*{scshape}} + Formatting of the acronyms as typeset with \cs{cnltxacronym}. +\end{options} + +A short example of the usage of \cs{newname} and \cs{cnltxacronym}: +\begin{example} + \newname\carlisle{David}{Carlisle}% + \carlisle\ is a well-known member of the \LaTeX\ community. \carlisle* is + the author of many packages such as \pkg*{longtable}. Take a look in the + index where you'll find \carlisle* mentioned. + + \lppl\ is defined as \cnltxacronym{LPPL}{lppl}. +\end{example} + +\subsubsection{Defining Abbreviations}\label{sec:defin-abbr} +In section~\ref{sec:prov-defin-comm} when describing \cs{newabbr} and similar +commands I said \enquote{The star argument prevents that a dot is added at the + end of the definition}. We should clarify what that means. Many +abbreviations end with a dot. Some don't which explains the starred form of +the commands. But why add a dot automatically in the first place? The +reasoning is two-fold: +\begin{itemize} + \item Suppose you add the dot explicitly in the definition but forget one or + two times that you did -- you'll end up with abbreviations followed by + \emph{two} dots! Macros defined with \cnltxtools\ recognize a + following dot and will not print a second one in those cases. + \item In a document where \cs*{nonfrenchspacing} is active the space after a + dot in the middle of a sentence should be shorter than the one after the + full stop ending a sentence. \TeX\ automatically interprets a dot + following a small letter as the end of a sentence and a dot after a + capital letter as a dot after an abbreviation inside of a sentence. + Usually you solve this by adding \cs*{@} in the appropriate places: + \verbcode+e.\,g.\@+ for a intra-sentence space and \verbcode+NASA\@.+ for + a inter-sentence space. The dot added by \cnltxtools\ always will be + followed by a intra-sentence space. If you add a dot explicitly it will + be your responsibility. Per default it will then act like a dot after a + small letter. +\end{itemize} + +Let's see some example: +\begin{example}[side-by-side] + \ttfamily% <= this will amplify the visual effect of \nonfrenchspacing + \newabbr\ab{a.b}% + \newabbr\AB{A.B}% + \newabbr*\cd{c.d.}% + \ab\ and some words\par + \ab. and some words\par + \AB\ and some words\par + \AB. and some words\par + \cd\ and some words +\end{example} + +Beware: \cnltxtools\ will only leave the dot out if one follows directly in +the input! That means that spaces are not ignored. However, of course \TeX\ +ignores spaces after macro names so usually this won't be an issue. If you +define an abbreviation with a macro name consisting of one non-letter where +spaces are not ignored you have to keep this fact in mind, though. + +\subsubsection{Predefined Abbreviations} +\cnltxtools\ already provides a bunch of abbreviations defined with its +\cs{newabbr} command. + +\minisec{Abbreviations that allow Localization}\label{sec:abbr-that-allow} + +\cnltxtools\ defines a few abbreviations that are sensitive to \pkg{babel} +settings. Currently only translations for English and German are provided and +the definition falls back to the English version if you're using a language +other than those. It is possible to add further localization strings quite +easily, see section~\ref{sec:language-support}. + +\begin{commands} + \command{ie} + Prints \enquote{\ie} or \enquote{\foreignlanguage{ngerman}{\ie}} + \command{eg} + Prints \enquote{\eg} or \enquote{\foreignlanguage{ngerman}{\eg}} + \command{etc} + Prints \enquote{\etc} or \enquote{\foreignlanguage{ngerman}{\etc}} + \command{cf} + Prints \enquote{\cf} or \enquote{\foreignlanguage{ngerman}{\cf}} +\end{commands} + +All of these macros add a final dot followed by \cs*{@} \emph{except} if a dot +\emph{directly} follows the macro. + +\begin{example}[side-by-side] + \eg\ and some following text\par + \eg, and some following text\par + \eg. and some following text\par + \selectlanguage{ngerman} + \eg\ and some following text\par + \eg, and some following text\par + \eg. and some following text +\end{example} + +\minisec{German Abbreviations}\label{sec:german-abbreviations} + +The following abbreviations are not sensitive to localization are and only of +use in a German text. Although they're defined: \emph{please} do not use +abbreviations at the start of a sentence! +\begin{commands} + \command{dsh} + Prints \enquote{\dsh} + \command{Dsh} + Prints \enquote{\Dsh} + \command{usf} + Prints \enquote{\usf} + \command{usw} + Prints \enquote{\usw} + \command{uswusf} + Prints \enquote{\uswusf} + \command{zB} + Prints \enquote{\zB} + \command{ZB} + Prints \enquote{\ZB} + \command{vgl} + Prints \enquote{\vgl} + \command{Vgl} + Prints \enquote{\Vgl} +\end{commands} + +These macros behave the same as the ones described in +section~\vref{sec:abbr-that-allow}. + +\begin{example}[side-by-side] + \dsh\ und weiterer Text\par + \dsh. und weiterer Text\par + \usw\ und weiterer Text\par + \usw. und weiterer Text\par + \usf\ und weiterer Text\par + \usf. und weiterer Text\par + \zB\ und weiterer Text\par + \zB. und weiterer Text +\end{example} + +\minisec{Time related Abbreviations}\label{sec:time-relat-abbr} + +The abbreviations presented in this section differ from the others in that +they're formatted by the command \cs{cnltxtimeformat}\marg{}, see +section~\vref{sec:prov-defin-comm}. +\begin{commands} + \command{AM} + Prints \enquote{\AM} + \command{PM} + Prints \enquote{\PM} + \command{AD} + Prints \enquote{\AD} + \command{BC} + Prints \enquote{\BC} +\end{commands} + +In their current definition these abbreviations are meant to be used +\emph{directly} after the time of day or the date, respectively. + +\begin{example}[side-by-side] + She left for work before 6\AM, but + did not arrive until 12\PM. The + interval 5\BC--5\AD\ is one year + shorter than the interval + 95\AD--105\AD. +\end{example} + +\section{Formatting Possibilities}\label{sec:cmds:formatting} + +One of the goals I wanted to achieve with this package is a consistent look +and an easy interface for customization. No font choice and no color choice +is fixed. In this section ways to change the formatting are shown. + +The formatting of the different commands provided by \cnltx\ and various other +properties can be changed in two ways: either by redefining the internal +commands that are used for the formatting or by setting a corresponding +option. Both variants are described in the next subsections. + +How the colors should be changed is described in section~\vref{sec:colors}. + +\subsection{Formatting by Redefining Hooks} + +You can change the formatting by redefining the following commands. They're +all defined by the \cnltxexample\ package except where indicated differently. + +\begin{commands} + \command{codefont}\Default{\cs*{ttfamily}} + This command is used for all formatting of source code. + \command{sourceformat}\Default{\cs{codefont}\cs*{small}} + Formatting of the listings. + \command{exampleformat}\Default + Special formatting of the output of a listing. + \command{versionnoteformat}\Default{\cs*{footnotesize}\cs*{sffamily}\cs*{RaggedRight}} + \byclass Formatting of the notes introduced in section~\vref{sec:cmds:versioning}. + \command{packageformat}\Default{\cs*{sffamily}} + The formatting of package names. + \command{classformat}\Default{\cs*{sffamily}} + The formatting of class names. + \command{argumentformat}\Default{\cs*{normalfont}\cs*{itshape}} + The formatting of \cs{meta}\marg{meta}. +\end{commands} + +\begin{example} + \renewcommand*\codefont{\sffamily\bfseries} + \code{foo} and \cs*{bar}, option \option{baz} +\end{example} + +\subsection{Formatting by Setting Options} + +You can change the formatting of by setting the following options. They're all +defined by the \cnltxexample\ package except where indicated differently. + +\begin{options} + \keyval{title-format}{definition}\Default{\cs*{bfseries}\cs*{scshape}} + \sinceversion{0.2}Formatting of the document title. + \keyval{abstract-width}{dimension}\Default{.75\cs*{linewidth}} + \sinceversion{0.6}The width of the \cs*{parbox} the abstract as set with + the \option{abstract} option is placed in. + \keyval{abstract-format}{definition}% + \Default{\cs*{setlength}\cs*{parskip}\Marg{.333\cs*{baselineskip}}} + \sinceversion{0.6}Code that is placed in the parbox the abstract is placed + in \emph{before} the abstract text. + \keyval{caption-font}{definition}% + \Default{\cs*{normalfont}\cs*{small}\cs*{sffamily}} + This option only has any effect if you use the option + \option{load-preamble}, see section~\vref{sec:preamble} for details on the + option. + \keyval{caption-label-font}{definition}% + \Default{\cs*{normalfont}\cs*{small}\cs*{sffamily}\cs*{scshape}} + This option only has any effect if you use the option + \option{load-preamble}, see section~\vref{sec:preamble} for details on the + option. + \keyval{code-font}{definition}\Default{\cs*{ttfamily}} + Used for all formatting of source code. + \keyval{source-format}{definition}\Default{\cs{codefont}\cs*{small}} + Formatting of the listings. + \keyval{expl-format}{definition}\Default + Special formatting of the output of a listing. + \keyval{module-sep}{definition}\Default{\cs*{,}>{}>\cs*{,}} + \byclass Change the separator between module name and corresponding option + name. + \keyval{version-note-format}{definition}% + \Default{\cs*{footnotesize}\cs*{sffamily}\cs*{RaggedRight}} + \byclass Formatting of the notes introduced in + section~\vref{sec:cmds:versioning}. + \keyval{pkg-format}{definition}\Default{\cs*{sffamily}} + The formatting of package names. + \keyval{cls-format}{definition}\Default{\cs*{sffamily}} + The formatting of class names. + \keyval{arg-format}{definition}\Default{\cs*{normalfont}\cs*{itshape}} + The formatting of \cs{meta}\marg{meta}. + \keyval{default-format}{code}\Default{\cs*{uline}} + \sinceversion{0.2}The formatting of \cs{default}'s argument. + \meta{code}'s last macro should take one argument. +\end{options} + +\begin{example} + \setcnltx{code-font=\sffamily\itshape} + \code{foo} and \cs*{bar}, option \option{baz} +\end{example} + +\section{Commands, Options and Further Settings Directly Related to the \cnltxdoc\ Class} + +\subsection{Using Class Options}\label{sec:class:options} +The \cnltxdoc\ class only knows a few options: +\begin{options} + \keybool{load-preamble}\Default{false} + See section~\vref{sec:preamble} for details. + \keybool{load-preamble+}\Default{false} + See section~\vref{sec:predefined-indexing} for details. + \keybool{add-index}\Default{false} + See section~\vref{sec:predefined-indexing} for details. + \keyval{babel-options}{options}\Default{english} + Options given to the \needpackage[macros/latex/required]{babel} package. + This option only has an effect if \keyis{load-preamble}{true}. + \keyval{scrartcl}{options}\Default + Options that are passed to the underlying class \cls{scrartcl}. \emph{All + global options you want to use should be given here.} +\end{options} + + +\subsection{Information on the Described Package or Class}\label{sec:inform-descr-pack} +A manual for a package or a class needs some information on the described +package like the package name, the version number, the date and so on. This +information is given with the following options. They are used to build the +title page of the manual. +\begin{options} + \keyval{package}{package} + The name of the package that is described. Either this option or + \option{class} or \option{name} should always be given. This command also + defines a command sequence from the package name that formats the package + name with color and small caps like \cnltx. + \keyval{class}{class} + The name of the class that is described. Either this option or + \option{package} or \option{name} should always be given. This command + also defines a command sequence from the class name that formats the class + name with color and small caps like \cnltx. + \keyval{name}{name} + The name of the class/package that is described. Either this option or + \option{package} or \option{class} should always be given. This command + also defines a command sequence from the class name that formats the class + name with color and small caps like \cnltx. + \keyval{authors}{author list} + \changedversion{0.4}Comma separated list of package/class authors. After + each author name you can add an email address by writing it in square + brackets: \verbcode+Some Name[some@name.com]+. Email addresses specified + this way get written as a footnote. At least one author should always be + given. + \keyval{version}{version number} + Version number of the package/class. \cnltx\ tries to extract the + information from the given \option{package} or \option{class}. This + option can be used to set it explicitly. + \keyval{date}{date} + Date of the package/class. \cnltx\ tries to extract the + information from the given \option{package} or \option{class}. This + option can be used to set it explicitly. + \keyval{info}{package/class info} + Information about the package/class. \cnltx\ tries to extract the + information from the given \option{package} or \option{class}. This + option can be used to set it explicitly. + \keyval{subtitle}{subtitle} + A subtitle, printed below the package/class name. + \keyval{url}{url} + The homepage of the package. + \keyval{email}{email} + A contact email address. + \keyval{abstract}{abstract} + An abstract of the package/class/manual. This is text typeset in a box of + \code{.75\cs*{linewidth}}. Actually it does not have to be text but could + be an image or whatever you like. +\end{options} + +\subsection{Building of the Manuals Title Page} +If either the \option{package} or \option{class} has been given an automatic +title page is built using the gathered information. Figure~\vref{fig:titlepage} +roughly sketches which informations is used and how the different elements are +arranged on the title page. The page style of the title page is +\code{plain}. Additionally a table of contents is automatically built that +is set in two columns. The automatic building of the title page can be +prevented by explicitly setting the following option: + +\begin{options} + \keybool{build-title} + The default state depends on other options given like \option{package}. + However, setting this option to \code{false} \emph{after} any of the + options described in section~\vref{sec:inform-descr-pack} will prevent the + building of a title page and allows you to design your own. +\end{options} + +\begin{figure}[htb] + \centering + \begin{tikzpicture}[ + start chain=going below, + node distance=1em, + every node/.style={draw,align=center} + ] + \node[on chain] {package name formatted with \cs{titleformat} and scaled + to 1.5 of its size} ; + \node[on chain] {subtitle} ; + \node[on chain,draw=none] + {\tikz\draw (0,0) node[draw] {version} ++(4,0) node[draw] {date} ;} ; + \node[on chain] {package information} ; + \node[on chain] {author names (formatted according to specifications for + names as defined with \cs{newname})} ; + \node[on chain] {url when specified via the \option{url} option} ; + \node[on chain] {email address when specified via the \option{email} option} ; + \node[on chain] {abstract when specified via the \option{abstract} option} ; + \end{tikzpicture} + \caption{Schematic sketch of the title page.} + \label{fig:titlepage} +\end{figure} + +\subsection{A Quotation Environment} + +\cnltxdoc\sinceversion{0.5} provides a quotation environment: +\begin{environments} + \environment{cnltxquote}[\oarg{author/reference}] + A quotation environment. +\end{environments} + +The environment sets the body indented on both sides as it simply uses a +\env*{quote} environment internally. The contents of the optional argument is +set flush right after the environment's body. The formatting is controlled by +two options: + +\begin{options} + \keyval{quote-format}{definition}\Default{\cs*{small}\cs*{sffamily}} + The formatting of the environment's body. + \keyval{quote-author-format}{definition}\Default{\cs*{itshape}} +\end{options} + +\begin{example} + \begin{cnltxquote}[Douglas Adams, The Restaurant at the End of the Universe] + ``The first ten million years were the worst,'' said Marvin, ``and the + second ten million years, they were the worst too. The third ten million + years I didn't enjoy at all. After that I went into a bit of a decline.'' + \end{cnltxquote} +\end{example} + +\subsection{Predefined Preamble}\label{sec:preamble} +It is possible to load a part of my standard preamble automatically by +passing an option as class option. +\begin{options} + \opt{load-preamble} + Class option that preloads part of my custom preamble. +\end{options} + +Using the option will include the following code: + +\begin{sourcecode} + \RequirePackage{ifxetex,ifluatex} + \ifboolexpr{not bool{xetex} and not bool{luatex}} + {\RequirePackage[T1]{fontenc}} + {\RequirePackage{fontspec}} + \RequirePackage[oldstyle]{libertine} + % `libertinehologopatch' is not on CTAN, yet! + % you can get it at https://bitbucket.org/cgnieder/libertinehologopatch/ + \RequirePackage{libertinehologopatch} + \RequirePackage[supstfm=libertinesups]{superiors} + % libertine does not have superior letters: + \def\@makefnmark{% + \hbox{% + \cnltx@ifisnum{\@thefnmark} + {\textsu{\hspace*{\superiors@spaced}\@thefnmark}} + {\@textsuperscript{\normalfont\@thefnmark}}% + }% + } + \RequirePackage{microtype} + \ifboolexpr + { + test {\ifcsdef{MT@pr@set@@romansans}} and + test {\ifcsdef{MT@ex@set@@romansans}} + } + {} + { + \DeclareMicrotypeSet{romansans}{ + encoding = {*}, + family = {rm*,sf*} + } + } + \ifcsdef{MT@tr@set@@scshape} + {} + { + \DeclareMicrotypeSet[tracking]{scshape}{ + encoding = {*} , + shape = {sc,scit,si} + } + } + \microtypesetup{ + tracking = scshape , + protrusion = romansans , + expansion = romansans + } + \ifboolexpr{not bool{xetex} and not bool{luatex}} + {\RequirePackage[scaled=.79]{beramono}} + {\setmonofont[Scale=MatchLowercase]{Bitstream Vera Sans Mono}} + \RequirePackage{fnpct} + \expandafter\RequirePackage\expandafter[\cnltx@babel@options]{babel} + \renewcommand*\othersectionlevelsformat[3]{% + \textcolor{cnltx}{#3\autodot}\enskip} + \renewcommand*\partformat{% + \textcolor{cnltx}{\partname~\thepart\autodot}} + \deffootnote{2em}{1em}{\llap{\thefootnotemark. }}% + \pagestyle{headings} + \setcapindent{1.5em} + \setkomafont{caption}{\cnltx@caption@font} + \setkomafont{captionlabel}{\cnltx@captionlabel@font} +\end{sourcecode} + +The effect of this preamble is demonstrated by the document you're reading at +this moment. + +\subsection{Predefined Indexing}\label{sec:predefined-indexing} +\cnltxdoc\ allows the automated creation of an index. This is done with the +help of the \pkg{imakeidx} package by \egreg~\cite{pkg:imakeidx}. To use this +feature you have two class options. They cannot be set with \cs{setcnltx} but +must be given as class options. + +\begin{options} + \keybool{add-index}\Default{false} + Enables the automatic creation of an index at the end of the document. + \keybool{load-preamble+}\Default{false} + This option has the same effect as adding the options + \option{load-preamble}, \option{add-index} and \option{add-bib}. +\end{options} + +Enabling the feature +\begin{itemize} + \item loads the \needpackage{imakeidx} package, + \item uses a given style file for the index that can be specified with the + \option{index-style} option, + \item sets a certain setup for the index that can be specified with the + \option{index-setup} option and + \item adds an index at the end of the document. +\end{itemize} + +The following options are available to customize the appearance of the index: +\begin{options} + \keyval{index-prologue}{text} + Adds \meta{text} as index prologue between heading and the actual index. + \keyval{index-space}{dimension}\Default{0pt} + The vertical space between index prologue and index. + \keyval{index-setup}{options}% + \Default{othercode=\cs*{footnotesize},level=\cs*{addsec}} + The options that are passed to \pkg{imakeidx}'s \cs*{indexsetup} command. + \keyval{makeindex-setup}{options}\Default{columns=2,columnsep=1em} + The options that are passed to the \cs*{makeindex} command. + \keyval{index-style}{style file}\Default{cnltx.ist} + The style file that is used for formatting the index. +\end{options} + +The index style file \file{cnltx.ist} contains the following lines: +\inputsourcecode[sourcecode-options={style=cnltx-makeindex}]{cnltx.ist} + +The feature is demonstrated by this document which does not contain a single +control sequence containing the string \code{index}! + +\subsection{Bibliography with \pkg*{biblatex}} +\subsubsection{Bibliography Entry Types \code{package}, \code{class} and + \code{bundle} for \pkg*{biblatex}} +\label{sec:listings:bibtex-language} + +\cnltxdoc\sinceversion{0.4} defines the bibliograpy entry types +\code{package}, \code{class} and \code{bundle} when +\pkg{biblatex}~\cite{pkg:biblatex} is used. This allows specifying \LaTeX\ +packages in \file{bib} files: + +\begin{sourcecode}[sourcecode-options={style=cnltx-bibtex}] + @package{pkg:chngcntr, + title = {chngcntr} , + author = {Peter Wilson} , + maintainer = {Will Robertson} , + date = {2009-09-02} , + version = {1.0a} , + url = {http://mirror.ctan.org/macros/latex/contrib/chngcntr/} + } + @class{cls:exam, + title = {exam}, + author = {Philip Hirschhorn}, + date = {2011-05-22}, + version = {2.4}, + url = {http://mirror.ctan.org/macros/latex/contrib/exam/} + } + @bundle{bnd:koma-script, + title = {\KOMAScript} , + sorttitle = {KOMA-Script} , + indextitle = {\KOMAScript} , + indexsorttitle = {KOMA-Script} , + author = {Markus Kohm and Frank Neukahm}, + date = {2012-07-29} , + version = {3.11b} , + url = {http://mirror.ctan.org/macros/latex/contrib/koma-script/} + } +\end{sourcecode} + +As you can see also an entry field \code{maintainer} is defined. For this to +work you have to use the \pkg{biblatex} bibliography style \code{cnltx}. This +style basically is a clone of the style \code{alphabetic} but defines the +necessary additions for the \code{package}, \code{class} and \code{bundle} +entry types and the \code{maintainer} entry field. + +Along with the bibliography style a citation style \code{cnltx} is provided, +again a clone of the \code{alphabetic} style. The only addition it makes is +that indexing of maintainer names is enabled if \pkg{biblatex}'s +\code{indexing} option is used. \emph{The styles can only be used with the + \cnltxdoc\ class} as it relies on definitions made by it. + +This document uses the following call of \pkg{biblatex}: +\begin{sourcecode} + \usepackage[ + backend=biber, + style=cnltx, + sortlocale=en_EN, + indexing=cite, + useprefix]{biblatex} + \addbibresource{cnltx.bib} +\end{sourcecode} +Actually it let's \cnltxdoc\ do it, see section~\ref{sec:autom-bibl} for +details. + +Just for the sake of the example I am going to cite the \pkg*{chngcntr} +package now~\cite{pkg:chngcntr} so you can see both the bibliography entry and +the indexed names of package, author and maintainer in the appendix. + +\subsubsection{Automatic Bibliography}\label{sec:autom-bibl} + +\cnltxdoc\ allows the automated creation of a bibliography. + +\begin{options} + \keybool{add-bib}\Default{false} + Enables the automatic creation of a bibliography at the end of the + document. + \keybool{load-preamble+}\Default{false} + This option has the same effect as adding the options + \option{load-preamble}, \option{add-index} and \option{add-bib}. +\end{options} + +What this options does is including the following code: +\begin{sourcecode} + \RequirePackage[ + backend=biber, + style=cnltx, + sortlocale=en_EN, + indexing=cite, + useprefix]{biblatex} + \addbibresource{cnltx.bib} + \AtEndDocument{\printbibliography} +\end{sourcecode} + +As you can see there's also a bibliography database file \file{cnltx.bib} that +provides a yet small but growing number of package entries. + +\section{Predefined \pkg*{listings} and \pkg*{mdframed} Styles} +\subsection{\pkg*{mdframed}} + +The source code environments (see section~\vref{sec:usage:examples}) all get a +frame with the help of the \pkg{mdframed}~\cite{pkg:mdframed} package. For +this a custom style is defined called \code{cnltx}. The options +\option{frame-options} and \option{add-frame-options} mentioned in +section~\vref{sec:usage:examples} manipulate this style. It is predefined +with these values: + +\begin{sourcecode} + \def\cnltx@mdframed@options{ + backgroundcolor = cnltxbg , + linecolor = cnltx , + roundcorner = 5pt + } +\end{sourcecode} + +\subsection{\pkg*{listings}} +\subsubsection{\LaTeX\ Sourcecode}\label{sec:listings-sourcecode} + +The code of the source code environments (see +section~\vref{sec:usage:examples}) is formatted with the help of the +\pkg{listings} package~\cite{pkg:listings}. A \pkg{listings} style is defined +called \code{cnltx}. The options \option{add-cmds}, \option{add-silent-cmds}, +\option{add-envs}, \option{add-silent-envs}, \option{listings-options} and +\option{add-listings-options} manipulate this style. It is predefined by +\cnltxexample\ as follows: + +\begin{sourcecode} + \def\cnltx@listings@style{ + language = [AlLaTeX]TeX, + alsolanguage = [plain]TeX, + basicstyle = {\sourceformat}, + numbers = left, + numberstyle = \tiny, + xleftmargin = 1em, + numbersep = .75em, + gobble = \cnltx@gobble , + columns = fullflexible, + literate = + {ä}{{\"a}}1 + {ö}{{\"o}}1 + {ü}{{\"u}}1 + {Ä}{{\"A}}1 + {Ö}{{\"O}}1 + {Ü}{{\"U}}1 + {ß}{{\ss}}1 , + breaklines = true, + keepspaces = true, + breakindent = 1em, + commentstyle = \color{comment}, + keywordstyle = \color{cs}, + deletetexcs = + { + a,o,u,A,O,U, + begin, + center, + description,document, + end,enumerate, + figure,flushleft,flushright, + itemize,list, + otherlanguage, + table,tabu,tabular + }, + deletekeywords = + { + a,o,u,A,O,U, + begin, + center, + description,document, + end,enumerate, + figure,flushleft,flushright, + itemize,list, + otherlanguage, + table,tabu,tabular + }, + % \begin, \end: + texcsstyle = [2]\color{beginend}, + index = [2][texcs2], + indexstyle = [2]\@gobble, + moretexcs = [2]{begin,end}, + % added environments that'll be indexed: + texcsstyle = [3]\color{env}, + index = [3][texcs3], + indexstyle = [3]\envidx, + % environments that won't be indexed: + texcsstyle = [4]\color{env}, + index = [4][texcs4], + indexstyle = [4]\@gobble, + % control sequences that'll be indexed: + texcsstyle = [5]\color{cs}, + index = [5][texcs5], + indexstyle = [5]\indexcs, + % control sequences that won't be indexed: + texcsstyle = [6]\color{cs}, + index = [6][texcs6], + indexstyle = [6]\@gobble + } +\end{sourcecode} + +\subsubsection{\BibTeX\ Entries} +The \cnltxlistings\ package defines\sinceversion{0.4} a \pkg{listings} +language \code{BibTeX} that contains a huge number of bibentry types and +bibentry field types, have a look at +section~\vref{sec:listings:bibtex-language}. \cnltxexample\ defines a +\pkg{listings} style for formatting them called \code{cnltx-bibtex}: + +\begin{sourcecode} + \def\cnltx@bibtex@listings@style{ + language = BiBTeX, + basicstyle = {\sourceformat}, + numbers = left, + numberstyle = \tiny, + xleftmargin = 1em, + numbersep = .5em, + gobble = \cnltx@gobble , + columns = fullflexible, + literate = + {ä}{{\"a}}1 + {ö}{{\"o}}1 + {ü}{{\"u}}1 + {Ä}{{\"A}}1 + {Ö}{{\"O}}1 + {Ü}{{\"U}}1 + {ß}{{\ss}}1 , + breaklines = true, + keepspaces = true, + breakindent = 1em, + commentstyle = \color{comment}, + keywordstyle = \color{bibentry} , + keywordstyle = [2]\color{bibentryfield}\itshape , + showstringspaces = false , + } +\end{sourcecode} + +\subsubsection{\code{makeindex} Style Files} +\cnltxlistings\ defines\sinceversion{0.7} a \pkg{listings} language +\code{makeindex} that contains the keywords used in \code{makeindex} style +files. \cnltxexample\ defines a \pkg{listings} style for formatting them +called \code{cnltx-makeindex}: + +\begin{sourcecode} + \def\cnltx@makeindex@listings@style{ + language = makeindex, + basicstyle = {\sourceformat}, + numbers = left, + numberstyle = \tiny, + xleftmargin = 1em, + numbersep = .75em, + gobble = \cnltx@gobble , + columns = fullflexible, + literate = + {ä}{{\"a}}1 + {ö}{{\"o}}1 + {ü}{{\"u}}1 + {Ä}{{\"A}}1 + {Ö}{{\"O}}1 + {Ü}{{\"U}}1 + {ß}{{\ss}}1 , + breaklines = true, + keepspaces = true, + breakindent = 1em, + commentstyle = \color{comment}, + keywordstyle = \color{makeidxkey}\bfseries , + stringstyle = \color{makeidxstring} , + showstringspaces = false + } +\end{sourcecode} + +\section{\PDF\ Strings and \pkg*{hyperref}} + +Since the formatting and indexing commands \cs{cs}, \cs{env}, \cs{option}, +\cs{pkg}, \cs{cls} and \cs{key} are robust they are ignored in \PDF\ +strings. For this reason you should \emph{only use the starred variants} in +places where \PDF\ bookmarks are built from such as section titles when you +use \pkg{hyperref}~\cite{pkg:hyperref}. Since \cnltxdoc\ loads \pkg{hyperref} +this means you should do so, too, when you use \cnltxdoc. This is important +for two reasons: +\begin{enumerate} + \item Indexing in strings that get written to the table of contents does + noch make much sense, anyway, so the starred versions should be used in + section titles even if you don't use \pkg{hyperref}. + \item When \pkg{hyperref} is loaded the mentioned commands are disabled in + \PDF\ strings in a way that \emph{expects} them to be followed by a star. + This means leaving the star out will result in \code{doesn't match its + definition} errors. +\end{enumerate} + +\section{Predefined Colors and Color-Schemes}\label{sec:colors} +\subsection{Explicitly Defined Colors}\label{sec:expl-defin-colors} + +The \cnltxbase\ package defines a number of colors: +\begin{colors} + \colour{cnltxbrown} + Per default used for the control sequences. + \colour{cnltxblue} + Per default used for module names. + \colour{cnltxred} + Per default used as base color in various places. + \colour{cnltxgreen} + Unused per default. + \colour{cnltxgray} + Per default used for formatting comments. + \colour{cnltxyellow} + Per default used for option names. + \colour{cnltxformalblue} + Unused per default. + \colour{cnltxformalred} + Unused per default. +\end{colors} + +\subsection{Actual Used Color Names and Color Schemes}\label{sec:actual-used-color} + +The colors defined in section~\vref{sec:expl-defin-colors} are not directly +used with those names. Instead colors are used whose names describe their +function rather than the color. For this the color names are mapped to actual +colors and saved as a coloring scheme. There are currently three predefined +color schemes whose definitions are given below. Those definitions also show +the actually used color names. They are defined via the following command: + +\begin{commands} + \command{definecolorscheme}[\marg{name}\marg{color assignments}] + \sinceversion{0.5}Defines the color scheme \meta{name}. When used all + assignments will be actually carried out with \pkg{xcolor}'s + \cs*{colorlet} command. How to input \meta{color assignments} will be + immediately clear from the examples below. +\end{commands} + +The `default' color scheme is defined as follows: +\begin{sourcecode} + \definecolorscheme{default}{ + cs => cnltxbrown , % command sequences + option => cnltxyellow ,% options + module => cnltxblue , % modules + comment => cnltxgray , % comments + beginend => red , % \begin and \end + env => black , % environment names + argument => black , % argument delimiters + meta => black!80 , % arguments of \meta + cnltx => cnltxred , % base color + cnltxbg => white , % source code box background + link => black!90 , % hyperlinks + versionnote => black!75 % versioning notes text + bibentry => cnltxgreen , % BibTeX entry types + bibentryfield => black, % BibTeX entry fields + expandable => red , % the color used in \expandable + unexpandable => black , % the color used in \unexpandable + makeidxkey => cnltxgreen , % used for keywords in the cnltx-makeindex + % style + makeidxstring => black % used for strings in the cnltx-makeindex + % style + } +\end{sourcecode} + +The `blue' color scheme is defined this way: +\begin{sourcecode} + \definecolorscheme{blue}{ + cs => cnltxbrown , + option => cnltxgreen , + module => cnltxred , + comment => cnltxgray , + beginend => red , + env => black , + argument => black , + meta => black!80 , + cnltx => cnltxblue , + cnltxbg => yellow!10 , + link => cnltx , + versionnote => black!75 + bibentry => cnltxyellow , + bibentryfield => black , + expandable => red , + unexpandable => black , + makeidxkey => cnltxyellow , + makeidxstring => black + } +\end{sourcecode} + +Finally the `formal' color scheme is defined like this: +\begin{sourcecode} + \definecolorscheme{formal}{ + cs => black , + option => cnltxformalblue , + module => cnltxblue , + comment => cnltxgray , + beginend => red , + env => black , + argument => black , + meta => black!80 , + cnltx => cnltxformalblue , + cnltxbg => white , + link => black!90 , + versionnote => black!75 , + bibentry => black , + bibentryfield => black , + expandable => red , + unexpandable => black , + makeidxkey => black , + makeidxstring => black + } +\end{sourcecode} + +\section{Language Support}\label{sec:language-support} +\noindent\sinceversion{0.2}The \cnltxdoc, the \cnltxexample\ and the +\cnltxtools\ package all rely on the \pkg{translations} +package~\cite{pkg:translations} for providing some document language dependent +strings. Currently only translations for English and German are provided. +Others can be added and the existing ones changed with the following command +provided by the \pkg{translations} package: + +\begin{commands} + \command{DeclareTranslation}[\marg{language}\marg{keyword}\marg{translation}] + Provide translations for the string identified by the \textsc{id} + \meta{keyword}. +\end{commands} + +The defined strings are listed in table~\vref{tab:language:strings}. They are +used in indexing strings and in different parts of the document. + +\begin{table} + \centering\renewcommand\arraystretch{1.3} + \caption{Overview over available internationalization key words.} + \label{tab:language:strings} + \begin{tabular}{ + l + >{\ttfamily}l + >{\RaggedRight}p{.25\linewidth} + >{\RaggedRight}p{.25\linewidth} + } + \toprule + Package/Class & key word & English version & German version\\ + \midrule + \cnltxexample & cnltx-package & + \GetTranslation{cnltx-package} & + \GetTranslationFor{German}{cnltx-package} \\ + \cnltxexample & cnltx-class & + \GetTranslation{cnltx-class} & + \GetTranslationFor{German}{cnltx-class} \\ + \cnltxexample & cnltx-bundle & + \GetTranslation{cnltx-bundle} & + \GetTranslationFor{German}{cnltx-bundle} \\ + \cnltxexample & cnltx-environment & + \GetTranslation{cnltx-environment} & + \GetTranslationFor{German}{cnltx-environment} \\ + \cnltxdoc & cnltx-default & + \GetTranslation{cnltx-default} & + \GetTranslationFor{German}{cnltx-default} \\ + \cnltxdoc & cnltx-empty & + \GetTranslation{cnltx-empty} & + \GetTranslationFor{German}{cnltx-empty} \\ + \cnltxdoc & cnltx-required & + \GetTranslation{cnltx-required} & + \GetTranslationFor{German}{cnltx-required} \\ + \cnltxdoc & cnltx-toc & + \GetTranslation{cnltx-toc} & + \GetTranslationFor{German}{cnltx-toc} \\ + \cnltxdoc & cnltx-license & + \GetTranslation{cnltx-license} & + \GetTranslationFor{German}{cnltx-license}\\ + \cnltxdoc & cnltx-introduced & + \GetTranslation{cnltx-introduced} & + \GetTranslationFor{German}{cnltx-introduced} \\ + \cnltxdoc & cnltx-changed & + \GetTranslation{cnltx-changed} & + \GetTranslationFor{German}{cnltx-changed} \\ + \cnltxdoc & cnltx-f. & + \GetTranslation{cnltx-f.} & + \GetTranslationFor{German}{cnltx-f.} \\ + \cnltxdoc & cnltx-ff. & + \GetTranslation{cnltx-ff.} & + \GetTranslationFor{German}{cnltx-ff.} \\ + \cnltxdoc & cnltx-maintainer & + \GetTranslation{cnltx-maintainer} & + \GetTranslationFor{German}{cnltx-maintainer} \\ + \cnltxdoc & cnltx-maintainer & + \GetTranslation{cnltx-maintainers} & + \GetTranslationFor{German}{cnltx-maintainers} \\ + \cnltxtools & cnltx-i.e. & + \GetTranslation{cnltx-i.e.} & + \GetTranslationFor{German}{cnltx-i.e.} \\ + \cnltxtools & cnltx-e.g. & + \GetTranslation{cnltx-e.g.} & + \GetTranslationFor{German}{cnltx-e.g.} \\ + \cnltxtools & cnltx-cf. & + \GetTranslation{cnltx-cf.} & + \GetTranslationFor{German}{cnltx-cf.} \\ + \cnltxtools & cnltx-etc. & + \GetTranslation{cnltx-etc.} & + \GetTranslationFor{German}{cnltx-etc.} \\ + \bottomrule + \end{tabular} +\end{table} + +\part{Appendix} +\appendix + +\section{Internal Helper Commands} + +The commands in this section are only described for the sake of completeness. +They are not meant to be used in a document. Expandable commands are marked +with \textcolor{expandable}{\expandablesign}. + +\subsection{Defined by \cnltxbase}\label{sec:defined-cnltxbase} + +Especially \cnltxbase\ defines some useful helper macros that are also used by +the other packages and classes. + +\subsubsection{Related to the Bundle} + +\begin{commands} + \expandable\command{cnltx\at\at date} + The creation date of the current version of the bundle. + \expandable\command{cnltx\at\at version} + The version number of the bundle. + \expandable\command{cnltx\at\at info} + The short description of the bundle. + \command{cnltx\at create\at bundle\at message}% + [\sarg\marg{module}\Marg{\choices{Error,Warning,WarningNoLine,Info}}] + \sinceversion{0.7}Create suiting error and warning messaging commands + for the module \meta{module} of the \cnltx\ bundle. The starred version + creates messages for a class the un-starred version messages for a + package. + \command{cnltx\at base\at error}[\marg{message}] + Issue an error message using \cs*{PackageError}\Marg{cnltx-base}. + \command{cnltx\at base\at warning}[\marg{message}] + Issue a warning message using \cs*{PackageWarning}\Marg{cnltx-base}. + \command{cnltx\at base\at warningnoline}[\marg{message}] + Issue a warning message using \cs*{PackageWarningNoLine}\Marg{cnltx-base}. + \command{cnltx\at base\at info}[\marg{message}] + Issue a message using \cs*{PackageInfo}\Marg{cnltx-base}. + \command{cnltx\at define\at colorscheme}[\marg{name}\marg{scheme definition}] + Command that can be used to define a color scheme. +\end{commands} + +\subsubsection{Programming Tools} + +\begin{commands} + \command{cnltx\at create\at message}% + [\sarg\marg{prefix}\marg{package/class + name}\Marg{\choices{Error,Warning,WarningNoLine,Info}} \marg{detailed + error message}] + \changedversion{0.7}Create error and warning massaging commands + \cs*{\meta{prefix}@\choices{error,warning,warningnoline,info}}\marg{message}. + The starred version creates messages for a class the un-starred version + messages for a package. All commands have one argument which takes the + message. \meta{prefix} will be all lowercase in the generated command. + \command{cnltx\at create\at generic\at message}% + [\sarg\marg{prefix}\marg{package/class + name}\Marg{\choices{Error,Warning,WarningNoLine,Info}}] + \sinceversion{0.7}Create error and warning massaging commands + \cs*{\meta{prefix}@\choices{error,warning,warningnoline,info}}\marg{message}. + The starred version creates messages for a class the un-starred version + messages for a package. All commands have one argument which takes the + message \emph{except for the error command which gets two arguments}, the + first for the short version and the second for the detailed message. + \meta{prefix} will be all lowercase in the generated command. + \command{cnltx\at par} + Expands to \cs*{par}. Sometimes you need to smuggle a \cs*{par} in a + short macro \ldots + \expandable\command{iftest}[\marg{test directive}\marg{true}\marg{false}] + \sinceversion{0.7}Checks if \meta{test directive} is true and either + places \meta{true} or \meta{false} in the input stream. \meta{test + directive} should be a \TeX\ test like + \cs*{ifx}\meta{token1}\meta{token2}.\\ + This is a command in the spirit of \pkg{etoolbox}'s \cs*{ifbool} that does + the same for a boolean \meta{bool} defined with + \cs*{newif}\cs*{if\meta{bool}} or \cs*{newbool}\marg{bool}. It + corresponds to \pkg{etoolbox}'s \code{test} directive for its + \cs*{ifboolexpr}. + \expandable\command{nottest}[\marg{test directive}\marg{not true}\marg{not false}] + \sinceversion{0.7}Checks if \meta{test directive} is not true and either + places \meta{not true} or \meta{not false} in the input stream. Test + directive should be a \TeX\ test like + \cs*{ifx}\meta{token1}\meta{token2}.\\ + This is a command in the spirit of \pkg{etoolbox}'s \cs*{notbool} that does + the same for a boolean \meta{bool} defined with + \cs*{newif}\cs*{if\meta{bool}} or \cs*{newbool}\marg{bool}. + \command{cnltx\at ifsym}[\marg{token}\marg{true}\marg{false}] + A generic version of \LaTeX's \cs*{@ifstar} that checks if \meta{token} + follows if the input stream. If yes it is removed and \meta{true} is + placed in the input stream else \meta{false}. + \command{cnltx\at ifdash}[\marg{true}\marg{false}] + A wrapper for \verbcode+\cnltx@ifsym{-}+. + \command{cnltx\at ifbang}[\marg{true}\marg{false}] + \sinceversion{0.3}A wrapper for \verbcode+\cnltx@ifsym{!}+. + \expandable\command{cnltx\at ifisnum}[\marg{token list}\marg{true}\marg{false}] + \sinceversion{0.6}Checks if \meta{token list} is an integer zero or + greater and leaves \meta{true} in the input stream if it is an + \meta{false} if it isn't. + \command{cnltx\at expandargs}[\darg{specs}\meta{control sequence}] + \sinceversion{0.7}This is a \LaTeXe\ version of expl3's + \cs*{exp\_args:N}\meta{specs}. The command expands the arguments of + \meta{control sequence} according to \meta{specs}. In \meta{specs} + \begin{itemize} + \item \code{N} means unexpanded token, + \item \code{n} means unexpanded braced group, + \item \code{c} means braced group converted into a control sequence + name, + \item \code{o} means braced group expanded once, + \item \code{f} means braced group expanded with \cs*{romannumeral}, and + \item \code{x} means braced group expanded with \cs*{edef}. + \end{itemize} + \expandable\command{cnltx\at stripbs} + A shortcut for \verbcode+\expandafter\@gobble\string+. + \command{cnltx\at if\at in}[\marg{tokenlist}\marg{search}\marg{true}\marg{false}] + Places \meta{true} in the input stream if \meta{search} is found in + \meta{tokenlist} and \meta{false} if it isn't. + \command{cnltx\at replace\at once}[\marg{cs}\marg{search}\marg{replace}] + Replaces the first occurence of \meta{search} in the first expansion of + \meta{cs} with \meta{replace}. + \command{cnltx\at long\at replace\at once}[\marg{cs}\marg{search}\marg{replace}] + \sinceversion{0.3}The same as \cs{cnltx\at replace\at once} but \meta{cs} + will be redefined with \cs*{long}. + \command{cnltx\at replace\at all}[\marg{cs}\marg{search}\marg{replace}] + Replaces all occurences of \meta{search} in the first expansion of + \meta{cs} with \meta{replace}. + \command{cnltx\at long\at replace\at all}[\marg{cs}\marg{search}\marg{replace}] + \sinceversion{0.3}The same as \cs{cnltx\at replace\at all} but \meta{cs} + will be redefined with \cs*{long}. + \command{cnltx\at remove\at once}[\marg{cs}\marg{search}] + \sinceversion{0.3}Removes the first occurence of \meta{search} in the + first expansion of \meta{cs}. + \command{cnltx\at long\at remove\at once}[\marg{cs}\marg{search}] + \sinceversion{0.3}The same as \cs{cnltx\at remove\at once} but \meta{cs} + will be redefined with \cs*{long}. + \command{cnltx\at remove\at all}[\marg{cs}\marg{search}] + \sinceversion{0.3}Removes all occurences of \meta{search} in the first + expansion of \meta{cs}. + \command{cnltx\at long\at remove\at all}[\marg{cs}\marg{search}] + \sinceversion{0.3}The same as \cs{cnltx\at remove\at all} but \meta{cs} + will be redefined with \cs*{long}. +\end{commands} + +\subsection{Defined by \cnltxdoc} + +\begin{commands} + \command{cnltx\at doc\at error}[\marg{message}] + Issue an error message using \cs*{ClassError}\Marg{cnltx-doc}. + \command{cnltx\at doc\at warning}[\marg{message}] + Issue a warning message using \cs*{ClassWarning}\Marg{cnltx-doc}. + \command{cnltx\at doc\at warningnoline}[\marg{message}] + Issue a warning message using \cs*{ClassWarningNoLine}\Marg{cnltx-doc}. + \command{cnltx\at doc\at info}[\marg{message}] + Issue a message using \cs*{ClassInfo}\Marg{cnltx-doc}. + \command{cnltx\at getfileinfo}[\marg{file name}\marg{file extension}] + Extract the date, version and background information for a package or a + class and defines \cs{cnltx\at package\at date}, \cs{cnltx\at package\at + version} and \cs{cnltx\at package\at info} to contain the extracted + data. + \command{cnltx\at version\at note}[\marg{note}] + Command that is used for the versioning notes interally. Sets + \cs*{reversemarginpar} and then writes the note \meta{note} to the margin + with corresponding formatting. +\end{commands} +\begin{environments} + \environment{cnltxlist} + The list environment that is used by the environments \env{commands}, + \env{options} and \env{environments}. +\end{environments} + +\subsection{Defined by \cnltxexample} + +\begin{commands} + \command{cnltx\at example\at error}[\marg{message}] + Issue an error message using \cs*{PackageError}\Marg{cnltx-example}. + \command{cnltx\at example\at warning}[\marg{message}] + Issue a warning message using \cs*{PackageWarning}\Marg{cnltx-example}. + \command{cnltx\at example\at warningnoline}[\marg{message}] + Issue a warning message using \cs*{PackageWarningNoLine}\Marg{cnltx-example}. + \command{cnltx\at example\at info}[\marg{message}] + Issue a message using \cs*{PackageInfo}\Marg{cnltx-example}. + \command{cnltxat} + Robust command that typesets `\at' with category code 11. An @ in command + names confuses the indexing of the command names. Either one uses another + symbol for makeindex's ``actual'' recognition and also tells + \pkg{idxcmds}~\cite{pkg:idxcmds} about it or one uses \cs{cnltxat} in + \cs{cs} and friends. For the sake of convenience you can define a command + like \cs*{at} that expands to it\footnote{This is important. If you + \cs*{let} it to \cs{cnltxat} index entries may be sorted differently! + Remember: \cs{cnltxat} is robust.}. In order not to overwrite any such + existing macro it is not defined by \cnltxexample. This document for + example defines \verbcode+\def\at{\cnltxat}+. + \command{cnltxletterat} + An alias of \cs{cnltxat}. + \command{cnltxotherat} + The same as \cs{cnltxat} but with a `\at' with category code 12. + \command{cnltxbang} + The same as \cs{cnltxotherat} except that it contains a `\bang'. + \command{cnltxequal} + The same as \cs{cnltxotherat} except that it contains a `\equal'. + \command{cnltx\at isvalue} + Used in definitions of the key/value option typesetting commands. Inserts + a \code{=} with some stretchable space around and a legal break-point + after it. + \command{indexcs} + Version of \cs{csidx} that takes care of a \cs*{textcompwordmark} inserted + by listings. Also replaces all occurences of @ with category code 11 or 12 + with \cs{cnltxat}. Used to index commands in the \env{sourcecode} and + \env{example} environments that have been added with \option{add-cmds}. + \command{indexenv} + \sinceversion{0.7a}Version of \cs{envidx} that takes care of a + \cs*{textcompwordmark} inserted by listings. Also replaces all occurences + of @ with category code 11 or 12 with \cs{cnltxat}. Used to index + environments in the \env{sourcecode} and \env{example} environments that + have been added with \option{add-envs}. + \command{cnltx\at treat\at lst\at index}[\marg{new index cs}\marg{internal + index cs}] + \sinceversion{0.7a}This command was used to define \cs{indexcs} and + \cs{indexenv}:\\ + \verbcode+\cnltx@treat@lst@index{\indexcs}{\csidx}+ + \command{newarg}[\oarg{arg formatting}\marg{cs}\marg{left delim}\marg{right delim}]% + \Default{\cs{meta}} + \changedversion{0.2}Command used to define the argument commands: + \verbcode+\newarg\marg{\{}{\}}+. The optional argument determines how the + argument of the new command will be formatted. This is done with + \cs{meta} per default. \verbcode+\newarg[\code]\Marg{\{}{\}}+ + \command{MakePercentComment} + Sets the category code of \code{\%} to 14. + \command{cnltx\at copyablespace} + Prints a space that is also copyable. Uses the \pkg{accsupp} package by + \oberdiek~\cite{pkg:accsupp}. + \command{cnltx\at mdframed\at options} + Predefined option list for the \pkg{mdframed}~\cite{pkg:mdframed} style + \code{cnltx}. + \command{cnltx\at listings\at style} + Predefined option list for the \pkg{listings}~\cite{pkg:listings} style + \code{cnltx}. +\end{commands} + +\subsection{Defined by \cnltxlistings} + +\begin{commands} + \command{cnltx\at listings\at error}[\marg{message}] + Issue an error message using \cs*{PackageError}\Marg{cnltx-listings}. + \command{cnltx\at listings\at warning}[\marg{message}] + Issue a warning message using \cs*{PackageWarning}\Marg{cnltx-listings}. + \command{cnltx\at listings\at warningnoline}[\marg{message}] + Issue a warning message using \cs*{PackageWarningNoLine}\Marg{cnltx-listings}. + \command{cnltx\at listings\at info}[\marg{message}] + Issue a message using \cs*{PackageInfo}\Marg{cnltx-listings}. + \command{cnltx\at predefined\at control\at sequences} + A comma-separated list of predefined `silent' control sequence names. + \command{cnltx\at predefined\at environments} + A comma-separated list of predefined `silent' environment names. + \command{listsilentcmds} + Prints all known control sequence names formatted and separated with the + separator set with \option{list-sep}. Requires \cnltxexample. + \command{listsilentenvs} + Prints all known environment names formatted and separated with the + separator set with \option{list-sep}. Requires \cnltxexample. + \command{listbibfilekeys}[\marg{file name}] + \sinceversion{0.7}Prints all cite keys contained in the bibliography file + \meta{file name} formatted with \cs{code} and separated with the + separator set with \option{list-sep}. Requires \cnltxexample. + \command{listbibfiletypes}[\marg{file name}] + \sinceversion{0.7}Prints all citation types contained in the bibliography + file \meta{file name} formatted with \cs{code} and separated with the + separator set with \option{list-sep}. Requires \cnltxexample. + \command{listbibfileentries}[\marg{file name}] + \sinceversion{0.7}Prints all cite keys contained in the bibliography file + \meta{file name} formatted with \cs{code} and gives their respective + entry types, separated with the separator set with \option{list-sep}. + Requires \cnltxexample. +\end{commands} +\begin{options} + \keyval{list-sep}{separator}\Default{,\cs*{space}} + Sets the separator for \cnltxlistings' commands listing the different + commands \etc. +\end{options} + +\subsection{Defined by \cnltxtools} + +\begin{commands} + \command{cnltx\at tools\at error}[\marg{message}] + Issue an error message using \cs*{PackageError}\Marg{cnltx-tools}. + \command{cnltx\at tools\at warning}[\marg{message}] + Issue a warning message using \cs*{PackageWarning}\Marg{cnltx-tools}. + \command{cnltx\at tools\at warningnoline}[\marg{message}] + Issue a warning message using \cs*{PackageWarningNoLine}\Marg{cnltx-tools}. + \command{cnltx\at tools\at info}[\marg{message}] + Issue a message using \cs*{PackageInfo}\Marg{cnltx-tools}. + \command{cnltx\at accsupp}[\marg{actual text}\marg{additional + options}\marg{\TeX\ text}] + A wrapper for package \pkg{accsupp}'s \cs*{BeginAccSupp}\Marg{ActualText + = \meta{actual text}} \meta{\TeX\ text} \cs*{EndAccSupp}\marg{}. +\end{commands} + +\section{List of Known \LaTeX\ Control Sequences}\label{sec:known:csnames} + +Below are listed all \emph{predefined} control sequence names that are treated +as ``silent'' names by \cnltx, that is, those defined by \cnltxlistings. + +\begin{multicols}{3}\small + \RaggedRight\listsilentcmds +\end{multicols} + +\section{List of Known \LaTeX\ Environments}\label{sec:known:environments} + +Below are listed all \emph{predefined} control sequence names that are treated +as ``silent'' names by \cnltx, that is, those defined by \cnltxlistings. + +\begin{multicols}{3}\small + \RaggedRight\listsilentenvs +\end{multicols} + +\section{List of Entries in \code{cnltx.bib}} +Most entries in \code{cnltx.bib} are entries of the \code{@package} type. +The cite keys that the file currently contains are listed below. This list is +very likely to be extended significantly in the future. + +\setcnltx{list-sep={,\par}} +\begin{multicols}{3}\small + \RaggedRight\listbibfileentries{cnltx.bib} +\end{multicols} + +\end{document} |