summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/tagging
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/tagging
Initial commit
Diffstat (limited to 'macros/latex/contrib/tagging')
-rw-r--r--macros/latex/contrib/tagging/README20
-rw-r--r--macros/latex/contrib/tagging/tagging.pdfbin0 -> 82856 bytes
-rw-r--r--macros/latex/contrib/tagging/tagging.sty59
-rw-r--r--macros/latex/contrib/tagging/tagging.tex364
4 files changed, 443 insertions, 0 deletions
diff --git a/macros/latex/contrib/tagging/README b/macros/latex/contrib/tagging/README
new file mode 100644
index 0000000000..4f24345ef6
--- /dev/null
+++ b/macros/latex/contrib/tagging/README
@@ -0,0 +1,20 @@
+ The `tagging' package provides document configuration by
+including or omitting tagged input.
+
+ tagging is licenced under the LPPL. For more details,
+please see the accompanying manual: taggingmanual.pdf.
+
+Change History
+~~~~~~~~~~~~~~
+
+2011-08-22 Initial release, providing:
+
+ \tagged{list}{y} Conditional inclusion
+ \untagged{list}{n} Conditional exclusion
+ \iftagged{list}{y}{n} Conditional inclusion/exclusion
+ \begin{taggedblock}{list} Conditionally included environment
+ \end{taggedblock}
+ \begin{untaggedblock}{list} Conditionally included environment
+ \end{taggedblock}
+ \usetag{list} Turn tags on
+ \droptag{list} Turn tags off
diff --git a/macros/latex/contrib/tagging/tagging.pdf b/macros/latex/contrib/tagging/tagging.pdf
new file mode 100644
index 0000000000..0f911cdac9
--- /dev/null
+++ b/macros/latex/contrib/tagging/tagging.pdf
Binary files differ
diff --git a/macros/latex/contrib/tagging/tagging.sty b/macros/latex/contrib/tagging/tagging.sty
new file mode 100644
index 0000000000..c947639043
--- /dev/null
+++ b/macros/latex/contrib/tagging/tagging.sty
@@ -0,0 +1,59 @@
+% tagging.sty
+% 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
+% --------------------------------------------------------------
+\ProvidesPackage{tagging}[2011/08/04]
+\RequirePackage{etoolbox,verbatim}
+\newcommand{\taggedy}{\relax}
+\newcommand{\taggedn}{\relax}
+\newcommand\usetag[1]{%
+ \def\do##1{\csdef{tagged@##1}{}}%
+ \docsvlist{#1}}%
+\newcommand\droptag[1]{%
+ \def\do##1{\csundef{tagged@##1}{}}%
+ \docsvlist{#1}}%
+\newenvironment{taggedblock}[1]%
+ {\def\do##1{%
+ \ifcsname tagged@##1\endcsname%
+ \let\comment\relax%
+ \let\endcomment\relax%
+ \fi}%
+ \docsvlist{#1}%
+ \comment}%
+ {\endcomment\leavevmode}%
+\newenvironment{untaggedblock}[1]{%
+ \csdef{@tagged@flag}{}
+ \def\do##1{%
+ \ifcsname tagged@##1\endcsname%
+ \csundef{@tagged@flag}{}
+ \fi}%
+ \docsvlist{#1}%
+ \ifcsname @tagged@flag\endcsname%
+ \let\comment\relax%
+ \let\endcomment\relax%
+ \fi%
+ \comment}%
+ {\endcomment\leavevmode}%
+\newcommand{\iftagged}[3]%
+ {\renewcommand{\taggedy}{#2}%
+ \renewcommand{\taggedn}{#3}%
+ \def\do##1{%
+ \ifcsdef{tagged@##1}{\renewcommand{\taggedn}{\taggedy}}{}}%
+ \docsvlist{#1}%
+ \taggedn%
+ }%
+\newcommand{\tagged}[2]{\iftagged{#1}{#2}{}}
+\newcommand{\untagged}[2]{\iftagged{#1}{}{#2}}
diff --git a/macros/latex/contrib/tagging/tagging.tex b/macros/latex/contrib/tagging/tagging.tex
new file mode 100644
index 0000000000..15ae60e47e
--- /dev/null
+++ b/macros/latex/contrib/tagging/tagging.tex
@@ -0,0 +1,364 @@
+% 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}