path: root/macros/latex/contrib/apptools/apptools.dtx

% \iffalse meta-comment
%
% File: apptools.dtx
% Version: 2012/11/28 v1.0
% Info: Tools for customizing appendices
%
% Copyright (c) 2012 Sebastian Kuhnert <mail at sebastian-kuhnert.de>
%
% This work may be distributed and/or modified under the conditions of the LaTeX
% Project Public License, either version 1.3c of this license or (at your
% option) any later version. The latest version of this license is available at
% http://www.latex-project.org/lppl.txt and version 1.3c or later is part of all
% distributions of LaTeX version 2008/05/04 or later.
%
% This work has the LPPL maintenance status `maintained', the Current Maintainer
% of this work is Sebastian Kuhnert.
%
% This work consists of the main source file apptools.dtx and the derived files
%    apptools.sty, apptools.pdf, apptools.ins, apptools.drv, apptools-test.tex
%
% Distribution:
%    CTAN:macros/latex/contrib/apptools/apptools.dtx
%    CTAN:macros/latex/contrib/apptools/apptools.ins
%    CTAN:macros/latex/contrib/apptools/apptools.pdf
%
% Unpacking:
%    (a) If apptools.ins is present:
%           tex apptools.ins
%    (b) Without apptools.ins:
%           tex apptools.dtx
%
% Documentation:
%    (a) If apptools.drv is present:
%           pdflatex apptools.drv
%    (b) Without apptools.drv:
%           pdflatex apptools.dtx; ...
%
% Installation:
%    TDS:tex/latex/apptools/apptools.sty
%    TDS:doc/latex/apptools/apptools.pdf
%    TDS:doc/latex/apptools/apptools-test.tex
%    TDS:source/latex/apptools/apptools.dtx
%
%<*ignore>
\begingroup
  \catcode123=1 %
  \catcode125=2 %
  \def\x{LaTeX2e}%
\expandafter\endgroup
\ifcase 0\expandafter
         \ifx\csname processbatchFile\endcsname\relax\else1\fi
         \ifx\fmtname\x\else 1\fi\relax
\else\csname fi\endcsname
%</ignore>
%<*install>
\input docstrip.tex
\Msg{************************************************************************}
\Msg{* Installation}
\Msg{* Package: apptools 2012/11/28 v1.0 Tools for customizing appendices}
\Msg{************************************************************************}

\keepsilent
\askforoverwritefalse

\let\MetaPrefix\relax
\preamble

This is a generated file.

Project: apptools
Version: 2012/11/28 v1.0

Copyright (c) 2012 by Sebastian Kuhnert <mail at sebastian-kuhnert.de>

This work may be distributed and/or modified under the conditions of the LaTeX
Project Public License, either version 1.3c of this license or (at your
option) any later version. The latest version of this license is available at
http://www.latex-project.org/lppl.txt and version 1.3c or later is part of all
distributions of LaTeX version 2008/05/04 or later.

This work has the LPPL maintenance status `maintained', the Current Maintainer
of this work is Sebastian Kuhnert.

This work consists of the main source file apptools.dtx and the derived files
   apptools.sty, apptools.pdf, apptools.ins, apptools.drv, apptools-test.tex.

\endpreamble
\let\MetaPrefix\DoubleperCent

\generate{%
  \file{apptools.ins}{\from{apptools.dtx}{install}}%
  \file{apptools.drv}{\from{apptools.dtx}{driver}}%
  \usedir{tex/latex/apptools}%
  \file{apptools.sty}{\from{apptools.dtx}{package}}%
  \usedir{doc/latex/apptools}%
  \file{apptools-test.tex}{\from{apptools.dtx}{test}}%
}

\catcode32=13\relax% active space
\let =\space%
\Msg{************************************************************************}
\Msg{*}
\Msg{* To finish the installation you have to move the following}
\Msg{* files into a directory searched by TeX:}
\Msg{*}
\Msg{*     apptools.sty}
\Msg{*}
\Msg{* To produce the documentation run:}
\Msg{*}
\Msg{*     pdflatex apptools.drv}
\Msg{*}
\Msg{* Happy TeXing!}
\Msg{*}
\Msg{************************************************************************}

\endbatchfile
%</install>
%<*ignore>
\fi
%</ignore>
%<*driver>
\NeedsTeXFormat{LaTeX2e}
\ProvidesFile{apptools.drv}%
  [2012/11/28 v1.0 Tools for customizing appendices]%
