Debian Codegraph @

texmf-dist/source/latex/multiaudience/multiaudience.dtx

raw
1 % \iffalse
2 % $Id: multiaudience.dtx,v 1.9 2021/10/02 22:21:51 boris Exp $
3 %
4 %% Copyright 2015-2021, Boris Veytsman <[email protected]
5 %% This work may be distributed and/or modified under the
6 %% conditions of the LaTeX Project Public License, either
7 %% version 1.3 of this license or (at your option) any
8 %% later version.
9 %% The latest version of the license is in
10 %% http://www.latex-project.org/lppl.txt
11 %% and version 1.3 or later is part of all distributions of
12 %% LaTeX version 2003/06/01 or later.
13 %%
14 %% This work has the LPPL maintenance status `maintained'.
15 %%
16 %% The Current Maintainer of this work is Boris Veytsman
17 %%
18 % \begin{macrocode}
19 %<style>\NeedsTeXFormat{LaTeX2e}
20 %<*gobble>
21 \ProvidesFile{multiaudience.dtx}
22 %</gobble>
23 %<style>\ProvidesPackage{multiaudience}
24 %<*style>
25 [2021/10/02 v1.04 Generating versions for different audiences from the
26 same source]
27 % \end{macrocode}
28 %</style>
29 %<*gobble>
30 % \fi
31 % \CheckSum{85}
32 %
33 %
34 %% \CharacterTable
35 %% {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
36 %% 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
37 %% Digits \0\1\2\3\4\5\6\7\8\9
38 %% Exclamation \! Double quote \" Hash (number) \#
39 %% Dollar \$ Percent \% Ampersand \&
40 %% Acute accent \' Left paren \( Right paren \)
41 %% Asterisk \* Plus \+ Comma \,
42 %% Minus \- Point \. Solidus \/
43 %% Colon \: Semicolon \; Less than \<
44 %% Equals \= Greater than \> Question mark \?
45 %% Commercial at \@ Left bracket \[ Backslash \\
46 %% Right bracket \] Circumflex \^ Underscore \_
47 %% Grave accent \` Left brace \{ Vertical bar \|
48 %% Right brace \} Tilde \~}
49 %
50 %\iffalse
51 % \begin{macrocode}
52 \documentclass{ltxdoc}
53 \usepackage{hypdoc}
54 \PageIndex
55 \CodelineIndex
56 \RecordChanges
57 \EnableCrossrefs
58 \begin{document}
59 \DocInput{multiaudience.dtx}
60 \end{document}
61 % \end{macrocode}
62 %</gobble>
63 % \fi
64 % \MakeShortVerb{|}
65 % \GetFileInfo{multiaudience.dtx}
66 %
67 %
68 % \title{Generating multiple versions of a document for different
69 % audiences from the same source\thanks{\copyright 2015 Boris Veytsman}
70 % \thanks{This package was commissined by Neadwerx, \url{http://www.neadwerx.com/}}}
71 % \author{Boris Veytsman \thanks{[email protected]}}
72 % \date{\filedate, \fileversion}
73 % \maketitle
74 %
75 % \begin{abstract}
76 % The \textsl{multiaudience} package allows to generate several
77 % versions of the same document for different audiences
78 % \end{abstract}
79 %
80 % \tableofcontents
81 %
82 % \clearpage
83 %
84 %\section{Introduction}
85 %\label{sec:intro}
86 %
87 % Suppose you want to present the same paper, say, software design
88 % document, to software developers and executives. You expect that
89 % your intended readers have different interests and expectations:
90 % some paragraphs will be interesting only to the developers, while
91 % some---only to the executives. On the other hand, some paragraphs
92 % will be interesting to both. Basically you want two different
93 % versions of the document, one for each audience. Another example
94 % may be the situation where you need a public and a confidential
95 % versions of the same document (or even classified and unclassified
96 % ones).
97 %
98 % Of course standard version controls tools like \textsl{subversion},
99 % \textsl{git} or \textsl{CVS} allow you to create branches of your
100 % document, but in many cases this is not a good solution. If the
101 % versions have many paragraphs in common, you will find yourself
102 % constantly merging and branching your revisions.
103 %
104 % The package \textsl{multiaudience} offers an alternative solution to
105 % the problem. You create a \LaTeX\ document, clearly marking some
106 % parts for different audiences. When you process the document, you
107 % indicate, for which audience the current output is intended. The
108 % corresponding parts will be chosen.
109 %
110 %
111 %\section{User's guide}
112 %\label{sec:ug}
113 %
114 %
115 %\subsection{Invocation}
116 %\label{sec:ug_invocation}
117 %
118 % \DescribeMacro{\CurrentAudience}%
119 % \DescribeMacro{\DefCurrentAudience}%
120 % To use the package you need first to define the macro
121 % \cs{CurrentAudience}. There are two ways to do it: a \LaTeX-ish
122 % macro \cs{DefCurrentAudience}\marg{audience}
123 % \begin{verbatim}
124 % \DefCurrentAudience{execs}
125 % \end{verbatim}
126 % or \TeX-ish \cs{def} primitive:
127 % \begin{verbatim}
128 % \def\CurrentAudience{execs}
129 % \end{verbatim}
130 % You may set this parameter outside the document itself like this:
131 % \begin{verbatim}
132 % pdflatex "\def\CurrentAudience{execs}\input{file}"
133 % \end{verbatim}
134 % This trick allows one to generate all versions of output from the
135 % command line:
136 % \begin{verbatim}
137 % pdflatex -jobname file-execs "\def\CurrentAudience{execs}\input{file}"
138 % pdflatex -jobname file-devs "\def\CurrentAudience{devs}\input{file}"
139 % ...
140 % \end{verbatim}
141 %
142 % Then put in the preamble of your document \emph{after} defining the
143 % current audience
144 % \begin{verbatim}
145 % \usepackage{multiaudience}
146 % \end{verbatim}
147 %
148 % \DescribeMacro{\SetNewAudience}%
149 % After calling the package you need
150 % to list all possible audience using the command
151 % \cs{SetNewAudience}\marg{audience}, for example,
152 % \begin{verbatim}
153 % \SetNewAudience{execs}
154 % \SetNewAudience{devs}
155 % \SetNewAudience{admins}
156 % \end{verbatim}
157 %
158 % Now you can mark the portions of your document, for example,
159 % \begin{verbatim}
160 % \begin{shownto}{execs, admins}
161 % Text for execs and admins
162 % \end{shownto}
163 % \begin{shownto}{-, execs}
164 % Text for everybody but execs
165 % \end{shownto}
166 % \end{verbatim}
167 %
168 %
169 %\subsection{Visibility scopes}
170 %\label{sec:scopes}
171 %
172 % The package contains a number of commands and environments, that
173 % mark certain portions of document for different audiences. They all
174 % have as an argument an \marg{audiences} list. It is a
175 % comma-separated list of audiences (defined by the command
176 % \cs{SetNewAudience}, see Section~\ref{sec:ug_invocation}),
177 % optionally starting with the keyword ``-''. This argument defines
178 % the visibility scope of the command or environment.
179 %
180 % The rules are:
181 % \begin{enumerate}
182 % \item If the list \marg{audiences} does \emph{not} start with the
183 % keyword ``-'', it defines the audiences, which will see the
184 % corresponding content. All other audiences will not see it. For
185 % example, the command
186 % \begin{verbatim}
187 % \showto{execs, devs}{TEXT}
188 % \end{verbatim}
189 % makes TEXT visible only to execs and devs, but not to anybody
190 % else among listed audiences.
191 % \item If the list \marg{audience} starts with the keyword ``-'', the
192 % logic is inverted: the audiences from the list will \emph{not} see
193 % the contents. For example, the command
194 % \begin{verbatim}
195 % \showto{-, execs, devs}{TEXT}
196 % \end{verbatim}
197 % makes the text not visible to execs and devs.
198 % \end{enumerate}
199 %
200 % The scopes can be nested. For example, in the following situation
201 % TEXT~1 will be visible only to devs and execs, while TEXT~2 only to
202 % devs.
203 % \begin{verbatim}
204 % \begin{shownto}{devs,execs}
205 % TEXT 1
206 % \begin{shownto}{devs}
207 % TEXT 2
208 % \end{shownto}
209 % \end{shownto}
210 % \end{verbatim}
211 % There is, however, an important limitation: by nesting scopes you
212 % can hide a part of the document, but you cannot uncover it if it is
213 % hidden for the current audience by the enclosing scope. In other
214 % hands, the following makes TEXT~2 invisible to everybody:
215 % \begin{verbatim}
216 % \begin{shownto}{execs}
217 % TEXT 1
218 % \begin{shownto}{devs}
219 % TEXT 2
220 % \end{shownto}
221 % \end{shownto}
222 % \end{verbatim}
223 %
224 %
225 %\subsection{Commands and environments}
226 %\label{sec:ug_commands}
227 %
228 % \DescribeMacro{\showto}%
229 % The command \cs{showto}\marg{audience}\marg{contents} makes the
230 % \marg{contents} visible (or invisible) to the current audience
231 % according to the first argument, as describes in
232 % Section~\ref{sec:ug_invocation}.
233 %
234 % \DescribeMacro{\Footnote}%
235 % The macro \cs{Footnote}\marg{audience}\marg{footnote} creates a
236 % footnote with the visibility determined by the \marg{audience}
237 % argument.
238 %
239 % \DescribeEnv{shownto}%
240 % The environment
241 % \cs{begin\{shownto\}}\marg{audience}\ldots\cs{end\{shownto\}}
242 % makes the contents visible or invisible according to its argument.
243 %
244 %
245 % \DescribeEnv{Section}%
246 % \DescribeEnv{Subsection}%
247 % \DescribeEnv{Subsubsection}%
248 % \DescribeEnv{Paragraph}%
249 % \DescribeEnv{Subparagraph}%
250 % Environments |Section|, |Subsection|, |Subsubsection|, |Paragraph|,
251 % |Subparagraph| define section-like units with limited visibility.
252 % They have the structure like
253 % \cs{begin\{Section\}}\marg{audience}\oarg{short title}\marg{long
254 % title}\ldots\cs{end\{Section\}}, foe example
255 % \begin{verbatim}
256 % \begin{Section}{execs}[Executive comments]{Executive comments for
257 % the document}
258 % Text
259 % \end{Section}
260 % \end{verbatim}
261 %
262 %
263 %\subsection{Verbatim text}
264 %\label{sec:ug_verbatim}
265 %
266 % Due to the way verbatim is implemented in \LaTeX, it is currently
267 % impossile to directly put \cs{verb} and \texttt{verbatim} inside
268 % visibility scopes. There are several workarounds shown in the
269 % example document:
270 % \begin{enumerate}
271 % \item You can put parts of the text with verbatim constructions in
272 % separate files and \cs{input} them inside visibility scopes.
273 % \item You can use \cs{SaveVerbatim} and \cs{UseVerbatim} from
274 % \textsl{fancyvrb} package.
275 % \item The command \cs{path} from \textsl{hyperref} package can be
276 % used for short verbatim-like fragments.
277 % \end{enumerate}
278 %
279 %
280 %\subsection{Extensions}
281 %\label{sec:ug_extension}
282 %
283 % \DescribeMacro{\DefMultiaudienceCommand}%
284 % The macro \cs{DefMultiaudienceCommand}\marg{new command}\marg{old
285 % command} can add visibility argument to \marg{old command}. It is
286 % assumed that \marg{old command} has only one argument. For example,
287 % \cs{Footnote} command in Section~\ref{sec:ug_commands} was defined
288 % as
289 % \begin{verbatim}
290 % \DefMultiaudienceCommand{\Footnote}{\footnote}
291 % \end{verbatim}
292 %
293 % \DescribeMacro{\NewMultiaudienceSectionEnv}%
294 % Similarly a section-like command \marg{command} can be converted
295 % into an environment with explicit visibility scope with the command
296 % \cs{NewMultiaudienceSectionEnv}\penalty0\marg{environment}\marg{command}. For
297 % example, \texttt{Section} environment is defined as
298 % \begin{verbatim}
299 % \NewMultiaudienceSectionEnv{Section}{\section}
300 % \end{verbatim}
301 %
302 % \subsection{Combined audiences}
303 % \label{ug:combinations}
304 %
305 % Sometimes one wants to create a document for several audiences. You
306 % can do this using comma-separated lists in \cs{CurrentAudience}, for
307 % example,
308 % \begin{verbatim}
309 % \DefCurrentAudience{execs,admins}
310 % \end{verbatim}
311 %
312 %
313 % \emph{Important:} there should be no spaces in the definition. The
314 % definition |\DefCurrentAudience{execs, admins}| will \emph{not} work!
315 %
316 % The resulting audience is the union of the audiences in the
317 % definition. Thus a fragment is included if either:
318 % \begin{enumerate}
319 % \item The list of audiences for the fragment does not start with
320 % |-|, and at least one of the current audiences is mentioned in the
321 % list.
322 % \item The list of audiences for the fragment starts with |-|, and
323 % none of the current audiences is mentioned in the list.
324 % \end{enumerate}
325 % For example, suppose the current audience is |execs,admins|. Then
326 % the following is true:
327 % \begin{enumerate}
328 % \item |\showto{devs}{...}|---excluded.
329 % \item |\showto{devs,admins}{...}|---included.
330 % \item |\showto{-, devs}{...}|---included.
331 % \item |\showto{-, devs, admins}{...}|---excluded.
332 % \end{enumerate}
333 %
334 %
335 %\StopEventually{\clearpage}
336 %
337 % \clearpage
338 %
339 % \section{Implementation}
340 % \label{sec:implementation}
341 %
342 % \begin{macrocode}
343 %<*style>
344 % \end{macrocode}
345 %
346 %
347 %\subsection{Switches and defaults}
348 %\label{sec:switches}
349 %
350 % \begin{macro}{\CurrentAudience}
351 % The default for \cs{CurrentAudience}
352 % \begin{macrocode}
353 \providecommand*\CurrentAudience{default}
354 % \end{macrocode}
355 %
356 % \end{macro}
357 %
358 % \begin{macro}{\DefCurrentAudience}
359 % \changes{v1.03}{2015/08/02}{Added macro}
360 % A little sugar around \cs{def}:
361 % \begin{macrocode}
362 \def\DefCurrentAudience#1{\def\CurrentAudience{#1}}
363 % \end{macrocode}
364 %
365 % \end{macro}
366 %
367 % \begin{macro}{\if@MULTAU@shown}
368 % \changes{v1.01}{2015/07/11}{Renamed}
369 % The main switch
370 % \begin{macrocode}
371 \newif\if@MULTAU@shown
372 \@MULTAU@showntrue
373 % \end{macrocode}
374 %
375 % \end{macro}
376 %
377 % \begin{macro}{\if@MULTAU@include}
378 % Whether the current command is ``include'' or ``exclude'' type
379 % (i.e. whether it does \emph{not} start with ``-'')
380 % \begin{macrocode}
381 \newif\if@MULTAU@include
382 \@MULTAU@includetrue
383 % \end{macrocode}
384 %
385 % \end{macro}
386 %
387 %
388 %\subsection{Key-value interface}
389 %\label{sec:keyval}
390 %
391 % We use |xkeyval|
392 % \begin{macrocode}
393 \RequirePackage{xkeyval}
394 % \end{macrocode}
395 %
396 % \begin{macro}{\KV@MULTAU@-}
397 % Normally we evaluate visibility according to the following algorithm:
398 % \begin{enumerate}
399 % \item Set visibility to FALSE.
400 % \item If found current audience in the list, set visibility to
401 % TRUE.
402 % \end{enumerate}
403 % The presense of ``-'' keys inverts the algorithm:
404 % \begin{enumerate}
405 % \item Set visibility to TRUE.
406 % \item If found current audience in the list, set visibility to
407 % FALSE.
408 % \end{enumerate}
409 % \begin{macrocode}
410 \define@key{MULTAU}{-}[]{\@MULTAU@showntrue\@MULTAU@includefalse}
411 % \end{macrocode}
412 % \end{macro}
413 %
414 % \begin{macro}{\SetNewAudience}
415 % \changes{v1.04}{2021/10/02}{Added facility for a list of current
416 % audiences}
417 % Definition of a new audience. We create a new key that switches
418 % visibility on or off.
419 % \begin{macrocode}
420 \def\SetNewAudience#1{%
421 \define@key{MULTAU}{#1}[]{%
422 \def\@MULTAU@currkey{#1}%
423 \@for\@tempa:=\CurrentAudience \do{%
424 \ifx\@MULTAU@currkey\@tempa\relax
425 \if@MULTAU@include
426 \@MULTAU@showntrue
427 \else
428 \@MULTAU@shownfalse
429 \fi%
430 \fi%
431 }}}
432 % \end{macrocode}
433 %
434 % \end{macro}
435 %
436 %
437 %\subsection{Main command}
438 %\label{sec:main_command}
439 %
440 % \begin{macro}{\showto}
441 % \changes{v1.01}{2015/07/11}{Renamed}
442 % The macro \cs{showto} is the heart of the package. Note that we
443 % cannot put the inside into a group since we want it to be
444 % transparent for things like counters.
445 % \begin{macrocode}
446 \long\def\showto#1#2{\@MULTAU@shownfalse\@MULTAU@includetrue
447 \setkeys{MULTAU}{#1}%
448 \if@MULTAU@shown#2\fi
449 \@MULTAU@showntrue\@MULTAU@includetrue}
450 % \end{macrocode}
451 %
452 % \end{macro}
453 %
454 %
455 %
456 %\subsection{Main environment}
457 %\label{sec:main_env}
458 %
459 % We need the macros from the |environ| package
460 % \begin{macrocode}
461 \RequirePackage{environ}
462 % \end{macrocode}
463 %
464 %
465 % \begin{macro}{\shownto}
466 % \changes{v1.01}{2015/07/11}{Renamed}
467 % And the environment
468 % \begin{macrocode}
469 \NewEnviron{shownto}[1]{%
470 \@MULTAU@shownfalse\@MULTAU@includetrue
471 \setkeys{MULTAU}{#1}%
472 \if@MULTAU@shown\BODY\fi}{\@MULTAU@showntrue\@MULTAU@includetrue}
473 % \end{macrocode}
474 %
475 % \end{macro}
476 %
477 %
478 %
479 %\subsection{Extensions}
480 %\label{sec:extensions}
481 %
482 % \begin{macro}{\DefVisibilityCommand}
483 % Create a new visibility command
484 % \changes{v1.01}{2015/07/11}{Renamed}
485 % \begin{macrocode}
486 \def\DefMultiaudienceCommand#1#2{\long\def#1##1##2{\showto{##1}{#2{##2}}}}
487 % \end{macrocode}
488 %
489 % \end{macro}
490 %
491 % \begin{macro}{\Footnote}
492 % Special footnote command:
493 % \begin{macrocode}
494 \DefMultiaudienceCommand{\Footnote}{\footnote}
495 % \end{macrocode}
496 %
497 % \end{macro}
498 %
499 % \begin{macro}{\NewMultiaudienceSectionEnv2}
500 % \changes{v1.01}{2015/07/11}{Renamed}
501 % Create a new visibility section environment
502 % \begin{macrocode}
503 \def\NewMultiaudienceSectionEnv#1#2{%
504 \NewEnviron{#1}[1]{%
505 \@MULTAU@shownfalse\@MULTAU@includetrue
506 \setkeys{MULTAU}{##1}%
507 \if@MULTAU@shown\expandafter#2\BODY\fi}%
508 {\@MULTAU@showntrue\@MULTAU@includetrue}}
509 % \end{macrocode}
510 % \end{macro}
511 %
512 %
513 % \begin{macro}{Section}
514 % \begin{macro}{Subsection}
515 % \begin{macro}{Subsubsection}
516 % \begin{macro}{Paragraph}
517 % \begin{macro}{Subparagraph}
518 % A bunch of section-like commands
519 % \begin{macrocode}
520 \NewMultiaudienceSectionEnv{Section}{\section}
521 \NewMultiaudienceSectionEnv{Subsection}{\subsection}
522 \NewMultiaudienceSectionEnv{Subsubsection}{\subsubsection}
523 \NewMultiaudienceSectionEnv{Paragraph}{\paragraph}
524 \NewMultiaudienceSectionEnv{Subparagraph}{\subparagraph}
525 % \end{macrocode}
526 %
527 % \end{macro}
528 % \end{macro}
529 % \end{macro}
530 % \end{macro}
531 % \end{macro}
532 %
533 % \begin{macrocode}
534 %</style>
535 % \end{macrocode}
536 %\Finale
537 %\clearpage
538 %
539 %\PrintChanges
540 %\clearpage
541 %\PrintIndex
542 %
543 \endinput