% !TEX TS-program = latexmkl % !TEX encoding = UTF-8 Unicode % !TeX spellcheck = en_GB % ----------------------------------------------------- % tagging.tex % Copyright 2019 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{\tpn}{tagging} \newcommand{\tpfname}{\textsf{\tpn.sty}} \newcommand{\tpname}{\textsf{\itshape \tpn}} \newcommand{\gitVtag}{\space1.1.0.1} \newcommand{\gitVtagn}{\space1.1.0.1} % ----------------------------------------------------- \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{9th September, 2019} \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 which alter its intrinsic behaviour, although later you will see how any options you may give are subverted. 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. 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}\}\{{\itshape}\}}} If \emph{any} of the tags in \texttt{\itshape} is active, then the \texttt{\itshape} will be included as part of the document; if not, it will be excluded. \subsection{{\ttfamily\textbackslash untagged\{{\itshape}\}\{{\itshape}\}}} If \emph{none} of the tags in \texttt{\itshape} is active, then the \texttt{\itshape} will be included as part of the document; if not, it will be excluded. % - - - - - - - - - - - - - - - - - - - - - - - - - - - \subsection{{\ttfamily\textbackslash iftagged\{{\itshape}\}\{{\itshape}\}\{{\itshape}\}}} This is a combination of {\ttfamily\textbackslash tagged} and {\ttfamily\textbackslash untagged}: If \emph{any} of the tags in \texttt{\itshape} is active, then the \texttt{\itshape} will be included as part of the document; if \emph{none} of the tags is active, then \texttt{\itshape} will replace \texttt{\itshape}. % - - - - - - - - - - - - - - - - - - - - - - - - - - - \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}\}}} Source text placed inside a \texttt{taggedblock} environment is included in the document if \emph{at least one} of the tags in \texttt{\itshape} is active. % - - - - - - - - - - - - - - - - - - - - - - - - - - - \subsection{{\ttfamily\textbackslash begin\{untaggedblock\}\{{\itshape}\}}} Source text placed inside an \texttt{untaggedblock} environment is included in the document only if \emph{none} of the tags in \texttt{\itshape} 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}\}}} This command activates \emph{all} the tags in \texttt{\itshape}. % - - - - - - - - - - - - - - - - - - - - - - - - - - - \subsection{{\ttfamily\textbackslash usepackage[{\itshape}]\{\tpn\}}} If you wish, you may activate one or more tags, once, in your document preamble by passing a taglist as options when you call the package. \emph{All} the tags in \texttt{\itshape} are activated. Any tags activated this way can still be deactivated and reactivated as many times as you may need in the body of the document. % - - - - - - - - - - - - - - - - - - - - - - - - - - - \subsection{{\ttfamily\textbackslash droptag\{{\itshape}\}}} This command deactivates \emph{all} the tags in \texttt{\itshape}. \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. I am most grateful to Frank Mittelbach, who intervened to fix my dodgy code and to provide the ability to activate tags as package options, thereby directly inspiring v1.1. 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''. % - - - - - - - - - - - - - - - - - - - - - - - - - - - \clearpage \section{Copyright \& licence} Copyright \copyright\ 2019, 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, tagging.tex, and tagging.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+ctan (at) llwyd-consulting (dot) cymru}\\ and at \href{http://tex.stackexchange.com/users/344/brent-longborough}{\TeX.SE} % ----------------------------------------------------- \end{document}