% arara: pdflatex: { shell: on }
% !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-2014 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{amsmath}
\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@makeindex@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,
    iftest,
    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, chead, circled,circlenumber, cnltx,
    foo, foothree,
    GetTranslation,
    KOMAoptions,
    lipsum,
    minusone,multoffourrm,
    nohyperpage,
    pdf@shellescape,
    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}

\usepackage{fixfoot}
\DeclareFixedFootnote\oberdiekfn{\CTANurl{oberdiek}}

\newcommand*\file[1]{\code{#1}}
\newidxcmd\prg{\code{#1}}[ (program)]
\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} ever 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 60~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 \sinceversion{0.9}\cnltx\ -- a wrapper package for usage in documents.
    It loads one or more of the following packages.  See
    section~\ref{sec:usage-bundle} for details on the usage. \\
    \verbcode+\usepackage{cnltx}+
  \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, see
    section~\ref{sec:list-entr-bib}.  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}\oberdiekfn~\cite{pkg:ltxcmds},
\pkg{pdftexcmds}\oberdiekfn~\cite{pkg:pdftexcmds},
\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},
\needpackage{idxcmds}~\cite{pkg:idxcmds},
\needpackage{ifxetex}~\cite{pkg:ifxetex},
\needpackage{adjustbox}~\cite{pkg:adjustbox}.

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
\pkg{accsupp}\oberdiekfn~\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.

\section{Usage of the Bundle}\label{sec:usage-bundle}
The intended use of this bundle is three-fold:
\begin{itemize}
  \item The main use-case is documenting my own \LaTeX\ packages.  This is
    done with
    \begin{sourcecode}[gobble=6]
      \documentclass{cnltx-doc}
    \end{sourcecode}
    and actually loads most if not all of the bundle.
  \item The module \cnltxbase\ is also intended as a programming tools package
    that will be used in other packages eventually.  It is already used by the
    \pkg{cntformats} package from the \bnd{exsheets}
    bundle~\cite{bnd:exsheets}.
  \item In case parts of this bundle prove useful to be used in a document the
    recommended way is to add
    \begin{sourcecode}[gobble=6]
      \usepackage{cnltx}
    \end{sourcecode}
    to the preamble which will load the \cnltxbase\ module.  Other needed
    modules can be given as package option by using the name part after the
    dash as option.
    \begin{sourcecode}[gobble=6]
      \usepackage[example]{cnltx}
    \end{sourcecode}
    would load \cnltxexample.
\end{itemize}

\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\code{-}\marg{name}\marg{value}]
    \sinceversion{0.2}A key \meta{name} set to value \meta{value}, the
    optional star prevents an index entry, the  optional \code{-} strips the
    braces around \code{value}; \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-output}{definitions}
    \meta{definitions} are placed before the output of the source code is
    inserted.
  \keyval{after-output}{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.
  \keybool{outside}\Default{false}
    \sinceversion{0.10}If \code{true} the output of an example is put outside
    of the frame in the input stream.  This can be useful if the example code
    contains a floating environment for example.
\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.
  \keyval{add-local-frame}{\pkg{mdframed} options}
    \sinceversion{0.10}Add \pkg{mdframed} options to the environment where the
    option is used only.  This is
    basically \beginenv*\Marg{\env{mdframed}}\Oarg{style=cnltx,\meta{options}}.
  \keyval{local-frame}{\pkg{mdframed} options}
    \sinceversion{0.10}replace the default \pkg{mdframed} options to the
    environment where the option is used only.  This is
    basically \beginenv*\Marg{\env{mdframed}}\oarg{options}.
\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{add-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.  This is
    basically \cs*{lstset}\Marg{style=cnltx,\meta{options}}.
  \keyval{sourcecode-options}{\pkg{listings} options}
    \sinceversion{0.10}These options are added to the \pkg{listings} options
    of the source code environments without redefing or using the main style.
    Hence it can be used to locally add options to a source code environment.
    This is basically \cs*{lstset}\marg{options}.
  \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{Compile Source Examples}\label{sec:comp-source-exampl}
\subsubsection{The Compliation Process}\label{sec:compliation-process}
When you input an example like
\begin{sourcecode}
  \begin{example}
    \documentclass{article}
    \begin{document}
      foo
    \end{document}
  \end{example}
\end{sourcecode}
you'll get an error since the code is input as is and you'll end up with
\cs*{documentclass} after \verbcode=\begin{document}=.  There's a way out,
though. 

\cnltxexample\sinceversion{0.9} provides the possibility to compile the source
code file externally and input the compiled \PDF.

\begin{sourcecode}
  \begin{example}[compile]
    \documentclass{article}
    \begin{document}
      foo
    \end{document}
  \end{example}
\end{sourcecode}

This needs \code{shell-escape} enabled.  The default compilation program is
\prg{pdflatex} which will compile the file two times.  The process can be
customized with the following options:

\begin{options}
  \keybool{compile}\Default{false}
    Compile the source code file.  Although this option can be set globally it
    really shouldn't be!  It's best to give this option explicitly to the
    source code environment whose body should be compiled.  If enabled
    globally \emph{all} examples would be compiled and most likely lead to
    various errors since most examples won't be complete \LaTeX\ documents.
  \keychoice{program}{pdflatex,lualatex,xelatex,arara}\Default{pdflatex}
    The program to compile the source file.
  \keyval{runs}{number}\Default{2}
    The number of compilations.
  \keyval{exe-with}{options}\Default
    Command line options that can be given to the compilation program chosen
    with \option{program}.
  \keyval{file-ext}{extension}\Default{pdf}
    The file extension of the included file of a compiled example.
  \keybool{add-frame}\Default{true}
    \sinceversion{0.10}If \code{true} every output page will get a frame.
\end{options}

The compiled document will be input with \cs*{includegraphics}, each page
separately.  Since the pages of the document are most likely as large as the
ones from the main document itself they are scaled down.  This is best
demonstrated with an example.  The following input
\begin{sourcecode}
  \begin{example}[compile]
    \documentclass[a5paper]{scrartcl}
    \usepackage{showframe,lipsum}
    \author{Clemens Niederberger}
    \title{A Test File}
    \begin{document}
      \maketitle
      \tableofcontents
      \section{A Section Title}
      \lipsum[1-10]
    \end{document}
  \end{example}
\end{sourcecode}
will lead to this output:

\begin{example}[compile]
  \documentclass[a5paper]{scrartcl}
  \usepackage{showframe,lipsum}
  \author{Clemens Niederberger}
  \title{A Test File}
  \begin{document}
    \maketitle
    \tableofcontents
    \section{A Section Title}
    \lipsum[1-10]
  \end{document}
\end{example}

The pages get scaled according to two parameters:
\begin{options}
  \keyval{max-pages}{number}\Default{4}
    The maximum number of pages in a row.  The width of the pages is scaled to
    $\text{\cs*{linewidth}}/n$ where $n$ is either the number of pages $p$ of
    the compiled document or \meta{number} if $p>\text{\meta{number}}$.
  \keyval{max-height}{dimension}\Default{.5\cs*{textheight}}
    The maximum height of a page.
\end{options}

There's another possibility to influence the appearance of the output:
\begin{options}
  \keyval{graphics}{options}\Default
    \meta{options} are passed to \cs*{includegraphics} for every page that is
    input.
\end{options}

\subsubsection{Floating Output}\label{sec:floating-output}
Since the output can become a quite large figure it might be preferable to
have it as a floating figure.  This is also possible by using the option
\option{float}.
\begin{options}
  \keychoice{float}{\default{true},false,\meta{float
      parameters}}\Default{false}
    Choose if the output should be placed in a \env*{figure} of it's own.  You
    can also use this option to specify the floating parameters for the float.
  \keyval{float-pos}{float parameters}\Default{tbp}
    Set the standard floating parameters that are used if
    \keyis-{float}{true}. The default is actually the expansion of
    \cs*{fps@figure} and not directly \code{tbp}.
  \keyval{float-env}{name}\Default{figure}
    \sinceversion{0.10}The floating environment used when the option
    \option{float} is used.
  \keyval{caption}{text}\Default
    \meta{text} will be used as caption.  If left blank no caption will be
    typeset.  If you want to add a \cs*{label} you can use it in this option.
    Implicitly sets \keyis-{float}{true}.
\end{options}
Please note that \option{float} only has an effect if \keyis-{compile}{true}
has been set.

\subsubsection{Selective Output}\label{sec:selective-output}
Sometimes it may be preferable not to include all pages of a compiled document
but only specific pages.  This is possible with the following option.

\begin{options}
  \keyval{pages}{specifications}
    Select the included pages.  \meta{specification} is a comma-separated list
    of page numbers and page ranges, \eg, \code{1,3,4} or
    \code{1,3-5}. \code{1,3-5} is the same as \code{1,3,4,5}.  If the list
    includes page numbers larger than the maximum number of pages the \PDF\
    has a warnung message will be issued and a replacement text will occur in
    the output where the page would have been.
\end{options}

The input
\begin{sourcecode}
  \begin{example}[compile,pages=1]
    \documentclass[a5paper]{scrartcl}
    \usepackage{showframe,lipsum}
    \author{Clemens Niederberger}
    \title{A Test File}
    \begin{document}
      \maketitle
      \tableofcontents
      \section{A Section Title}
      \lipsum[1-10]
    \end{document}
  \end{example}
\end{sourcecode}
will lead to this output:

\begin{example}[compile,pages=1]
  \documentclass[a5paper]{scrartcl}
  \usepackage{showframe,lipsum}
  \author{Clemens Niederberger}
  \title{A Test File}
  \begin{document}
    \maketitle
    \tableofcontents
    \section{A Section Title}
    \lipsum[1-10]
  \end{document}
\end{example}

Together with the \option{graphics} option this can be used to output a part
of a page. The following source

\begin{sourcecode}
  \begin{example}[compile,pages=1,graphics={trim={0pt 12cm 0pt 0pt},clip}]
    \documentclass[a5paper]{scrartcl}
    \usepackage{showframe,lipsum}
    \author{Clemens Niederberger}
    \title{A Test File}
    \begin{document}
      \maketitle
      \tableofcontents
      \section{A Section Title}
      \lipsum[1-10]
    \end{document}
  \end{example}
\end{sourcecode}
will give this output:

\begin{example}[compile,pages=1,graphics={trim={0pt 12cm 0pt 0pt},clip}]
  \documentclass[a5paper]{scrartcl}
  \usepackage{showframe,lipsum}
  \author{Clemens Niederberger}
  \title{A Test File}
  \begin{document}
    \maketitle
    \tableofcontents
    \section{A Section Title}
    \lipsum[1-10]
  \end{document}
\end{example}

\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 neither the user command nor the internal
    command (\cf\ \cs*{arabic} and \cs*{@arabic}) 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.
  \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{cd}%
  \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:\changedversion{0.10}

\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. }}%
  \RequirePackage{scrlayer-scrpage}
  \chead{\rightmark}
  \KOMAoptions{automark}
  \pagestyle{scrheadings}
  \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.  The styles load \cnltxexample\ 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-maintainers &
        \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}
