% taggingmanual.tex
% Copyright 2011 Brent Longborough
%
% 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 Brent Longborough.
%
% This work consists of these files: 
%     tagging.sty, tagging.tex, and tagging.pdf
% -----------------------------------------------------
\documentclass[a4paper,12pt,twoside,openany]{memoir}
\usepackage{showexpl}
\usepackage{tgpagella}
\usepackage{tgadventor}
\usepackage{fontspec}
\defaultfontfeatures{Ligatures=TeX}
\setmainfont[Numbers={Proportional,OldStyle}]{TeX Gyre Pagella}
\setsansfont[Numbers={Proportional,OldStyle}]{TeX Gyre Adventor}
\setmonofont{Consolas}
\usepackage{tagging}
\setulmarginsandblock{0.11111\paperwidth}{0.22222\paperwidth}{*}
\setlrmarginsandblock{0.11111\paperwidth}{0.22222\paperwidth}{*}
\setheadfoot{1.2\baselineskip}{0.0849\paperwidth}
\setmarginnotes{0.125\foremargin}{0.75\foremargin}{\onelineskip}
\setheaderspaces{*}{*}{0.618}
\checkandfixthelayout[fixed]
\tightlists
\chapterstyle{bringhurst}
\pagestyle{ruled}
\settocdepth{section}
\setsecnumdepth{none}
\newcommand{\tpfname}{\textsf{tagging.sty}}
\newcommand{\tpname}{\textsf{\itshape tagging}}
\newcommand{\gitVtag}{\space1.0}
\newcommand{\gitVtagn}{\space1.0}
% -----------------------------------------------------
\usepackage[%
	bookmarksnumbered,
	bookmarksopen,
	linktocpage,
	]{hyperref}
\hypersetup{
   pdfauthor={Brent Longborough},
   pdftitle={The tagging package for configuring documents},
   pdfsubject={Document configuration with LaTeX},
   pdfkeywords={tagging;document configuration},
}
\begin{document}
% -----------------------------------------------------
\title{%
	\Huge \tpfname\\[2ex]%
	\Large A package for document configuration
	}
\author{Brent Longborough}
\date{28th August, 2011}
\maketitle

{\centering
Version:\gitVtagn\\
}
%\vspace*{2\baselineskip}
% -----------------------------------------------------
\begingroup
\aliaspagestyle{chapter}{empty}
\setlength{\afterchapskip}{20pt}
\let\clearpage\relax
\let\chaptitlefont\Large\bfseries
\vspace*{5\baselineskip}
\tableofcontents*
\clearpage
\endgroup
% -----------------------------------------------------
\chapter{Introduction}
\tpname\ is a \LaTeX\ package to help you easily to
produce multiple editions of a document from a single source,
or to reuse varying parts of an input file
to produce more than one result at different places
in a single document.

To use \tpname, just include a standard \verb!\usepackage{tagging}!
in your document preamble; there are no package options.

With \tpname, you mark up parts of your
\LaTeX source code with \textit{tags} --- labels which
make some kind of sense for you in relation to
the document you are writing.

For example, imagine you are writing a car owners' manual.\footnote{%
OK, I know Peugeot don't do this,
but imagine a top-end luxury car manufacturer.}
The car can have optional features, such as automatic transmission
or a navigation system, and can be powered by diesel or petrol.

In your source code, \tpname\ allows you to
mark up different parts of the text that
are required (or not) for a particular label
(such as \textbf{petrol}, \textbf{diesel}, \textbf{satnav},
and \textbf{auto} in this case).

Separately, you specify which of your tags you wish to activate;
when you process the document, different marked pieces are then
included or excluded in accordance with your markup
and the active tags.

Alternatively, you might prefer to tag pieces of the document
as applying to given models, by labelling them with one more
model designations. 
For such an application, you would probably have
a number of master document source files,
each of which would activate the appropriate tags,
and then input or include one or more source files
containing the marked-up content.

Another application, such as writing standard letters,
might involve simply changing the tags to be activated
in the preamble of a marked-up source file.

Yet another application might involve describing the way
in which something --- an idea, an algorithm, for instance --- has evolved.
The description of the evolving thing could be labelled with its stages,
and then repeatedly imbedded from a master source document with different
active tags to reflect the stage in its evolution. 