\documentclass{ltxdoc}
\usepackage{hypdoc}
\usepackage[openlevel=2]{bookmark}
\usepackage{array}

\usepackage[T1]{fontenc}
\usepackage{textcomp}
\usepackage[scaled]{berasans}
\usepackage[scaled]{beramono}
\usepackage[bitstream-charter]{mathdesign}
\usepackage[activate]{microtype}

\usepackage{xcolor}
\hypersetup{linkcolor=red!50!black,
            urlcolor=purple!50!black}
\urlstyle{sf}

\usepackage[utf8]{inputenc}

\usepackage{etoolbox}

\usepackage[british,iso]{isodate}

\usepackage{embedfile}
\embedfile[desc={LaTeX docstrip source file for package `apptools'},
           mimetype={text/x-tex}]{apptools.dtx}

\newcommand{\CTAN}[1]{\href{http://mirror.ctan.org/#1}{CTAN:\nolinkurl{#1}}}
\newcommand{\TDS}[1]{TDS:\nolinkurl{#1}}
\newcommand{\file}[1]{\nolinkurl{#1}}

\makeatletter
\renewcommand{\DescribeMacro}[1]{%
  \DescribeMACRO #1\@empty\@empty\@empty
}
\def\DescribeMACRO#1#2\@empty{%
  \addvspace{1em}\noindent
  \phantomsection
  \label{macrodesc:\expandafter\@gobble\string #1\@empty}%
  \addcontentsline{toc}{subsection}{%
    \texttt{\textbackslash\expandafter\@gobble\string #1\@empty}}%
  \SpecialUsageIndex{#1}%
  \begingroup
  \togglefalse{linktodesc}%
  \hspace{-4em}\texttt{\color{blue!50!black}%
    \expandafter\cs\expandafter{\expandafter\@gobble\string #1\@empty}#2}%
  \endgroup
  \par\smallskip\noindent\ignorespaces
}
\renewcommand{\PrintMacroName}[1]{%
  \phantomsection\label{macrodef:\expandafter\@gobble\string#1\@empty}%
  \raisebox{\baselineskip}{\hypertarget{macrodef:\expandafter\@gobble\string
      #1\@empty}{}}%
  \bookmark[dest={macrodef:\expandafter\@gobble\string
    #1\@empty},level=4]{\textbackslash #1}%
  \begingroup
  \toggletrue{linktodesc}%
  \strut\MacroFont\expandafter\cs\expandafter{\expandafter\@gobble\string
    #1\@empty}%
  \endgroup
}
\renewcommand{\meta@font@select}{%
  \rmfamily\itshape
}
\renewcommand{\@hangfrom}[1]{%
  \setbox\@tempboxa\hbox{\llap{#1}}%
  \hangindent\wd\@tempboxa
  \noindent\box\@tempboxa
}
\makeatother

\newtoggle{linktodesc}
\toggletrue{linktodesc}
\csdef{cs }#1{%
  \iftoggle{linktodesc}{%
    \ifcsdef{r@macrodesc:#1}{%
     \hyperref[macrodesc:#1]{\texttt{\color{blue!50!black}\char `\\#1}}%
    }{%
      \texttt{\color{blue!50!black}\char `\\ #1}%
    }%
  }{%
    \ifcsdef{r@macrodef:#1}{%
      \hyperref[macrodef:#1]{\texttt{\color{blue!50!black}\char `\\#1}}%
    }{%
      \texttt{\color{blue!50!black}\char `\\#1}%
    }%
  }%
}

\EnableCrossrefs
\CodelineIndex

\begin{document}
\DocInput{apptools.dtx}
\end{document}
%</driver>
% \fi
%
% \CheckSum{89}
%
% \CharacterTable
%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%   Digits        \0\1\2\3\4\5\6\7\8\9
%   Exclamation   \!     Double quote  \"     Hash (number) \#
%   Dollar        \$     Percent       \%     Ampersand     \&
%   Acute accent  \'     Left paren    \(     Right paren   \)
%   Asterisk      \*     Plus          \+     Comma         \,
%   Minus         \-     Point         \.     Solidus       \/
%   Colon         \:     Semicolon     \;     Less than     \<
%   Equals        \=     Greater than  \>     Question mark \?
%   Commercial at \@     Left bracket  \[     Backslash     \\
%   Right bracket \]     Circumflex    \^     Underscore    \_
%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%   Right brace   \}     Tilde         \~}
%
% \GetFileInfo{apptools.drv}
%
% \title{The \texttt{apptools} package}
% \author{Sebastian Kuhnert\\\texttt{mail at sebastian-kuhnert.de}}
% \date{Documentation for version \csname @gobble\endcsname v1.0
%       (\printdateTeX{2011/11/21})}
%
% \maketitle
%
% \begin{abstract}
%   The \texttt{apptools} package provides tools to customize appendices. It
%   provides an \cs{AtAppendix} command to add code to a hook that is executed
%   when \cs{appendix} is called by the user. Additionally, a \TeX{} conditional
%   \cs{ifappendix} and a \LaTeX-style conditional \cs{IfAppendix} are provided
%   to check if \cs{appendix} has already been called.
% \end{abstract}
%
% \tableofcontents
%
%
% \section{Introduction}
%
% Sometimes it is useful to execute some code at the start of the appendix in an
% automated way.
% \textsf{KOMA-Script}\footnote{\CTAN{macros/latex/contrib/koma-script/}} classes
% provide a hook for this purpose. Relatedly, the
% |apa|\footnote{\CTAN{macros/latex/contrib/apa/}} and
% |apa6|\footnote{\CTAN{macros/latex/contrib/apa6/}} classes provide a
% \TeX\ conditional \cs{ifappendix} to check if \cs{appendix} has been
% called already. This package provides an interface to both these features that
% is independent of the document class.
%
%
% \subsection{License}
% 
% Copyright \copyright{} 2012 Sebastian Kuhnert. Permission is granted to copy,
% distribute and/or modify this software under the terms of the \LaTeX{} Project
% Public Licence, version 1.3c or later.\footnote{The latest version of this
% license is available at \url{http://www.latex-project.org/lppl/lppl.txt}; it
% should also be included in your \TeX{} distribution, usually at
% \TDS{doc/latex/base/lppl.pdf}} This package is maintained, the Current
% Maintainer is Sebastian Kuhnert.
%
% \section{User Interface}
%
% \DescribeMacro{\AtAppendix\marg{code}}%
% Add \meta{code} to the hook that is executed when \cs{appendix} is given.
%
% \DescribeMacro{\IfAppendix\marg{then}\marg{else}}%
% Expands to \meta{else} before \cs{appendix} is executed, and to \meta{then}
% afterwards.
%
% \DescribeMacro{\ifappendix}%
% Calling \cs{ifappendix} \meta{then}\cs{else} \meta{else}\cs{fi} expands to
% \meta{else} before \cs{appendix} is executed, and to \meta{then} afterwards.
%
% \StopEventually{
% }
%
% \section{Implementation}
% \togglefalse{linktodesc}
%    \begin{macrocode}
%<*package>
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{apptools}
  [2012/11/28 v1.0 Tools for customizing appendices]%
%    \end{macrocode}
%
% \begin{macro}{\apptools@hook}
%   The hook that will be called when \cs{appendix} is executed. By default it
%   just calls \cs{appendixtrue} to make \cs{ifappendix} and \cs{IfAppendix}
%   work correctly.
%    \begin{macrocode}
\def\apptools@hook{\appendixtrue}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\AtAppendix}
%   Extend \cs{apptools@hook}.
%    \begin{macrocode}
\newcommand{\AtAppendix}{%
  \g@addto@macro\apptools@hook
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\apptools@origappendix}
% \begin{macro}{\appendix}
%   Call the hook \cs{apptools@hook} in \cs{appendix}.
%    \begin{macrocode}
\let\apptools@origappendix\appendix
\def\appendix{%
  \apptools@hook \apptools@origappendix
}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\ifappendix}
%   The \TeX\ conditional behind \cs{IfAppendix}. The classes |apa| and |apa6|
%   already define \cs{ifappendix} as \TeX\ conditional, so the \LaTeX\ version
%   has to be called differently. A second \cs{newif} call for the same
%   conditional only has the effect of setting it to false, which is
%   unproblematic in this case.
%    \begin{macrocode}
\newif\ifappendix
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\IfAppendix}
%   The \LaTeX{} style conditional provided by this package.
%    \begin{macrocode}
\newcommand*{\IfAppendix}{%
  \ifappendix
    \expandafter\@firstoftwo
  \else
    \expandafter\@secondoftwo
  \fi
}
%    \end{macrocode}
% \end{macro}
%
%
%    \begin{macrocode}
%</package>
%    \end{macrocode}
%
%
% \section{Test}
%
% The file \file{apptools-test.tex} performs some simple tests that the commands
% provided by this package actually work.
%
%    \begin{macrocode}
%<*test>
\NeedsTeXFormat{LaTeX2e}
\nofiles
\documentclass{article}
\usepackage{apptools}[2012/11/28]
\usepackage{qstest}
\IncludeTests{*}
\LogTests{log}{*}{*}

\begin{document}
\makeatletter

\begin{qstest}{AtAppendix}{AtAppendix}
  \def\defaulthook{\appendixtrue}
  \Expect*{\meaning\defaulthook}*{\meaning\apptools@hook}
  \g@addto@macro\defaulthook{\def\fooafterappendix{foo}}
  \AtAppendix{\def\fooafterappendix{foo}}
  \Expect*{\meaning\defaulthook}*{\meaning\apptools@hook}
  \Expect*{\meaning\fooafterappendix}{undefined}
\end{qstest}

\begin{qstest}{ifbefore}{ifbefore}
  \Expect{else}*{\ifappendix then\else else\fi}
  \Expect{else}*{\IfAppendix{then}{else}}
\end{qstest}

\appendix

\begin{qstest}{ifafter}{ifafter}
  \Expect{then}*{\ifappendix then\else else\fi}
  \Expect{then}*{\IfAppendix{then}{else}}
\end{qstest}

\begin{qstest}{hook}{hook}
  \def\expected{foo}
  \Expect*{\meaning\fooafterappendix}*{\meaning\expected}
\end{qstest}

\end{document}
\@@end
%</test>
%    \end{macrocode}
%
% \section{Installation}
%
% \subsection{Obtaining the package}
% The package source is attached to this PDF file and can be extracted with many
% recent PDF viewers. Alternatively, it can be obtained from
% \CTAN{macros/latex/contrib/apptools/apptools.dtx}.
%
% \subsection{Unpacking the package}
% The \file{.dtx} file is a self-extracting \textsf{docstrip} archive. The files are
% extracted by running the \file{.dtx} through plain \TeX:
% \begin{quote}
%   |tex apptools.dtx|
% \end{quote}
% If the \file{.ins} file is already present, you can run \TeX\
% alternatively on the \file{.ins} file.
% 
% \subsection{Generating the package documentation}
% Running the \file{.dtx} file through pdf\LaTeX{} generates the package
% documentation:
% \begin{quote}
%   |pdflatex apptools.dtx|
% \end{quote}
% Multiple passes will be necessary to get the cross references right. The index
% will be generated automatically if |makeindex| is allowed for \cs{write18};
% otherwise the following command is needed before the last pdf\LaTeX{}
% pass:
% \begin{quote}
%   |makeindex -s gind.ist apptools.idx|
% \end{quote}
%
% \subsection{Moving the files}
% To finish the installation, the generated files need to be moved to an
% appropriate place in your local \TeX\ Directory Structure (TDS) tree, also
% known as |texmf| tree. The suggested locations are:
% \begin{quote}
%   \begin{tabular}{@{}>{\sffamily}l@{\quad$\mapsto$\quad}>{TDS:\sffamily}l@{}}
%     apptools.sty & tex/latex/apptools/apptools.sty\\
%     apptools.pdf & doc/latex/apptools/apptools.pdf\\
%     apptools-test.tex & doc/latex/apptools/apptools-test.tex\\
%     apptools.dtx & source/latex/apptools/apptools.dtx\\
%   \end{tabular}
% \end{quote}
%
% \appendix
% \section*{Revision History}
% \addcontentsline{toc}{section}{Revision History}
%
% \newcommand{\version}[2]{^^A
%   \hypertarget{version.#1}{}^^A
%   \subsection*{\llap{v#1\quad}#2}^^A
%   \bookmark[dest=version.#1,level=subsection]{v#1, #2}^^A
%   \ignorespaces
% }
%
% \version{1.0}{2012-11-28}
% Initial release.
%
% \makeatletter
% \immediate\closeout\@indexfile
% \makeatother
% \immediate\write18{makeindex -s gind.ist \jobname.idx}
% \IndexPrologue{
%   \section*{Index}\addcontentsline{toc}{section}{Index}
%   Most index entries refer to code line numbers; the definition of a command is
%   marked by underlining this number. Numbers in italics are an exception: They
%   give the page on which the command is described.
% }
% \PrintIndex
%
% \Finale
\endinput