\paragraph{Message Handling}
\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 messaging 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 messaging 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.
\end{commands}

\paragraph{Conditionals}
\begin{commands}
  \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}, \ie, demand an \cs*{else} and
    \cs*{fi}.\\
    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}, \ie, demand an \cs*{else} and
    \cs*{fi}.\\
    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 ifnextchars}[\marg{list of
    tokens}\marg{true}\marg{false}\meta{trailing token}]
    \sinceversion{0.8}Tests if \meta{trailing token} is any of those in
    \meta{list of tokens} and either places \meta{true} or \meta{false} in the
    input stream without removing \meta{trailing token}.
  \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.  There is one hopefully extremely unlikely case
    where the test fails: when \meta{token list} starts with
    ``\code{\meta{integer}\%}'' where \code{\%} has a category code different
    than 9 (ignored) or 14 (comment).
  \expandable\command{cnltx\at ifshellescape}[\marg{true}\marg{false}]
    \sinceversion{0.9}Checks if shellescape is enabled.  It returns true if
    \pkg{pdftexcmds}' \cs*{pdf@shellescape} has the value~\code{1}.  This is a
    wrapper for \verbcode+\iftest{\ifnum\pdf@shellescape=1 }+.
  \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.
  \expandable\command{cnltx\at ifstrequal}[\marg{string1}\marg{string2}%
    \marg{true}\marg{false}]
    \sinceversion{0.10}Tests if \meta{string1} is equal to \meta{string2} and
    either leaves \meta{true} or \meta{false} in the input stream.  This test
    doesn't take category codes into account.
  \command{cnltx\at ifinlist}%
    [\marg{item}\marg{listmacro}\marg{true}\marg{false}]
    \sinceversion{0.10}A conditional for \pkg{etoolbox} lists similar to
    \cs*{ifinlist} where braces in items are allowed.  This wraps around the
    proposal in \pkg{etoolbox}'s documentation to redefine \cs*{do} and loop
    through the list.
  \command{cnltx\at ifinlistcs}%
    [\marg{item}\marg{listcsname}\marg{true}\marg{false}]
    \sinceversion{0.10}A conditional for \pkg{etoolbox} lists similar to
    \cs*{ifinlistcs} where braces in items are allowed.  This wraps around the
    proposal in \pkg{etoolbox}'s documentation to redefine \cs*{do} and loop
    through the list.