The possibilities are, if not limitless,
at least very extensive.
Here are a few more:
\begin{itemize}
\item Redacted v. unredacted
\item Report v. management summary
\item Teacher v. Student material
\item Question v. Answer
\end{itemize}
% -----------------------------------------------------
\chapter{Tagging commands}
\section{Tags and tag lists}
All the commands and environments provided by \tpname\
take a list of one or more tags as their first parameter.
Each tag must consist of one or more
alphabetic characters
(A-Z,a-z)%
\footnote{%
    Sorry, I haven't yet worked out
    how to provide support for accented characters.
    I suspect it means messing with catcodes,
    so please don't hold your breath waiting for it
}
which have some meaning for the user.
A tag list is a set of one or more tags separated by commas.

Tagged text is included in the document, or excluded,
if any of its tags is `active' at that point in the document.
Commands are available to include or exclude text based on its
particular tag markup.

Examples:

\begin{centering}
\begin{tabularx}{0.618\textwidth}{lX}
\textbf{Three tags:}&\texttt{draft redacted student}\\
\textbf{A tag list:}&\texttt{draft,student,linux}
\end{tabularx}\\[\baselineskip]
\end{centering}

\tpname\ does not (deliberately, anyway) restrict the use of tagging to text;
it may also be used to control document setup and formatting in the preamble
as well as in the body of the document.
% - - - - - - - - - - - - - - - - - - - - - - - - - - -
\section{Text tagging commands}
The three markup commands provided by \tpname\
take as parameters a tag list and some text to be included or excluded.
Here they are:
% - - - - - - - - - - - - - - - - - - - - - - - - - - -
\subsection{{\ttfamily\textbackslash tagged\{{\itshape<taglist>}\}\{{\itshape<source text>}\}}}
If \emph{any} of the tags in \texttt{\itshape<taglist>} is active,
then the \texttt{\itshape<source text>} will be included as part of the document;
if not, it will be excluded.
\subsection{{\ttfamily\textbackslash untagged\{{\itshape<taglist>}\}\{{\itshape<alt text>}\}}}
If \emph{none} of the tags in \texttt{\itshape<taglist>} is active,
then the \texttt{\itshape<alt text>} will be included as part of the document;
if not, it will be excluded.
% - - - - - - - - - - - - - - - - - - - - - - - - - - -
\subsection{{\ttfamily\textbackslash iftagged\{{\itshape<taglist>}\}\{{\itshape<source text>}\}\{{\itshape<alt text>}\}}}
This is a combination of {\ttfamily\textbackslash tagged} and {\ttfamily\textbackslash untagged}:
If \emph{any} of the tags in \texttt{\itshape<taglist>} is active,
then the \texttt{\itshape<source text>} will be included as part of the document;
if \emph{none} of the tags is active,
then \texttt{\itshape<alt text>} will replace \texttt{\itshape<source text>}.

% - - - - - - - - - - - - - - - - - - - - - - - - - - -
\section{Tagged environments}
\tpname\ defines two environments: one to include and one to exclude text.
As you might expect, these environments are both coded with a
{\ttfamily\textbackslash begin\{\}}-{\ttfamily\textbackslash end\{\}} pair.
\subsection{{\ttfamily\textbackslash begin\{taggedblock\}\{{\itshape<taglist>}\}}}
Source text placed inside a \texttt{taggedblock} environment
is included in the document if \emph{at least one} of the tags in
\texttt{\itshape<taglist>} is active.
% - - - - - - - - - - - - - - - - - - - - - - - - - - -
\subsection{{\ttfamily\textbackslash begin\{untaggedblock\}\{{\itshape<taglist>}\}}}
Source text placed inside an \texttt{untaggedblock} environment
is included in the document only if \emph{none} of the tags in
\texttt{\itshape<taglist>} is active.

% - - - - - - - - - - - - - - - - - - - - - - - - - - -
\section{Tag activation and control}
The tag control commands determine which tags
are active at any point in the document.
The document starts with all tags inactive;
\tpname\ requires that you explicitly activate 
the tags you need.

Once a tag has been activated, it remains active from that point
in the document to the point at which it is deactivated,
or to the end of the document if not deactivated.
All tags operate independently:
activating or deactivating a given tag has no hidden effect on other tags.

\subsection{{\ttfamily\textbackslash usetag\{{\itshape<taglist>}\}}}
This command activates \emph{all} the tags in \texttt{\itshape<taglist>}.
% - - - - - - - - - - - - - - - - - - - - - - - - - - -
\subsection{{\ttfamily\textbackslash droptag\{{\itshape<taglist>}\}}}
This command deactivates \emph{all} the tags in \texttt{\itshape<taglist>}.
\tpname\ is too simple to include a command 
to ``deactivate all known tags'' --- sorry.

% - - - - - - - - - - - - - - - - - - - - - - - - - - -
\section{Tag nesting}
It is possible to nest markup, though it maybe confusing unless you lay it out carefully.
For example,
\begin{verbatim}
\tagged{lux}{\untagged{nav}{Sorry, something's wrong here!}}
\end{verbatim}
would apologise if it's a luxury model without a satnav.

% -----------------------------------------------------
\chapter{Examples}
These examples show first the markup, then the formatted result in a box below it.
\section{Example 1: Tailoring a simple letter}
\noindent 1a:
\begin{LTXexample}[pos=b]
\usetag{good}

Dear Don,

The results of your latest evaluation were
\tagged{good}{excellent.}
\tagged{bad}{disappointing.}
\untagged{good,bad}{satisfactory.}

\iftagged{bad}{I hope you will be able to improve.
Please let me know if I can do anything to help.
}{Keep up the good work!}
\end{LTXexample}

\noindent 1b:
\droptag{good}
\begin{LTXexample}[pos=b]
\usetag{bad}

Dear Don,

The results of your latest evaluation were
\tagged{good}{excellent.}
\tagged{bad}{disappointing.}
\untagged{good,bad}{satisfactory.}

\iftagged{bad}{I hope you will be able to improve.
Please let me know if I can do anything to help.
}{Keep up the good work!}
\end{LTXexample}

% - - - - - - - - - - - - - - - - - - - - - - - - - - -
\clearpage
\section{Example 2: Tailoring a customer brochure}
\noindent 2a:
\begin{LTXexample}[pos=b]
\droptag{deluxe} % Not needed here; for illustration only
Welcome to your new mobile phone!
\iftagged{deluxe}{Tailored for}{For} your convenience,
it comes with:
\begin{itemize}
    \item A screen
    \begin{taggedblock}{deluxe}
       \item A built-in microwave oven and Shrubbery
    \end{taggedblock}
    \item An operating system
\end{itemize}
\end{LTXexample}
\vspace*{\baselineskip}
\noindent 2b:
\begin{LTXexample}[pos=b]
\usetag{deluxe}
Welcome to your new mobile phone!
\iftagged{deluxe}{Tailored for}{For} your convenience,
it comes with:
\begin{itemize}
    \item A screen
    \begin{taggedblock}{deluxe}
       \item A built-in microwave oven and Shrubbery
    \end{taggedblock}
    \item An operating system
\end{itemize}
\end{LTXexample}
% -----------------------------------------------------
\chapter{Etc}
\section{Acknowledgements and dependencies}

\tpname\ is based on an idea by \href{http://tex.stackexchange.com/users/2674/leo-liu}{Leo Liu}.
It would have been a lot more difficult to implement without the help of 
Philipp Lehman's
\href{http://www.ctan.org/tex-archive/macros/latex/contrib/etoolbox}{etoolbox}
and of
\href{http://www.ctan.org/pkg/verbatim}{verbatim}, currently maintained by
Rainer Schöpf, both of which are required for \tpname to work.

The \href{http://tex.stackexchange.com}{\TeX.SE community}
has been a constant source of help, inspiration, and amazement.

Of course, we all stand on the shoulders of giants: Donald Knuth,
and then too many others to name.

Thank you all. Any failings that remain are entirely
``an ill-favoured thing, sir, but mine own''.

% - - - - - - - - - - - - - - - - - - - - - - - - - - -
\section{Copyright \& licence}
Copyright \copyright\ 2011, Brent Longborough.

This work --- \tpname\ --- 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 at
\url{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 Brent Longborough.

This work consists of the files tagging.sty, taggingtest.tex, 
taggingmanual.tex, and taggingmanual.pdf

% - - - - - - - - - - - - - - - - - - - - - - - - - - -
\section{From the author}
I hope you find this package useful.
Please bear in mind that I am very much an amateur \TeX nician,
so \tpname\ may be incompatible with some packages, and,
if you find such an incompatibility, I may not have the skill to fix it.

However, I'll be very happy to receive your comments by email.\\[\baselineskip]
Enjoy!\\
Brent Longborough\\[\baselineskip]
\textsf{brent+tagging (at) longborough (dot) org}\\
and at \href{http://tex.stackexchange.com/users/344/brent-longborough}{\TeX.SE}
% -----------------------------------------------------
\end{document}
