Debian Codegraph @

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

raw
1 % \iffalse meta-comment
2 % Copyright (c) 2015 Jared Jennings <[email protected]>
3 %
4 % Permission is hereby granted, free of charge, to any person
5 % obtaining a copy of this software and associated documentation
6 % files (the "Software"), to deal in the Software without
7 % restriction, including without limitation the rights to use, copy,
8 % modify, merge, publish, distribute, sublicense, and/or sell copies
9 % of the Software, and to permit persons to whom the Software is
10 % furnished to do so, subject to the following conditions:
11 %
12 % The above copyright notice and this permission notice shall be
13 % included in all copies or substantial portions of the Software.
14 %
15 % THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
16 % EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
17 % MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
18 % NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
19 % BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
20 % ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
21 % CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22 % SOFTWARE.
23 % \fi
24 %
25 % ^^A We cannot \usepackage{cybercic}, because it is a horrible hack.
26 % ^^A Therefore we do not get \filedate and \fileversion for free.
27 % \def\filedate{2015/06/24}
28 % \def\fileversion{v2.1}
29 % \iffalse
30 %<package>\NeedsTeXFormat{LaTeX2e}
31 %<package>\ProvidesPackage{cybercic}
32 %<package> [2015/06/24 Fixed packaging issues]
33 %
34 %<*driver>
35 \documentclass{ltxdoc}
36
37 \usepackage{verbatim}
38
39
40
41 % Make PDF magic happen.
42 % Thanks, Patrick Joeckel:
43 % http://www.mpch-mainz.mpg.de/~joeckel/pdflatex/
44 % Note that I expect always to use pdflatex, not latex+dvipdf
45 \usepackage[bookmarks=true,bookmarksnumbered=true,breaklinks=true,pdftex]{hyperref}
46 \hypersetup{
47 colorlinks=false,
48 linkbordercolor={0.7 0.7 1.0}
49 }
50
51 \EnableCrossrefs
52 \RecordChanges
53 \CodelineIndex
54
55 \begin{document}
56 \DocInput{cybercic.dtx}
57 \end{document}
58 %</driver>
59 % \fi
60 %
61 % \CheckSum{0}
62 %
63 % \CharacterTable
64 % {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
65 % 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
66 % Digits \0\1\2\3\4\5\6\7\8\9
67 % Exclamation \! Double quote \" Hash (number) \#
68 % Dollar \$ Percent \% Ampersand \&
69 % Acute accent \' Left paren \( Right paren \)
70 % Asterisk \* Plus \+ Comma \,
71 % Minus \- Point \. Solidus \/
72 % Colon \: Semicolon \; Less than \<
73 % Equals \= Greater than \> Question mark \?
74 % Commercial at \@ Left bracket \[ Backslash \\
75 % Right bracket \] Circumflex \^ Underscore \_
76 % Grave accent \` Left brace \{ Vertical bar \|
77 % Right brace \} Tilde \~}
78 %
79 % \changes{v1.0}{2011/11/02}{Split off from iadoc}
80 % \changes{v1.1}{2012/06/07}{Made skiacic into a \LaTeX\ package}
81 % \changes{v1.2}{2012/12/17}{Renamed skiacic to iacic}
82 % \changes{v1.3}{2015/03/11}{Renamed iacic to cybercic; changes for suitability on CTAN}
83 % \changes{v2.0}{2015/03/21}{Bumped version to match \textsf{cyber}}
84 % \changes{v2.1}{2015/06/24}{Fixed packaging issues}
85 %
86 % \title{The \textsf{cybercic} package\thanks{This document corresponds to
87 % \textsf{cybercic}~\fileversion, dated~\filedate.}}
88 % \author{Jared Jennings \\ \texttt{[email protected]}}
89 %
90 % \maketitle
91 % \tableofcontents
92 % \clearpage
93 %
94 %
95 % \section{What's it for?}
96 %
97 % This package, when used in conjunction with \textsf{cyber}, adds IA control
98 % names to division names in the table of contents. (The \textsf{cic} stands
99 % for ``controls in contents.'' \emph{Division} means chapter, section,
100 % subsection, subsubsection, etc.)
101 %
102 % As an example, suppose you have a section in your document like this:
103 %
104 % \begin{verbatim}
105 % \section{Stuff about individual authentication}
106 %
107 % \documents{iacontrol}{IAIA-1} Bla, bla, bla...
108 % \end{verbatim}
109 %
110 % Without \textsf{cybercic}, this creates a line in your table of contents that
111 % says something like, ``3.2 Stuff about individual authentication ..... 34,''
112 % and a section heading in the body of the document, on (in our example) page
113 % 34, that says something like, ``3.2 Stuff about individual authentication.''
114 %
115 % When you add \textsf{cybercic}, the line in your table of contents will say,
116 % ``3.2 Stuff about individual authentication (IAIA-1) ... 34.'' The section
117 % head in the body of the document will stay the same.
118 %
119 %
120 % \section{How to use it}
121 %
122 % In the preamble of your document, write |\usepackage{cybercic}|. But! You must
123 % be careful where you write it. If you use \textsf{hyperref}, you must use
124 % \textsf{cybercic} \emph{after} \textsf{hyperref}. You must use
125 % \textsf{cybercic} after \textsf{cyber}, as well.
126 %
127 % \DescribeMacro{\Cybercontrolsincontentsenabledfalse}
128 %
129 % \DescribeMacro{\Cybercontrolsincontentsenabledtrue}
130 %
131 % If there is a part of your document wherein you do not want section titles in
132 % the table of contents changed, at the beginning of that part write
133 % |\Cybercontrolsincontentsenabledfalse|. When you want controls-in-contents
134 % re-enabled, write |\Cybercontrolsincontentsenabledtrue|.
135 %
136 %
137 % \section{Caveats}
138 %
139 % First and foremost, when you use this package, and you also use
140 % \textsf{hyperref} to make a PDF with bookmarks in it, you cannot put
141 % \emph{any} formatting in your section titles. This means you cannot write
142 % something like:
143 %
144 % \begin{verbatim}
145 % \section{My \emph{Awesome} Section}
146 % \section{The {\tt /usr/var/tmp} directory}
147 % \end{verbatim}
148 %
149 % You must content yourself with:
150 %
151 % \begin{verbatim}
152 % \section{My Awesome Section}
153 % \section{The /usr/var/tmp directory}
154 % \end{verbatim}
155 %
156 % This package is a horrible (but ingenious) hack. Do not use it unless you
157 % really, really need to. It may not play well with other packages.
158 %
159 % If a section spans multiple pages, and compliance posture tags (like
160 % |\documents| or |\implements|, see \textsf{cyber} documentation) are strewn
161 % throughout, running page heads containing section names will only show IA
162 % control names mentioned before the page began. Patches gratefully accepted.
163 %
164 %
165 % \section{Implementation}
166 %
167 % \StopEventually{}
168 %
169 % \begin{macrocode}
170 \makeatletter
171 % \end{macrocode}
172 %
173 % Given that we are using controlsincontents, sometimes it needs to be disabled
174 % for part of a document. The newif here is for that purpose.
175 % \begin{macro}{\Cybercontrolsincontentsenabledtrue}
176 % \begin{macro}{\Cybercontrolsincontentsenabledfalse}
177 % \begin{macrocode}
178 \newif\ifCybercontrolsincontentsenabled
179 \Cybercontrolsincontentsenabledtrue
180 % \end{macrocode}
181 % \end{macro}
182 % \end{macro}
183 %
184 % The word ``division'' here is a general term for a part, chapter, section,
185 % subsection, subsubsection, paragraph, or subparagraph.
186 %
187 % Every kind of division has an optional argument, what should show in the
188 % table of contents instead of the title shown in the text. Our strategy is to
189 % set that optional toc name to a reference to a macro. The macro is first
190 % defined to contain the original name of the section, but it can be redefined
191 % later in the document to tack text onto the end of it.
192 %
193 % \url{http://www.elektro.uni-miskolc.hu/~gati/references/latex/macro/tugpap1.pdf}
194 % introduces this sort of indirection.
195 %
196 % Only the last definition of the division's title macro that appeared in the
197 % document is expanded when the |.toc| file is written. So the table of
198 % contents then contains all the additions to the division's title as well as
199 % the title itself. Unfortunately, at the part of the document where the
200 % division title is typeset in the text, none of the redefinitions have
201 % happened yet, so only the title which shows in the TOC can be amended using
202 % this method.
203 %
204 % We need to name the macro that will contain each division's title. Each name
205 % must be unique, so we use the counters for different kinds of sections; but
206 % each name must also be a valid identifier, so instead of using numbers we use
207 % letters. (Alph bombs out after it gets to number 26, so Roman it is.)
208 % \begin{macrocode}
209 \newcommand \alphpart {pt\Roman{part}}
210 \ifdefined\chapter
211 \newcommand \alphchapter {\alphpart ch\Roman{chapter}}
212 \newcommand \alphsection {\alphchapter se\Roman{section}}
213 \else
214 \newcommand \alphsection {\alphpart se\Roman{section}}
215 \fi
216 \newcommand \alphsubsection {\alphsection su\Roman{subsection}}
217 \newcommand \alphsubsubsection {\alphsubsection ss\Roman{subsubsection}}
218 \newcommand \alphparagraph {\alphsubsubsection p\Roman{paragraph}}
219 \newcommand \alphsubparagraph {\alphparagraph sp\Roman{subparagraph}}
220 % \end{macrocode}
221
222 % Now we're going to replace |\@sect|. This macro is used for all divisions
223 % |\section| and smaller.
224 % \begin{macrocode}
225 \let\skia@orig@sect\@sect
226 \gdef\@sect#1#2#3#4#5#6[#7]#8{%
227 \ifCybercontrolsincontentsenabled
228 % \end{macrocode}
229 % \#1 is the kind of division, e.g. section or subparagraph. \#2 is the depth
230 % of this kind of division in the hierarchy (1 is a chapter, 2 is a
231 % section, etc)
232 % \begin{macrocode}
233 \ifnum #2>\c@tocdepth
234 % \end{macrocode}
235 % The kind of division we're starting is too detailed to show up in the
236 % table of contents. Just do the usual |@sect| thing. (Before this special
237 % case was written, any use of |\subsubsection| resulted in an
238 % |\inaccessible| error.)
239 % \begin{macrocode}
240 \skia@orig@sect{#1}{#2}{#3}{#4}{#5}{#6}[#7]{#8}
241 % \end{macrocode}
242 % A side effect of not redefining |\last@division| and |\last@divtitle| here
243 % as we do below is that any |\addtosectionname|s that happen will add to
244 % the name of the last-declared TOC-worthy division - which will be a
245 % larger division that contains this one.
246 %
247 % For example, assume |\setcounter{tocdepth}{1}|, i.e. only chapters are
248 % shown in the TOC. Now if we |\chapter{One}| |\section{Onedotone}|
249 % |\addtosectionname{Bla}|, Bla will be added to One, not onto Onedotone.
250 % \begin{macrocode}
251 \else
252 % \end{macrocode}
253 % This division will show up in the TOC. Prepare it to have text added
254 % onto its name there.
255 % Let's capture a unique name for the section being created:
256 % \begin{macrocode}
257 \edef\last@division{#1\csname alph#1\endcsname}
258 % \end{macrocode}
259 % (An example expansion would be paragraphptchseIsussIIp.)
260 % Now we construct a name for a macro which will contain the title of this
261 % section.
262 % \begin{macrocode}
263 \edef\last@divtitle{\csname titleof\last@division \endcsname}
264 \edef\last@divaddedto{\csname addedto\last@division \endcsname}
265 % \end{macrocode}
266 % Now we define that macro. The expandafter causes |\last@divtitle| to be
267 % expanded before the |\def|, so that we are not defining |\last@divtitle|, but
268 % the thing it expands to---in our example, we are defining
269 % |\titleofparagraphptchseIsussIIp|. Mind-bending, eh?
270 % \begin{macrocode}
271 \expandafter\def\last@divtitle{#7}
272 % \end{macrocode}
273 % Now we call the old |@sect|, giving |\last@divtitle| as the section title to
274 % use in the table of contents. But we don't want to expand it right now,
275 % because it would just expand to \#7. So we put a |\noexpand| first. But we
276 % don't want its value to be exactly ``|\last@divtitle|'', because that
277 % one gets redefined all the time, and only the last definition would be
278 % used in writing the toc file, so the name of every section in the toc
279 % would end up the same... This expansion stuff is a bit fiddly, isn't
280 % it? So instead of using |\last@divtitle|, as above, we have to write
281 % its expansion out here.
282 % \begin{macrocode}
283 \skia@orig@sect{#1}{#2}{#3}{#4}{#5}{#6}[\noexpand\csname titleof\last@division\endcsname]{#8}
284 \fi
285 \else
286 % \end{macrocode}
287 % If we're in this |else|, Cybercontrolsincontentsenabled is not true. Just do
288 % the usual section thing.
289 % \begin{macrocode}
290 \skia@orig@sect{#1}{#2}{#3}{#4}{#5}{#6}[#7]{#8}
291 \fi}
292 % \end{macrocode}
293 %
294 % And we need to add the same machinery to |\@chapter|---if it exists. (Some
295 % document classes do not define it.)
296 % \begin{macrocode}
297 \ifdefined\@chapter
298 \let\skia@orig@chapter\@chapter
299 \gdef\@chapter[#1]#2{%
300 \ifCybercontrolsincontentsenabled
301 \edef\last@division{chapter\alphchapter}
302 \edef\last@divtitle{\csname titleof\last@division \endcsname}
303 \edef\last@divaddedto{\csname addedto\last@division \endcsname}
304 \expandafter\def\last@divtitle{#1}
305 \skia@orig@chapter[\noexpand\csname titleof\last@division\endcsname]{#2}
306 \else
307 \skia@orig@chapter[#1]{#2}
308 \fi}
309 \fi % defined @chapter
310 % \end{macrocode}
311 %
312 %
313 % Fix PDF bookmarks by using the expansion of the title macro, not its name.
314 %
315 % When you use \textsf{hyperref} and you tell it to make PDF bookmarks, the
316 % bookmarks it writes to the PDF file have to have very normal sorts of names.
317 % I think you may get to use UTF-8, but you can't have any text formatting.
318 % The way hyperref makes sure of this is by temporarily defining all of the
319 % \LaTeX\ formatting macros you may want to use, like |\textsf|, to do nothing,
320 % so that they expand to their contents rather than some \TeX\ code that makes
321 % the formatting happen plus the contents, and then evaluating the line that's
322 % supposed to go in the table of contents (the optional argument to |\@section|
323 % or |\@chapter| which defaults to the first argument) expanding only those
324 % macros. As I recall. It's been six months since I figured it out.
325 %
326 % But we've set the section name as it should appear in the contents to a
327 % macro, and not a macro that \textsf{hyperref} is prepared for. So the PDF
328 % bookmark for section 1.2 which begins on page 4 says
329 % |1.2 \titleofsectionptchseI 4|
330 % instead of |1.2 My Cool Section (IAIA-1) 4|.
331 %
332 % Our hamfisted solution to this is to go ahead and fully expand the parameter.
333 % That means that the |\titleofsectionptchseI| macro is expanded, to ``My Cool
334 % Section (IAIA-1).'' But it also means that all of those guards that hyperref
335 % had to deal with what happens if I write
336 % |\section{My \emph{Awesome} Section}|
337 % are gone, and suddenly if there is any formatting in any section names, bad
338 % things happen. So this is the part of the code that necessitates that all
339 % division titles have no formatting in them at all.
340 %
341 % Most of this definition of addcontentsline comes from the hyperref package.
342 % For this to work properly, cyber must be loaded \emph{after} hyperref.
343 % \begin{macrocode}
344 \@ifpackageloaded{hyperref}{%
345 \gdef\addcontentsline#1#2#3{% toc extension, type, tag
346 \begingroup
347 \let\label\@gobble
348 \let\textlatin\@firstofone
349 \ifx\@currentHref\@empty
350 \Hy@Warning{%
351 No destination for bookmark of \string\addcontentsline,%
352 \MessageBreak destination is added%
353 }%
354 \phantomsection
355 \fi
356 \expandafter\ifx\csname toclevel@#2\endcsname\relax
357 \begingroup
358 \def\Hy@tempa{#1}%
359 \ifx\Hy@tempa\Hy@bookmarkstype
360 \Hy@WarningNoLine{bookmark level for unknown #2 defaults to 0}%
361 \else
362 \Hy@Info{bookmark level for unknown #2 defaults to 0}%
363 \fi
364 \endgroup
365 \expandafter\gdef\csname toclevel@#2\endcsname{0}%
366 \fi
367 \edef\Hy@toclevel{\csname toclevel@#2\endcsname}%
368 % \end{macrocode}
369 % Unlike hyperref, expand \#3 so we don't try to use a macro name as the
370 % title of the bookmark. But \#3 is likely a |\numberline{...}|, and at
371 % the time this is expanded, it seems that |\numberline| is some LaTeXy
372 % thing, not a hyperreffy thing, and hyperref complains about all the
373 % TeX code in the expansion of \#3. So we make sure that \numberline is
374 % going to just put the number in.
375 % \begin{macrocode}
376 \let\saved@numberline\numberline
377 \ifHy@bookmarksnumbered
378 \let\numberline\Hy@numberline
379 \else
380 \let\numberline\@gobble
381 \fi
382 \edef\Hy@expandedtag{#3}
383 \let\numberline\saved@numberline
384 % \end{macrocode}
385 % Now, about writing that bookmark.
386 % \begin{macrocode}
387 \Hy@writebookmark{\csname the#2\endcsname}%
388 {\Hy@expandedtag}%
389 {\@currentHref}%
390 {\Hy@toclevel}%
391 {#1}%
392 \ifHy@verbose
393 \typeout{pdftex: bookmark at \the\inputlineno:
394 {\csname the#2\endcsname}
395 {\Hy@expandedtag}
396 {\@currentHref}%
397 {\Hy@toclevel}%
398 {#1}%
399 }%
400 \fi
401 \addtocontents{#1}{%
402 \protect\contentsline{#2}{#3}{\thepage}{\@currentHref}%
403 }%
404 \endgroup
405 }
406 }
407
408 % \end{macrocode}
409 % That blank line just above seems to be necessary.
410 %
411 % To avoid restating IA controls in appended-to section names, we'll need a
412 % substring search function.
413 %
414 % From the substr package, version 1.2, 2009/10/20, copyright 2000, 2005, 2009
415 % Harald Harders, available from CTAN:
416 %
417 % ---
418 %
419 % expands the first and second argument with
420 % |\protected@edef| and calls \#3 with them:
421 % \begin{macrocode}
422 \newcommand\su@ExpandTwoArgs[3]{%
423 \protected@edef\su@SubString{#1}%
424 \protected@edef\su@String{#2}%
425 \expandafter\expandafter\expandafter#3%
426 \expandafter\expandafter\expandafter{%
427 \expandafter\su@SubString\expandafter
428 }\expandafter{\su@String}%
429 }
430 % \end{macrocode}
431 % tests if \#1 in \#2. If yes execute \#3, else \#4
432 % \begin{macrocode}
433 \newcommand*\IfSubStringInString[2]{%
434 \su@ExpandTwoArgs{#1}{#2}\su@IfSubStringInString
435 }
436 \newcommand*\su@IfSubStringInString[2]{%
437 \def\su@compare##1#1##2\@nil{%
438 \def\su@param{##2}%
439 \ifx\su@param\@empty
440 \expandafter\@secondoftwo
441 \else
442 \expandafter\@firstoftwo
443 \fi
444 }%
445 \su@compare#2\@nnil#1\@nil
446 }
447 % \end{macrocode}
448 %
449 % ---
450 %
451 % End substr package excerpt.
452 %
453 % Now, to append some text to the name of the section we're in, we just have to
454 % redefine the macro whose name is the value of |\last@divtitle|. In order to add
455 % to it without infinite recursion, we use |\edef|, which expands its body before
456 % defining. Again, rather than defining |\last@divtitle| itself, we want to
457 % define the macro it names. The expandafter does this.
458 %
459 % \begin{macrocode}
460 \def\addtosectionname#1{%
461 \def\skia@yes{yes}
462 \expandafter\ifx\last@divaddedto\skia@yes
463 \IfSubStringInString{#1}{\last@divtitle}{}{%
464 \expandafter\edef\last@divtitle{\last@divtitle , #1}%
465 }
466 \else
467 \expandafter\edef\last@divtitle{\last@divtitle ---#1}
468 \fi
469 \expandafter\def\last@divaddedto{yes}}
470
471 \makeatother
472 % \end{macrocode}
473 % \Finale