\end{commands}

\paragraph{Expansion Tools}
\begin{commands}
  \command{expandtwice}[\marg{code}]
    \sinceversion{0.10}Expands \meta{code} twice in an \cs*{edef}-like
    context.  This is a  wrapper for\newline
    \cs*{unexpanded}\cs*{expandafter}\cs*{expandafter}\cs*{expandafter}.
  \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}
\end{commands}

\paragraph{Token List Manipulation}
\begin{commands}
  \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 greplace\at once}[\marg{cs}\marg{search}\marg{replace}]
    \sinceversion{0.9}The same as \cs{cnltx\at replace\at once} but acts
    globally.
  \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 greplace\at all}[\marg{cs}\marg{search}\marg{replace}]
    \sinceversion{0.9}The same as \cs{cnltx\at replace\at all} but acts
    globally.
  \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 gremove\at once}[\marg{cs}\marg{search}]
    \sinceversion{0.9}The same as \cs{cnltx\at remove\at once} but acts
    globally.
  \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 gremove\at all}[\marg{cs}\marg{search}]
    \sinceversion{0.9}The same as \cs{cnltx\at remove\at all} but acts
    globally.
\end{commands}

\paragraph{Miscellaneous}
\begin{commands}
  \expandable\command{cnltx\at par}
    Expands to \cs*{par}.  Sometimes you need to smuggle a \cs*{par} in a
    short macro \ldots
  \expandable\command{cnltx\at stripbs}
    A shortcut for \verbcode+\expandafter\@gobble\string+.
  \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'.
\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{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.  \cs{Marg} is defined
    \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}}\label{sec:list-entr-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}