summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/tagging/tagging.tex
blob: 55925ec7480a145b3943bcb9dca50f8db8045174 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
% !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<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 usepackage[{\itshape<taglist>}]\{\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<taglist>} 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<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.

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}