Debian Codegraph @

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

raw
1 % \iffalse meta-comment
2 %
3 % This file is part of the package fistrum for use with LaTeX2e.
4 %
5 % Function: Access to 150 paragraphs of the well known Lorem Ipsum dummy text.
6 %
7 % This program may be distributed and/or modified under the
8 % conditions of the LaTeX Project Public License, either version 1.3
9 % of this license or (at your option) any later version.
10 % The latest version of this license is in
11 % http://www.latex-project.org/lppl.txt
12 % and version 1.3 or later is part of all distributions of LaTeX
13 % version 2005/12/01 or later.
14 %
15 % Please send error reports and suggestions for improvements to
16 % https://github.com/daviddavo/fistrum
17 %
18 \def\fistrumversion{0.1}
19 \def\fistrumdate{2023-02-28}
20 %<*driver>
21 \ProvidesFile{fistrum.dtx}%
22 [\fistrumdate\space v\fistrumversion\space
23 Por la gloria de mi madre, ese pedazo de texto de ejemplo.]
24 \documentclass{l3doc}
25 \usepackage{xcolor}
26 \usepackage{booktabs}
27 \usepackage{tabularx}
28 \usepackage{enumitem}
29 \usepackage{tikz}
30 \usetikzlibrary{positioning}
31 \usepackage[a4paper,
32 top=2cm, left=8.8cm, right=2cm, bottom=3cm,
33 marginparwidth=6.3cm, marginparsep=.5cm,
34 ]{geometry}
35 \newlength\fullmargin
36 \setlength\fullmargin\marginparwidth
37 \addtolength\fullmargin\marginparsep
38 \usepackage{mdframed}
39 \mdfdefinestyle{expl}{%
40 backgroundcolor=black!5!white,
41 linewidth=0pt,
42 middlelinewidth=0pt
43 }
44 \newmdenv[style=expl]{explbox}
45
46 \usepackage{fistrum,multicol}
47 \usepackage{multirow}
48 \usepackage[latin, spanish, es-noshorthands]{babel}
49 \usepackage[useregional]{datetime2}
50 \makeatletter
51 \newcommand\@subtitle{}
52 \newcommand\subtitle[1]{%
53 \renewcommand\@subtitle{#1}}
54 \renewcommand\maketitle[1]{%
55 \noindent
56 \hspace{-\fullmargin}%
57 \begin{minipage}{\textwidth+\fullmargin}
58 \renewcommand\thefootnote{\fnsymbol{footnote}}
59 \let\thanks\footnote
60 {
61 \centering
62 {\LARGE \@title}\\[.8\baselineskip]
63 {\LARGE \@subtitle}\\[2\baselineskip]
64 {\Large \@author}\\[\baselineskip]
65 {\Large \@date}\\[\baselineskip]
66 }
67 \ifx\\#1\\\else
68 \begin{multicols}{2}[%
69 \subsection*{\hfill\abstractname\hfill\null}]
70 \setlength{\columnsep}{.5cm}%
71 #1
72 \end{multicols}
73 \fi
74 \end{minipage}}
75 \makeatother
76 \newenvironment{wide}
77 {\hspace{-.75\fullmargin}%
78 \begin{minipage}{\textwidth+.75\fullmargin}}
79 {\end{minipage}}
80 \newcommand\opt[1]{\textsf{#1}} % l3doc does not have some markup for package options...
81 \newcommand\fist{\emph{Lorem fistrum\ldots}}
82 \renewcommand\topfraction{.85}
83 \renewcommand\textfraction{.15}
84 \renewcommand\floatpagefraction{.85}
85 \emergencystretch 2em
86 \newcommand\secref[1]{(see section~\ref{#1})}
87 \usepackage{hyperref}
88 \def\ghissue#1{%
89 \texttt{\##1}\footnote{%
90 \url{https://github.com/daviddavo/fistrum/issues/#1}}}
91 \begin{document}
92 \DocInput{fistrum.dtx}
93 \end{document}
94 %</driver>
95 %<*package>
96 \NeedsTeXFormat{LaTeX2e}
97 \RequirePackage{l3keys2e}
98 \@ifundefined{NewDocumentCommand}
99 {\RequirePackage{xparse}}{}
100 \ProvidesExplPackage {fistrum} {\fistrumdate} {\fistrumversion}
101 {150 paragraphs of Lorem Fistrum dummy text}
102 %</package>
103 % \fi
104 %
105 % \title{\pkg{fistrum}}
106 % \subtitle{Access to 150 paragraphs of Lorem Fistrum very dummy
107 % text\thanks{Version: \fistrumversion}^^A
108 % \thanks{Basado en \href{https://chiquitoipsum.com}{Chiquito Ipsum} de
109 % Isabel Nieto, Carlos A. Hernández y Gauss Multimedia}.
110 % }
111 % \author{David Davó\thanks{[email protected]}}
112 % \date{\DTMdate{2023-02-28}}
113 % \RecordChanges
114 % \changes{v0.1}{Feb 2023}{First release}
115 % \maketitle{\pkg{fistrum} es un paquete de \LaTeX{} derivado de \pkg{lipsum} que produce texto de ejemplo
116 % para usarlo en documentos y ejemplos. Los párrafos se han tomado con permiso de
117 % \url{https://www.chiquitoipsum.com/}.
118 %
119 % Por favor, si encuentras un bug, alguna errata o tienes alguna sugerencia
120 % abre un \textit{issue} en
121 % \url{https://github.com/daviddavo/fistrum}.}
122 %
123 % \begin{documentation}
124 %
125 % \section{Al ataquerl}
126 %
127 % \textbf{Nota: La documentación es una copia de la de lipsum, pueden haber quedado erratas}
128 %
129 % To load the package, write
130 % \begin{verbatim}
131 % \usepackage{fistrum}
132 % \end{verbatim}
133 % in the preamble of your document. Probably the most important macro
134 % provided by this package is \DescribeMacro{\fistrum}\cs{fistrum}, which
135 % typesets the \emph{Lorem fistrum} paragraphs. The first optional
136 % argument allows to specify the range of the paragraphs. For example,
137 % \verb|\fistrum[4-57]| typesets the paragraphs 4 to 57 and accordingly,
138 % \verb|\fistrum[23]| typesets the 23\textsuperscript{rd} paragraph.
139 % Using \cs{fistrum} without its optional argument typesets the
140 % paragraphs 1--7 of \fist
141 %
142 % As of version 2.0, \cs{fistrum} has a second optional argument which allows
143 % selecting a range of sentences from the paragraphs. To get the sentences
144 % four to eight from paragraphs three to nine, use |\fistrum[3-9][4-8]|.
145 % The sentences are counted from the first sentence of the first selected
146 % paragraph. In the previous example, sentence number~1 is the first
147 % sentence of paragraph number~3.
148 %
149 % \section{Usage}
150 %
151 % \pkg{fistrum} was intended to quickly provide a way to fill a page or two to
152 % analyze the page
153 % layout\footnote{\url{https://groups.google.com/d/topic/de.comp.text.tex/oPeLOjkrLfk}}.
154 % While it has grown in the meanwhile and now provides some more advanced
155 % features, it still is only intended to quickly provide text. If you want more
156 % features, look at the \pkg{blindtext}-package.
157 %
158 % \subsection{Package Options}
159 % \label{sec:pkg-opt}
160 %
161 % \pkg{fistrum} outputs a range of paragraphs taken from the \fist\ dummy
162 % text. The package options control mainly the behaviour of the
163 % \cs{fistrum} and \cs{unpackfistrum} commands, and can be set at
164 % load-time with \cs{usepackage}|[|\meta{option}|]{fistrum}|, or later in
165 % the document by using \cs{setfistrum}|{|\meta{option}|}|.
166 %
167 % \begingroup
168 % \RenewDocumentCommand \item { r[] e= d() }
169 % {\par\medskip\noindent\llap
170 % {\smash{\begin{tabular}{@{}l@{}}\toprule
171 % \opt{#1}\\\bottomrule\end{tabular}}~~}%^^A
172 % \IfValueT{#2}{=~~\!\meta{#2}\hfill
173 % \IfValueT{#3}{\quad(default: \texttt{#3})}\null
174 % \newline}\ignorespaces}
175 %
176 % \item[nopar]={boolean}(false)
177 % Changes the initial default separator between each paragraph of
178 % \cs{fistrum} from \cs{par} to \cs{space}, and the other way around
179 % for \cs{fistrum*}.
180 % \item[text]={name}(fistrum-es)
181 % Selects the dummy text \meta{name} that is used by \cs{fistrum} and
182 % \cs{unpackfistrum} \secref{sec:other-texts}.
183 % \item[language]={lang}(latin)
184 % Sets the language to be used by \cs{fistrum} to typeset the currently
185 % active dummy text \secref{sec:hyphenation}. Changing the dummy text
186 % with the \opt{text} option will also change the current
187 % \opt{language}.
188 % \item[auto-lang]={boolean}(true)
189 % Turns on/off automatic language switching. This changed since
190 % version 2.3, in which this option (didn't exist thus) was |false| by
191 % default. See section~\ref{sec:hyphenation} for more details.
192 % \item[default-range]={p_i\texttt{-}p_f}(1-7)
193 % Sets the default range of paragraphs produced by \cs{fistrum} when no
194 % optional argument is provided. The value to \opt{default-range}
195 % obeys the \meta{range} syntax described in
196 % section~\ref{sec:range-syntax}. If no value is given to
197 % \opt{default-range} (that is, \cs{setfistrum}|{default-range}|), then
198 % the default is reset to |1-7|.
199 %
200 % \endgroup
201 %
202 % \medskip
203 %
204 % Besides these options, there are still ones that can be passed to the
205 % package to influence the paragraph and sentence separators and other
206 % such things. These options are detailed in
207 % section~\ref{sec:separators}.
208 %
209 %^^A Besides the listed options, there are still options that can be
210 %^^A passed to the package to influence the paragraph and sentence
211 %^^A separators and other things like that. The options for paragraphs
212 %^^A are:
213 %^^A \AddToHookNext{env/multicols/before}
214 %^^A {\setlength{\multicolsep}{0.5\multicolsep}}
215 %^^A \begin{multicols}{2}
216 %^^A \ttfamily \setlist{nosep}
217 %^^A \begin{itemize}
218 %^^A \item par-before
219 %^^A \item par-begin
220 %^^A \item par-sep
221 %^^A \item par-end
222 %^^A \item par-after
223 %^^A \end{itemize}
224 %^^A \begin{itemize}
225 %^^A \item par-before*
226 %^^A \item par-begin*
227 %^^A \item par-sep*
228 %^^A \item par-end*
229 %^^A \item par-after*
230 %^^A \end{itemize}
231 %^^A \end{multicols}
232 %^^A and for sentences, the same group with |sentence| instead of |par|
233 %^^A in their name. These options are detailed in
234 %^^A section~\ref{sec:separators}.
235 %
236 % \subsection{User Commands}
237 %
238 % \begin{function}{\fistrum}
239 % \begin{syntax}
240 % \cs{fistrum}\meta{*}\oarg{par range}\oarg{sentence range}
241 % \end{syntax}
242 % \cs{fistrum} outputs the \meta{par range} from the
243 % currently active dummy text. If \meta{par range} is not given
244 % or is empty, the \opt{default-range} (initially |1-7|) is output.
245 % ^^A
246 % If a \meta{sentence range} is given, the selected paragraphs are
247 % split into sentences, numbered starting from~1, and the specified
248 % range of sentences is taken out from those paragraphs.
249 % ^^A
250 % If the \meta{*} version is used, a different set of separators is
251 % inserted around the paragraphs or sentences.
252 %
253 % \cs{fistrum} changes the active language to that of the dummy text
254 % for typesetting, so the proper hyphenation patterns are used.
255 % See section~\ref{sec:hyphenation}.
256 % ^^A
257 % Section~\ref{sec:range-syntax} explains the syntax of ranges, and
258 % section~\ref{sec:separators} explains the separators added around
259 % the pieces of text.
260 % \end{function}
261 %
262 % \begin{function}{\unpackfistrum,\fistrumexp}
263 % \begin{syntax}
264 % \cs{unpackfistrum}\meta{*}\oarg{par range}\oarg{sentence range}
265 % \ldots
266 % \cs{fistrumexp}
267 % \end{syntax}
268 % \cs{unpackfistrum} selects the paragraphs and/or sentences exactly as
269 % described for \cs{fistrum}, but instead of outputting them, it saves
270 % the selected text in the \cs{fistrumexp} macro. Additionally,
271 % \cs{unpackfistrum} \ldots\cs{fistrumexp} is not completely equivalent
272 % to \cs{fistrum} because it doesn't change languages as \cs{fistrum}
273 % does.
274 % \end{function}
275 %
276 % \begin{function}{\setfistrum}
277 % \begin{syntax}
278 % \cs{setfistrum}\Arg{key-val list}
279 % \end{syntax}
280 % Applies the \meta{key-val list} of options to the package. The
281 % options are described in section~\ref{sec:pkg-opt} and in
282 % section~\ref{sec:separators}.
283 % \end{function}
284 %
285 % \subsection{Other commands}
286 %
287 % These commands exist for necessity or backwards comatibility, and
288 % should normally not be needed in user documents.
289 %
290 % \begin{function}{\SetFistrumText}
291 % \begin{syntax}
292 % \cs{SetFistrumDefault}\Arg{name}
293 % \end{syntax}
294 % Loads the dummy text \meta{name} \secref{sec:other-texts}.
295 % This command does the same as option \opt{text}, but it is
296 % kept for backwards compatibility.
297 % \end{function}
298 %
299 % \begin{function}{\SetFistrumDefault}
300 % \begin{syntax}
301 % \cs{SetFistrumDefault}\Arg{range}
302 % \end{syntax}
303 % Sets the default range for \cs{fistrum} and \cs{unpackfistrum}.
304 % This command does the same as option \opt{default-range}, but it is
305 % kept for backwards compatibility.
306 % \end{function}
307 %
308 % \section{General remarks on behaviour}
309 %
310 % Here are some topics that are general considerations about the
311 % behaviour of \pkg{fistrum} and its commands. These are technicalities
312 % that most end users don't care too much about, unless you are trying
313 % to do something beyond the usual ``print me some dummy text''.
314 %
315 % \subsection{Syntax of paragraph and sentence ranges}
316 % \label{sec:range-syntax}
317 %
318 % A \meta{range} argument can either be blank, a single integer, or a
319 % proper integer range. If the \meta{range} argument is blank, the
320 % commands behave as if the argument was not given at all. For example,
321 % |\fistrum[]| behaves exaclty like |\fistrum| and outputs the default
322 % paragraph range. Note that |\fistrum[][2-5]| does \textbf{not} behave
323 % as |\fistrum[2-5]|, but behaves as |\fistrum[1-7][2-5]| (assuming
324 % |default=range=1-7|), because the default value is then taken for the
325 % first argument. If the \meta{range} argument is an integer, then only
326 % a single paragraph/sentence is selected.
327 %
328 % If the argument contains a |-| (\textsc{ascii}~45), it is interpreted
329 % as a \emph{proper} range \meta{n_i}|-|\meta{n_f}. In a proper range,
330 % if \meta{n_i} is blank, it is taken to be the start of the possible
331 % range, and in the same way, if \meta{n_f} is empty it is taken to be
332 % the end of the possible range. That is, |\fistrum[-9]| is the same as
333 % |\fistrum[1-9]|, and |\fistrum[5-]| is the same (assuming the standard
334 % 150-paragraph dummy text) as |\fistrum[5-150]|, and similarly,
335 % |\fistrum[-]| is the same as |\fistrum[1-150]|.
336 %
337 % Only one |-| is allowed in a range, so if more than one |-| is given,
338 % an error is raised and no paragraphs/sentences are output. No
339 % paragraphs or sentences will be output also in case one of the ranges
340 % is reversed, so |\fistrum[2-1]| returns no paragraphs, as does
341 % |\fistrum[][2-1]| output no sentences, for example. Note that
342 % ``returning no paragraphs/sentences'' is not ``the output is empty'':
343 % that is mostly true, except that the |-before| and |-after| separators
344 % are still output \secref{sec:separators}.
345 %
346 % Finally, if a range spans more paragraphs or sentences than what the
347 % dummy text actually provides, the range is truncated so that it fits
348 % the available text. If the range in the argument does not intersect
349 % with the range provided by the dummy text, no paragraphs or sentences
350 % are output.
351 %
352 % \subsection{Hyphenation patterns}
353 % \label{sec:hyphenation}
354 %
355 % Since version~2.4, the command \cs{fistrum} automatically changes the
356 % hyphenation patterns when typesetting a dummy text, so that
357 % line-breaking looks better \secref{sec:foreword2.4}. This feature is
358 % on by default, so if you need the old behaviour you have to explicitly
359 % disable automatic language switching with
360 % |\setfistrum{auto-lang=false}|.
361 %
362 % The language is defined individually for each dummy text
363 % \secref{sec:other-texts}, but you may change it for the current dummy
364 % text by using |\setfistrum{language=|\meta{lang}|}|. If you load
365 % another dummy text (for example with the \opt{text} option), then the
366 % option \opt{language} is also changed according to the dummy text
367 % loaded \secref{sec:other-texts}.
368 %
369 % \subsection{Paragraph and sentence separators}
370 % \label{sec:separators}
371 %
372 % As may be clear by now, \pkg{fistrum} has two modes of operation:
373 % sentence output, and paragraph output, selected by providing or not
374 % providing the second optional argument to \cs{fistrum}. In each mode,
375 % the dummy text is separated into chunks (paragraphs or sentences),
376 % which are counted, and then output accordingly.
377 %
378 % When \cs{fistrum} (or \cs{unpackfistrum}) is used with a single (or no)
379 % optional argument, then a range of paragraphs is output, along with
380 % some ``separators'' (in the lack of a better name) between paragraphs,
381 % around each paragraph, and before and after the whole output.
382 % A schematic (very colorful, because I couldn't find a better visual)
383 % representation of the output is:
384 %
385 % \begin{function}{
386 % par-before,
387 % par-begin,
388 % par-sep,
389 % par-end,
390 % par-after,
391 % sentence-before,
392 % sentence-begin,
393 % sentence-sep,
394 % sentence-end,
395 % sentence-after,
396 % }
397 % \noindent
398 % \begin{tikzpicture}[x=0.703cm,
399 % item/.style={
400 % draw,
401 % rounded corners=2mm,
402 % minimum width=2.2cm,
403 % execute at begin node=\strut,
404 % rotate=54,
405 % font=\footnotesize,
406 % },
407 % ]
408 % \def\sep#1{\texttt{par-\textbf{#1}}\null}
409 % \node [item,fill=red!40 ] at (0 ,0) {\sep{before}};
410 % \node [item,fill=red!20 ] at (1 ,0) {\sep{begin }};
411 % \node [item,fill=red!20 ] at (2 ,0) {\meta{paragraph}};
412 % \node [item,fill=red!20 ] at (3 ,0) {\sep{end \ }};
413 % \node [item,shading=axis,left color=red!30,right color=green!30,
414 % shading angle=54] at (4 ,0) {\sep{sep \ }};
415 % \node [item,fill=green!20] at (5 ,0) {\sep{begin }};
416 % \node [item,fill=green!20] at (6 ,0) {\meta{paragraph}};
417 % \node [item,fill=green!20] at (7 ,0) {\sep{end \ }};
418 % \node [item,shading=axis,left color=green!30,right color=blue!30,
419 % shading angle=54] at (8 ,0) {\sep{sep \ }};
420 % \node [item,fill=blue!20 ] at (9 ,0) {\sep{begin }};
421 % \node [item,fill=blue!20 ] at (10,0) {\meta{paragraph}};
422 % \node [item,fill=blue!20 ] at (11,0) {\sep{end \ }};
423 % \node [item,fill=blue!40 ] at (12,0) {\sep{after\ }};
424 % \end{tikzpicture}
425 %
426 % When \cs{fistrum} is called, the first thing it outputs is the
427 % \opt{par-before} tokens. These tokens are output unconditionally,
428 % regardless of how many (if any) paragraph is output.
429 %
430 % Then, before each paragraph in the range, \cs{fistrum} outputs the
431 % \opt{par-begin} tokens, and then the actual text of the
432 % \meta{paragraph}, and then the \opt{par-end} tokens. These tokens are
433 % output conditionally, if the paragraph text is output. If more than
434 % one paragraph is output, then the \opt{par-sep} tokens are inserted
435 % between the \opt{par-end} of one paragraph and the \opt{par-begin} of
436 % the paragraph that follows.
437 %
438 % \end{function}
439 %
440 % Finally, at the end, the \opt{par-after} tokens are inserted
441 % unconditionally at the end, same as for \opt{par-before}.
442 %
443 % As mentioned before, in case of an error parsing the range, the output
444 % will be no paragraphs, but the \opt{par-before} and \opt{par-after}
445 % tokens are still output.
446 %
447 % The explanation above is equally valid for the starred variants. If
448 % \cs{fistrum}|*| is used, the \opt{par-before*} tokens are
449 % inserted, and so on. It is also true for sentences (starred or
450 % otherwise), replacing |par| in the option names by |sentence|, so when
451 % you use, for example, |\fistrum[][1-9]|, the \opt{sentence-before}
452 % tokens will be unconditionally inserted, and so on.
453 %
454 % Note that, when \cs{fistrum} is used in sentence-mode (for example,
455 % with |\fistrum[1-3][1-9]|), only the |sentence-...| tokens are inserted
456 % in the output, regardless of how many paragraphs those sentences were
457 % collected from. In the same way, if paragraph-mode is being used, only
458 % |par-...| tokens are inserted.
459 %
460 % \subsubsection{Deprecated command-based syntax}
461 %
462 % Older versions of \pkg{fistrum} (from 2.0 to 2.3) provided~10 CamelCase
463 % commands for changing the separators, but the syntax was rather
464 % cumbersome to use, so the keyval syntax presented thus far was
465 % introduced in the hopes of making things a bit easier. The old
466 % commands will still exist for some time in the package, but with a
467 % deprecation warning. Changing to the keyval syntax is advised, so
468 % here is a correspondence table between the old and new syntaxes:
469 %
470 % \begin{center}
471 % \ttfamily \makeatletter
472 % \definecolor{a}{HTML}{E0211A}\colorlet{a}{a!60!black}
473 % \definecolor{b}{HTML}{5970D5}\colorlet{b}{b!60!black}
474 % \protected@edef\x#1#2{\string\SetFistrum
475 % {\color{a}#1}List{\color{b}#2}}%
476 % \def\y#1#2{{\color{a}#1}-{\color{b}#2}}
477 % \begin{tabular}{@{}ll@{}}
478 % \toprule
479 % \textrm{Old command} & \textrm{New key name} \\
480 % \midrule
481 % \x{Par}{Start} & \y{par}{before} \\
482 % \x{Par}{ItemStart} & \y{par}{begin} \\
483 % \x{Par}{ItemSeparator} & \y{par}{sep} \\
484 % \x{Par}{ItemEnd} & \y{par}{end} \\
485 % \x{Par}{End} & \y{par}{after} \\
486 % \x{Sentence}{Start} & \y{sentence}{before} \\
487 % \x{Sentence}{ItemStart} & \y{sentence}{begin} \\
488 % \x{Sentence}{ItemSeparator} & \y{sentence}{sep} \\
489 % \x{Sentence}{ItemEnd} & \y{sentence}{end} \\
490 % \x{Sentence}{End} & \y{sentence}{after} \\
491 % \bottomrule
492 % \end{tabular}
493 % \end{center}
494 %
495 % Additionally, the command-based interface provided shortcuts
496 % |\SetFistrum|\meta{Thing}|List|(|Item|)|Surrounders|, which are
497 % equivalent to just using the commands
498 % |\SetFistrum|\meta{Thing}|List|(|Item|)|Start| then |\...End|. These
499 % don't provide any functionality, other than requiring a little less
500 % typing, so no key-val alternative was implemented.
501 % The |\...|\meta{Thing}|...Surrounders| commands should be replaced by
502 % \meta{thing}|-before| and \meta{thing}|-after|, and the
503 % |\...|\meta{Thing}|...ItemSurrounders| commands should be replaced by
504 % \meta{thing}|-begin| and \meta{thing}|-end|, as in the correspondence
505 % table below:
506 %
507 % \begin{center}
508 % \ttfamily \makeatletter
509 % \definecolor{a}{HTML}{E0211A}\colorlet{a}{a!60!black}
510 % \definecolor{b}{HTML}{5970D5}\colorlet{b}{b!60!black}
511 % \protected@edef\x#1#2{\string\SetFistrum
512 % {\color{a}#1}List{\color{b}#2}Surrounders%^^A
513 % \kern .5\tabcolsep \xleaders\hbox{\vrule
514 % width 2pt height \dimexpr .5ex+.4pt\relax depth -.5ex
515 % \kern 2pt}%
516 % \hskip 0pt plus 1filll \kern -.5\tabcolsep
517 % \raise.5ex\rlap{\kern.5\tabcolsep
518 % \vrule width \tabcolsep height 0.4pt depth 0pt
519 % \kern-0.5\tabcolsep
520 % \smash{\vrule depth \normalbaselineskip width 0.4pt
521 % \raise-\normalbaselineskip
522 % \hbox{\vrule width .5\tabcolsep height 0.4pt depth 0pt}}}}%
523 % \def\y#1#2{{\color{a}#1}-{\color{b}#2}}
524 % \begin{tabular}{@{}ll@{}}
525 % \toprule
526 % \textrm{Old command} & \textrm{New key names} \\
527 % \midrule
528 % \x{Par}{} & \y{par}{}before \\
529 % & \y{par}{}after \\
530 % \x{Par}{Item} & \y{par}{begin} \\
531 % & \y{par}{end} \\
532 % \x{Sentence}{} & \y{sentence}{}before \\
533 % & \y{sentence}{}after \\
534 % \x{Sentence}{Item} & \y{sentence}{begin} \\
535 % & \y{sentence}{end} \\
536 % \bottomrule
537 % \end{tabular}
538 % \end{center}
539 %
540 % \section{Loading and defining dummy texts}
541 % \label{sec:other-texts}
542 %
543 % Starting with \pkg{fistrum} v2.2, a simple interface is provided to
544 % define and load other texts for the output of \cs{fistrum} and friends.
545 % This interface can, for example, be used to implement dummy texts in
546 % different languages without re-coding the logic implemented by
547 % \pkg{fistrum}.
548 %
549 % \begin{function}{\NewFistrumPar}
550 % \begin{syntax}
551 % \cs{NewFistrumPar}\Arg{paragraph}
552 % \end{syntax}
553 % In order to provide a new text that will be used by \pkg{fistrum},
554 % define the text by using a set of \cs{NewFistrumPar}\Arg{paragraph}
555 % commands in a file with the ending |.ftd.tex| (|ftd| means
556 % \emph{fistrum text definition}\footnotemark{}) to a location where
557 % your \TeX{} system will find it. The \meta{paragraph}-argument is a
558 % single paragraph of the new text. Thus, the first occurence of
559 % \cs{NewFistrumPar} defines the first paragraph, the second occurence
560 % the second paragraph and so on.
561 % \end{function}
562 % \footnotetext{To avoid name clashes with files using general languages
563 % as names, I chose to introduce the |.ftd.tex| file ending. I did not
564 % find a file with this ending in my |texmf|-tree, so I guess it is
565 % safe.}
566 %
567 % \begin{function}{\SetFistrumLanguage}
568 % \begin{syntax}
569 % \cs{SetFistrumLanguage}\Arg{lang}
570 % \end{syntax}
571 % Additionally, tell \pkg{fistrum} the language of the dummy text using
572 % \cs{SetFistrumLanguage}\Arg{lang} somewhere in the |.ftd.tex| file.
573 % \end{function}
574 %
575 % \medskip
576 %
577 % To specify the new text as output for \cs{fistrum} and friends, use
578 % \cs{setfistrum}|{|\opt{text}|=|\meta{name}|}|, where \meta{name} is the
579 % name of the file without the ending |.ftd.tex|, as given in the table
580 % below. When a new dummy text is loaded, the previous one is cleared,
581 % and the language is changed as well, according to the table.
582 %
583 % \begin{table}[ht]
584 % \begin{wide}
585 % \begin{tabularx}{\textwidth}{lllX}
586 % \toprule
587 % File (\texttt{.ftd.tex}) & Language & Source & Description \\
588 % \midrule
589 % \texttt{fistrum-la} & Latin
590 % & Chiquito
591 % & Contiene el texto \emph{Lorem fistrum} tras seleccionar la opción
592 % latín en \url{https://www.chiquitoipsum.com/}. \\
593 % \texttt{fistrum-es} & Spanish
594 % & Chiquito
595 % & Contiene el texto \emph{Lorem fistrum} tras seleccionar la opción
596 % fistrum en \url{https://www.chiquitoipsum.com/}. \\
597 % \bottomrule
598 % \end{tabularx}
599 % \end{wide}
600 % \end{table}
601 %
602 % \subsection{Guidelines on providing new dummy texts}
603 %
604 % \cs{SetFistrumText} more or less just uses an \cs{input} or, to be more
605 % precise, the \LaTeX3-variant \cs{file_input:n}, to load the |.ftd.tex|
606 % file. This means, that the file is not necessarily loaded in the
607 % preamble of the document and thus the contents of the file underlie
608 % the respective restrictions.
609 %
610 % Should you want a new dummy text, create an issue in the GitHub
611 % repository\footnote{\url{https://github.com/daviddavo/fistrum}}
612 % with the source for the dummy text.
613 %
614 % Should you prefer to distribute the dummy text as a separate package,
615 % make sure that the text follows the layout of \pkg{fistrum}'s dummy
616 % texts, so that everything works correctly. The dummy text definition
617 % file should contain a line with \cs{SetFistrumLanguage}, and then as
618 % many \cs{NewFistrumPar} entries as there are paragraphs in the dummy
619 % text. Make sure that the file has the |.ftd.tex| extension, and
620 % everything should work smoothly.
621 %
622 % \end{documentation}
623 %
624 % \clearpage
625 % \newgeometry{left=5cm,right=2cm}
626 %
627 % \begin{implementation}
628 %
629 % \section{\pkg{fistrum} Implementation}
630 %
631 % \begin{macrocode}
632 %<*package>
633 %<@@=fistrum>
634 % \end{macrocode}
635 %
636 % \subsection{Variables}
637 %
638 % \begin{variable}{\g_@@_par_int}
639 % Stores the number of paragraphs in the current text.
640 % \begin{macrocode}
641 \int_new:N \g_@@_par_int
642 % \end{macrocode}
643 % \end{variable}
644 %
645 % \begin{variable}{\g_@@_language_tl}
646 % Stores the language of the dummy text for hyphenation patterns.
647 % \begin{macrocode}
648 \tl_new:N \g_@@_language_tl
649 % \end{macrocode}
650 % \end{variable}
651 %
652 % \begin{variable}[int]{\g_fistrum_default_range_tl}
653 % The default range for fistrum paragraphs.
654 % \begin{macrocode}
655 \tl_new:N \g_fistrum_default_range_tl
656 % \end{macrocode}
657 % \end{variable}
658 %
659 % \begin{variable}{\l_@@_output_tl}
660 % This variables is used to store the token list containing the
661 % selected output.
662 % \begin{macrocode}
663 \tl_new:N \l_@@_output_tl
664 % \end{macrocode}
665 % \end{variable}
666 %
667 % \begin{variable}{\g_@@_text_str}
668 % Holds the current text loaded for the output of \cs{fistrum} and
669 % friends. Used to avoid loading the same text definition if it is
670 % already used.
671 % \begin{macrocode}
672 \str_new:N \g_@@_text_str
673 % \end{macrocode}
674 % \end{variable}
675 %
676 % \begin{variable}{\l_@@_sep_set_str}
677 % Holds the name of the active separator token set. By default it is
678 % empty to use the default separator set (empty).
679 % \begin{macrocode}
680 \str_new:N \l_@@_sep_set_str
681 % \end{macrocode}
682 % \end{variable}
683 %
684 % \begin{variable}{\l_@@_autolang_bool}
685 % Boolean whether to change hyphenation patterns according to the
686 % dummy text language.
687 % \begin{macrocode}
688 \bool_new:N \l_@@_autolang_bool
689 % \end{macrocode}
690 % \end{variable}
691 %
692 % \begin{variable}{\q_@@_mark,\s_@@}
693 % Quark and scan mark used throughout the package.
694 % \begin{macrocode}
695 \quark_new:N \q_@@_mark
696 \scan_new:N \s_@@
697 % \end{macrocode}
698 % \end{variable}
699 %
700 % \begin{variable}{\l_@@_tmpa_str,\l_@@_a_int,\l_@@_b_int}
701 % Scratch variables.
702 % \begin{macrocode}
703 \str_new:N \l_@@_tmpa_str
704 \int_new:N \l_@@_a_int
705 \int_new:N \l_@@_b_int
706 % \end{macrocode}
707 % \end{variable}
708 %
709 % \begin{macro}{\@@_tmp:w}
710 % Scratch macro.
711 % \begin{macrocode}
712 \cs_new_eq:NN \@@_tmp:w ?
713 % \end{macrocode}
714 % \end{macro}
715 %
716 % \begin{variable}{\l_@@_<thing>_<place>_<version>_tl}
717 % \csname @gobble\endcsname{
718 % \l_@@_par_end_nostar_tl,
719 % \l_@@_par_end_star_tl,
720 % \l_@@_par_end__tl,
721 % \l_@@_par_itemend_nostar_tl,
722 % \l_@@_par_itemend_star_tl,
723 % \l_@@_par_itemend__tl,
724 % \l_@@_par_itemseparator_nostar_tl,
725 % \l_@@_par_itemseparator_star_tl,
726 % \l_@@_par_itemseparator__tl,
727 % \l_@@_par_itemstart_nostar_tl,
728 % \l_@@_par_itemstart_star_tl,
729 % \l_@@_par_itemstart__tl,
730 % \l_@@_par_start_nostar_tl,
731 % \l_@@_par_start_star_tl,
732 % \l_@@_par_start__tl,
733 % \l_@@_sentence_end_nostar_tl,
734 % \l_@@_sentence_end_star_tl,
735 % \l_@@_sentence_end__tl,
736 % \l_@@_sentence_itemend_nostar_tl,
737 % \l_@@_sentence_itemend_star_tl,
738 % \l_@@_sentence_itemend__tl,
739 % \l_@@_sentence_itemseparator_nostar_tl,
740 % \l_@@_sentence_itemseparator_star_tl,
741 % \l_@@_sentence_itemseparator__tl,
742 % \l_@@_sentence_itemstart_nostar_tl,
743 % \l_@@_sentence_itemstart_star_tl,
744 % \l_@@_sentence_itemstart__tl,
745 % \l_@@_sentence_start_nostar_tl,
746 % \l_@@_sentence_start_star_tl,
747 % \l_@@_sentence_start__tl,
748 % }
749 % These variables store the separators and delimiters added around the
750 % paragraphs and sentences, in the starred or nonstarred variants, as
751 % well as the generic version for runtime usage.
752 % \begin{macrocode}
753 \clist_map_inline:nn { start, itemstart, itemseparator, itemend, end }
754 {
755 \clist_map_inline:nn { par, sentence }
756 {
757 \clist_map_inline:nn { { }, star, nostar }
758 { \tl_new:c { l_@@_##1_#1_####1_tl } }
759 }
760 \tl_new:c { l_@@_par_#1_parsepar_tl }
761 }
762 \tl_set:Nn \l_@@_par_itemseparator_parsepar_tl { ~ }
763 % \end{macrocode}
764 % \end{variable}
765 %
766 % \subsection{Developer interface}
767 %
768 % \begin{macro}{\@@_parse_par_range:nNN,\@@_parse_par_range:eNN}
769 % \begin{macro}{\@@_parse_sentence_range:nNN,\@@_parse_sentence_range:eNN}
770 % \begin{macro}{\@@_parse_range_arg:nNNn,\@@_parse_range_arg:wnNNn}
771 % \begin{macro}{\@@_int_set:Nnn}
772 % Parses an argument that may be a single integer or an integer range
773 % separated by a |-|, and stores them into the integer registers |#2|
774 % and |#3|. If a number is blank, zero is used. If only a single
775 % number is given, |#3| is set equal to |#2|.
776 % \begin{macrocode}
777 \cs_new_protected:Npn \@@_parse_par_range:nNN #1 #2 #3
778 {
779 \tl_if_blank:nTF {#1}
780 { \exp_args:NV \@@_parse_range_arg:nNNn \g_fistrum_default_range_tl }
781 { \@@_parse_range_arg:nNNn {#1} }
782 #2 #3 { \g_@@_par_int }
783 }
784 \cs_new_protected:Npn \@@_parse_sentence_range:nNN #1 #2 #3
785 { \@@_parse_range_arg:nNNn {#1} #2 #3 { \c_max_int } }
786 \cs_new_protected:Npn \@@_parse_range_arg:nNNn #1
787 {
788 \exp_last_unbraced:No \@@_parse_range_arg:wnNNn
789 \tl_to_str:n { #1 - - } \s_@@ {#1}
790 }
791 \cs_new_protected:Npn \@@_parse_range_arg:wnNNn
792 #1 - #2 - #3 \s_@@ #4 #5#6 #7
793 {
794 \str_if_eq:nnTF {#3} { - }
795 {
796 \@@_int_set:Nnn #5 {#1} { 1 }
797 \@@_int_set:Nnn #6 {#2} {#7}
798 }
799 {
800 \tl_if_empty:nTF {#3}
801 {
802 \@@_int_set:Nnn #5 {#1} { \ERROR }
803 \int_set_eq:NN #6 #5
804 }
805 {
806 \msg_error:nnn { fistrum } { invalid-range } {#4}
807 \@@_parse_range_arg:nNNn { 2 - 1 } #5 #6 {#7}
808 }
809 }
810 }
811 \cs_new_protected:Npn \@@_int_set:Nnn #1 #2 #3
812 { \int_set:Nn #1 { \tl_if_blank:nT {#2} {#3} #2 } }
813 \cs_generate_variant:Nn \@@_parse_par_range:nNN { e }
814 \cs_generate_variant:Nn \@@_parse_sentence_range:nNN { e }
815 % \end{macrocode}
816 % \end{macro}
817 % \end{macro}
818 % \end{macro}
819 % \end{macro}
820 %
821 % \begin{macro}{\@@_sep_item:nn}
822 % A shorthand to leave an (\cs{undexpanded}) token list.
823 % \begin{macrocode}
824 \cs_new:Npn \@@_sep_item:nn #1 #2
825 { \exp_not:v { l_@@_#1_#2_ \l_@@_sep_set_str _tl } }
826 % \end{macrocode}
827 % \end{macro}
828 %
829 % \begin{macro}[int]{\fistrum_get_range:nn}
830 % \begin{macro}{
831 % \@@_build_list:nn,
832 % \@@_build_list_aux:n,
833 % \@@_get_paragraph:ww,
834 % \@@_get_paragraph_end:w,
835 % }
836 % Expands to the paragraphs between \meta{number_1} and
837 % \meta{number_2} with the proper delimiters added. Text is returned
838 % in \cs{exp_not:n}, so this macro can be safely used in an \cs{edef}.
839 % \begin{macrocode}
840 \cs_new:Npn \fistrum_get_range:nn #1 #2
841 {
842 \@@_sep_item:nn { par } { start }
843 \use:e
844 {
845 \exp_not:N \@@_get_paragraph:ww
846 \@@_build_list:nn {#1} {#2}
847 \exp_not:N \q_@@_mark ;
848 \exp_not:N \q_@@_mark ; \s_@@
849 }
850 \@@_sep_item:nn { par } { end }
851 }
852 \cs_new:Npn \@@_build_list:nn #1 #2
853 {
854 \int_step_function:nnN
855 { \int_max:nn {#1} { 1 } }
856 { \int_min:nn {#2} { \g_@@_par_int } }
857 \@@_build_list_aux:n
858 }
859 \cs_new:Npn \@@_build_list_aux:n #1 { #1 ; }
860 \cs_new:Npn \@@_get_paragraph:ww #1 ; #2 ;
861 {
862 \if_meaning:w \q_@@_mark #2
863 \if_meaning:w \q_@@_mark #1
864 \@@_get_paragraph_end:w
865 \else:
866 \fistrum_get_paragraph:n {#1}
867 \fi:
868 \else:
869 \fistrum_get_paragraph:n {#1}
870 \@@_sep_item:nn { par } { itemseparator }
871 \fi:
872 \@@_get_paragraph:ww #2 ;
873 }
874 \cs_new:Npn \@@_get_paragraph_end:w #1 \s_@@ { \fi: \fi: }
875 % \end{macrocode}
876 % \end{macro}
877 % \end{macro}
878 %
879 % \begin{macro}[int]{\fistrum_get_paragraph:n}
880 % Expands to the paragraph \meta{number} with the proper delimiters
881 % added. Text is returned in \cs{exp_not:n}, so this macro can be
882 % safely used in an \cs{edef}.
883 % \begin{macrocode}
884 \cs_new:Npn \fistrum_get_paragraph:n #1
885 {
886 \@@_sep_item:nn { par } { itemstart }
887 \@@_unexpanded_par:n {#1}
888 \@@_sep_item:nn { par } { itemend }
889 }
890 % \end{macrocode}
891 % \end{macro}
892 %
893 % \begin{macro}{\@@_unexpanded_par:n}
894 % Expands to the paragraph \meta{number} wrapped in \cs{exp_not:n}.
895 % If \meta{number} is out of range, it expands to nothing.
896 % \begin{macrocode}
897 \cs_new:Npn \@@_unexpanded_par:n #1
898 {
899 \bool_lazy_and:nnT
900 { \int_compare_p:nNn { 0 } < {#1} }
901 { \int_compare_p:nNn {#1} < { \g_@@_par_int + 1 } }
902 { \exp_not:v { g_@@_par_#1_tl } }
903 }
904 % \end{macrocode}
905 % \end{macro}
906 %
907 % \begin{macro}[int]{\fistrum_get_sentences:nnn,\fistrum_get_sentences:nnV}
908 % \begin{macro}{\@@_get_sentences:nnnw,\@@_get_sentences_end:w}
909 % Expands to the sentences numbered between \meta{number_1} and
910 % \meta{number_2}, inclusive, contained in the \meta{text}, and adding
911 % the proper separators.
912 % \begin{macrocode}
913 \cs_new:Npn \fistrum_get_sentences:nnn #1 #2 #3
914 {
915 \@@_sep_item:nn { sentence } { start }
916 \exp_args:Ne \use_ii_i:nn { { \int_max:nn {#1} { 1 } } }
917 { \@@_get_sentences:nnnw { 1 } } {#2}
918 #3 ~ \q_@@_mark .~ \s_@@
919 \@@_sep_item:nn { sentence } { end }
920 }
921 \cs_new:Npn \@@_get_sentences:nnnw #1 #2 #3 #4 .~
922 {
923 \int_compare:nNnT {#1} > {#3} { \@@_get_sentences_end:w }
924 \use:nn { \if_meaning:w \q_@@_mark } #4
925 \exp_after:wN \@@_get_sentences_end:w
926 \else:
927 \int_compare:nNnF {#1} < {#2}
928 {
929 \int_compare:nNnF {#1} = {#2}
930 { \@@_sep_item:nn { sentence } { itemseparator } }
931 \@@_sep_item:nn { sentence } { itemstart }
932 \exp_not:n { #4 . }
933 \@@_sep_item:nn { sentence } { itemend }
934 }
935 \fi:
936 \exp_args:Nf \@@_get_sentences:nnnw { \int_eval:n { #1 + 1 } }
937 {#2} {#3}
938 }
939 \cs_new:Npn \@@_get_sentences_end:w #1 \s_@@ { }
940 \cs_generate_variant:Nn \fistrum_get_sentences:nnn { nnV }
941 % \end{macrocode}
942 % \end{macro}
943 % \end{macro}
944 %
945 % \subsection{User- and developer-level commands}
946 %
947 % \begin{macro}[int]{\fistrumPar}
948 % Macro to typeset a single paragraph of \fist\ Was not officially
949 % available in version prior to 2.0.
950 % \begin{arguments}
951 % \item Number of the paragraph to typeset.
952 % \end{arguments}
953 % Implemented as follows:
954 % \begin{macrocode}
955 \NewDocumentCommand \fistrumPar { m }
956 {
957 \@@_deprecated:n { FistrumPar }
958 \@@_unexpanded_par:n {#1} \par
959 }
960 % \end{macrocode}
961 % \end{macro}
962 %
963 % \subsection{Tokens surrounding the \fist\ content}
964 %
965 % \begin{macro}{\@@_element_set:nnn}
966 % A general macro for setting starred/non-starred versions of several
967 % elements used between chunks of dummy text. Arguments are:
968 % \begin{arguments}
969 % \item Element name;
970 % \item Boolean true or false if the |*| variant was used;
971 % \item Value to set the element to.
972 % \end{arguments}
973 % \begin{macrocode}
974 \cs_new_protected:Npn \@@_element_set:nnn #1 #2 #3
975 { \tl_set:cn { l_@@_ #1 _ \IfBooleanF {#2} { no } star _tl } {#3} }
976 % \end{macrocode}
977 % \end{macro}
978 %
979 % \begin{macro}{\@@_deprecated:n}
980 % Warns about deprecated commands and destroys itself.
981 % \begin{macrocode}
982 \cs_new_protected:Npn \@@_deprecated:n #1
983 {
984 \msg_warning:nnn { fistrum } { cmd-deprecated } {#1}
985 \cs_gset_eq:NN \@@_deprecated:n \use_none:n
986 }
987 % \end{macrocode}
988 % \end{macro}
989 %
990 % \begin{macro}[int]{
991 % \SetFistrumParListStart,
992 % \SetFistrumParListEnd,
993 % \SetFistrumParListSurrounders,
994 % \SetFistrumParListItemSeparator,
995 % \SetFistrumParListItemStart,
996 % \SetFistrumParListItemEnd,
997 % \SetFistrumParListItemSurrounders,
998 % \SetFistrumSentenceListStart,
999 % \SetFistrumSentenceListEnd,
1000 % \SetFistrumSentenceListSurrounders,
1001 % \SetFistrumSentenceListItemSeparator,
1002 % \SetFistrumSentenceListItemStart,
1003 % \SetFistrumSentenceListItemEnd,
1004 % \SetFistrumSentenceListItemSurrounders,
1005 % }
1006 % A dirty loop to quickly define the old command-based user-interface.
1007 % \begin{macrocode}
1008 \cs_set_protected:Npn \@@_tmp:w #1 #2 #3 #4
1009 {
1010 \str_set:Nx \l_@@_tmpa_str
1011 { #2 \tl_if_empty:nTF {#4} {#3} { start } }
1012 \use:e
1013 {
1014 \NewDocumentCommand \exp_not:c { SetFistrum #1 List #2 #3 }
1015 { s +m \tl_if_empty:nF {#4} { +m } }
1016 {
1017 \@@_deprecated:n { SetFistrum #1 List #2 #3 }
1018 \@@_element_set:nnn
1019 { \exp_args:Ne \str_lowercase:n { #1_\l_@@_tmpa_str } }
1020 {##1} {##2}
1021 \tl_if_empty:nT {#4} { \use_none:nnnn }
1022 \@@_element_set:nnn { \str_lowercase:n { #1_#2 #4 } }
1023 {##1} {##3}
1024 }
1025 }
1026 }
1027 \clist_map_inline:nn { Par, Sentence }
1028 {
1029 \clist_map_inline:nn
1030 { { Start } { }, { End } { }, { Surrounders } { end } }
1031 { \@@_tmp:w {#1} { Item } ##1 \@@_tmp:w {#1} { } ##1 }
1032 \@@_tmp:w {#1} { Item } { Separator } { }
1033 }
1034 % \end{macrocode}
1035 % \end{macro}
1036 %
1037 % \begin{macro}{\SetFistrumDefault}
1038 % Command to change the default range used by \cs{fistrum} and friends.
1039 % \begin{arguments}
1040 % \item[\meta{range}] Range to be used as default.
1041 % \end{arguments}
1042 % Implemented as:
1043 % \begin{macrocode}
1044 \NewDocumentCommand \SetFistrumDefault { m }
1045 {
1046 \@@_parse_par_range:eNN {#1} \l_@@_a_int \l_@@_b_int
1047 \tl_gset:Nx \g_fistrum_default_range_tl
1048 { \int_use:N \l_@@_a_int - \int_use:N \l_@@_b_int }
1049 }
1050 % \end{macrocode}
1051 % \end{macro}
1052 %
1053 % The following macros are considered to be user-level commands and thus
1054 % all lower-case.
1055 %
1056 % \begin{macro}{\fistrum}
1057 % \begin{arguments}
1058 % \item Range-like string that specifies the number of the
1059 % paragraphs taken from \fist\ If omitted, the value set by
1060 % \cs{SetFistrumDefault} is used, which defaults to |1-7|.
1061 % \item Sentences to be typeset from the range selected by
1062 % \meta{paragraph range}. If sentences outside the number of
1063 % sentences in \meta{paragraph range} are specified, only existing
1064 % sentences are typeset.
1065 % \end{arguments}
1066 % The difference between \cs{fistrum} and \cs{fistrum*} is the token(s)
1067 % that are inserted after each paragraph (only if called without the
1068 % second optional argument).
1069 %
1070 % \cs{fistrum} and \cs{unpackfistrum} have the same interface and do
1071 % almost the same thing, so both are implemented using a common macro
1072 % \cs{@@_do:nnnn} that does the heavy-lifting, and at the end
1073 % executes the code in |#4|.
1074 % \begin{macrocode}
1075 \NewDocumentCommand \fistrum { s O { \g_fistrum_default_range_tl } o }
1076 {
1077 \@@_do:nnnn {#1} {#2} {#3}
1078 {
1079 \@@_set_hyphens:
1080 \tl_use:N ##1
1081 \@@_restore_hyphens:
1082 }
1083 }
1084 % \end{macrocode}
1085 % \end{macro}
1086 %
1087 % \begin{macro}{\unpackfistrum,\fistrumexp}
1088 % This command does the same as \cs{fistrum}, but instead of
1089 % typesetting the paragraphs or sentences, it stores the expanded
1090 % content in the \cs{fistrumexp} token list. The tokens between items
1091 % of the list, set, for example, by using the package option
1092 % \opt{space} or by using the \cs{SetFistrum...List} commands, are
1093 % |x|-expanded.
1094 % \begin{macrocode}
1095 \NewDocumentCommand \unpackfistrum { s O { \g_fistrum_default_range_tl } o }
1096 { \@@_do:nnnn {#1} {#2} {#3} { \tl_gset_eq:NN \fistrumexp ##1 } }
1097 \cs_new_eq:NN \fistrumexp \prg_do_nothing:
1098 % \end{macrocode}
1099 % \end{macro}
1100 %
1101 % \begin{macro}{\@@_do:nnnn}
1102 % \begin{macro}{\@@_do:N}
1103 % This is the main macro for \cs{fistrum} and \cs{unpackfistrum}.
1104 % It parses the paragraph range, sets the sentence/paragraph
1105 % separators, then acts accordingly if a sentence range was provided.
1106 % \begin{macrocode}
1107 \cs_new_protected:Npn \@@_do:nnnn #1 #2 #3 #4
1108 {
1109 \cs_set_protected:Npn \@@_do:N ##1 {#4}
1110 \@@_parse_par_range:eNN {#2} \l_@@_a_int \l_@@_b_int
1111 \str_set_eq:NN \l_@@_tmpa_str \l_@@_sep_set_str
1112 \str_set:Nx \l_@@_sep_set_str { \IfBooleanF {#1} { no } star }
1113 \bool_lazy_or:nnTF
1114 { \tl_if_novalue_p:n {#3} }
1115 { \tl_if_blank_p:n {#3} }
1116 {
1117 \tl_set:Nx \l_@@_output_tl
1118 { \fistrum_get_range:nn { \l_@@_a_int } { \l_@@_b_int } }
1119 }
1120 {
1121 \str_set:Nn \l_@@_sep_set_str { parsepar }
1122 \tl_set:Nx \l_@@_output_tl
1123 { \fistrum_get_range:nn { \l_@@_a_int } { \l_@@_b_int } }
1124 \str_set:Nx \l_@@_sep_set_str { \IfBooleanF {#1} { no } star }
1125 \@@_parse_sentence_range:eNN {#3} \l_@@_a_int \l_@@_b_int
1126 \tl_set:Nx \l_@@_output_tl
1127 {
1128 \fistrum_get_sentences:nnV { \l_@@_a_int } { \l_@@_b_int }
1129 \l_@@_output_tl
1130 }
1131 }
1132 \str_set_eq:NN \l_@@_sep_set_str \l_@@_tmpa_str
1133 \@@_do:N \l_@@_output_tl
1134 }
1135 \cs_new_eq:NN \@@_do:N ?
1136 % \end{macrocode}
1137 % \end{macro}
1138 % \end{macro}
1139 %
1140 % \begin{macro}{\@@_set_hyphens:,\@@_restore_hyphens:}
1141 % Selects the hyphenation patterns for the language of the dummy text,
1142 % using \cs{hyphenrules} if that's defined. If \cs{hyphenrules}
1143 % doesn't exist try setting hyphenation with \cs{@@_set_hyphens_raw:}.
1144 % Each \cs[no-index]{@@_set_hyphens_\meta{method}:} function
1145 % appropriately redefines \cs{@@_restore_hypehens:} to reset the
1146 % hyphenation patterns.
1147 % \begin{macrocode}
1148 \cs_new_protected:Npn \@@_set_hyphens:
1149 {
1150 \bool_if:NTF \l_@@_autolang_bool
1151 { \use:n } { \use_none:n }
1152 {
1153 \cs_if_exist:NTF \hyphenrules
1154 {
1155 \cs_if_exist:cTF { [email protected] }
1156 { \@@_set_hyphens_polyglossia: }
1157 { \@@_set_hyphens_babel: }
1158 }
1159 { \@@_set_hyphens_raw: }
1160 }
1161 }
1162 \cs_new_protected:Npn \@@_restore_hyphens:
1163 { \prg_do_nothing: }
1164 % \end{macrocode}
1165 % \end{macro}
1166 %
1167 % \begin{macro}{\@@_set_hyphens_babel:}
1168 % \pkg{babel} makes things pretty simple. We just check if
1169 % \cs[no-index]{l@\meta{lang}} is defined, and if so, use
1170 % \cs{hyphenrules} to set it, and once more to reset in
1171 % \cs{@@_restore_hyphens:}. \cs{hyphenrules} is actually an
1172 % environment, but in \pkg{babel} its \cs[no-index]{end} part does
1173 % nothing, and its effect can be undone by just using another
1174 % \cs{hyphenrules} on top of it.
1175 %
1176 % If the language is not defined, the language either doesn't exist at
1177 % all, or we are using Lua\TeX. Both cases are handled by
1178 % \cs{@@_lang_not_available:}.
1179 % \begin{macrocode}
1180 \cs_new_protected:Npn \@@_set_hyphens_babel:
1181 {
1182 \cs_if_exist:cTF { l@ \g_@@_language_tl }
1183 {
1184 \exp_args:NV \hyphenrules \g_@@_language_tl
1185 \cs_set_protected:Npx \@@_restore_hyphens:
1186 { \exp_not:N \hyphenrules { \languagename } }
1187 }
1188 { \@@_lang_not_available: }
1189 }
1190 % \end{macrocode}
1191 % \end{macro}
1192 %
1193 % \begin{macro}{\@@_set_hyphens_polyglossia:}
1194 % \pkg{polyglossia} less friendly. We also check if the language is
1195 % loaded (looking at \cs[no-index]{\meta{lang}@loaded}), and if it
1196 % is, load it with the \env{hyphenrules} environment. Here we can't
1197 % use the command form, as the \cs[no-index]{end} part is not a no-op.
1198 % This also means that an extra group is added around the dummy text,
1199 % which causes issue \ghissue{1} when used with \pkg{wrapfig}, for
1200 % example. But not too much we can do about that for now.
1201 %
1202 % In case the language is not loaded, fall back to
1203 % \cs{@@_set_hyphens_raw:} for a final attempt before giving up.
1204 % \begin{macrocode}
1205 \cs_new_protected:Npn \@@_set_hyphens_polyglossia:
1206 {
1207 \cs_if_exist:cTF { \g_@@_language_tl @loaded }
1208 {
1209 \exp_args:NnV \begin{hyphenrules} \g_@@_language_tl
1210 \cs_set_protected:Npn \@@_restore_hyphens:
1211 { \end{hyphenrules} }
1212 }
1213 { \@@_set_hyphens_raw: }
1214 }
1215 % \end{macrocode}
1216 % \end{macro}
1217 %
1218 % \begin{macro}{\@@_set_hyphens_raw:}
1219 % If nothing else is available, try setting the language using
1220 % \cs{language}\meta{number}. This is always available,
1221 % except with Lua\TeX, which loads languages on-the-fly.
1222 % \begin{macrocode}
1223 \cs_new_protected:Npn \@@_set_hyphens_raw:
1224 {
1225 \cs_if_exist:cTF { l@ \g_@@_language_tl }
1226 {
1227 \use:x
1228 {
1229 \language \use:c { l@ \g_@@_language_tl }
1230 \cs_set_protected:Npn \@@_restore_hyphens:
1231 { \language \int_eval:n { \language } \scan_stop: }
1232 }
1233 }
1234 { \@@_lang_not_available: }
1235 }
1236 % \end{macrocode}
1237 % \end{macro}
1238 %
1239 % \begin{macro}{\@@_lang_not_available:}
1240 % If the requested language is for some reason unavailable, warn the
1241 % user, then fall back to the current language. If the requested
1242 % language and \cs{languagename} are the same, we are probably running
1243 % into this warning again because we have no languages loaded (e.g.,
1244 % testing environments). In that case, shut up because there's not
1245 % much that can be done (and a warning that says ``language "english"
1246 % is not available; using "english" instead'' is of little use).
1247 % \begin{macrocode}
1248 \cs_new_protected:Npn \@@_lang_not_available:
1249 {
1250 \str_if_eq:VVF \g__fistrum_language_tl \languagename
1251 {
1252 \msg_warning:nnx { fistrum } { missing-language }
1253 { \g_@@_language_tl }
1254 \tl_gset_eq:NN \g_@@_language_tl \languagename
1255 }
1256 }
1257 % \end{macrocode}
1258 % \end{macro}
1259 %
1260 % \begin{macro}{\NewFistrumPar}
1261 % Developer-Level macro to add a paragraph to the dummy text used by
1262 % \cs{fistrum} and related commands. To specify a new dummy text, see
1263 % section~\ref{sec:other-texts}.
1264 % \begin{macrocode}
1265 \cs_new_protected:Npn \NewFistrumPar #1
1266 {
1267 \int_gincr:N \g_@@_par_int
1268 \tl_gclear_new:c { g_@@_par_ \int_use:N \g_@@_par_int _tl }
1269 \tl_gset:cn { g_@@_par_ \int_use:N \g_@@_par_int _tl } {#1}
1270 }
1271 % \end{macrocode}
1272 % \end{macro}
1273 %
1274 % \begin{macro}{\SetFistrumText}
1275 % Used to select and load the text output by \cs{fistrum} and friends.
1276 % See the section on loading and defining new outputs for \cs{fistrum}
1277 % (section~\ref{sec:other-texts}). It first checks whether the
1278 % requested text is already loaded, and if not, it loads the
1279 % corresponding fistrum text definition file, and clears remaining
1280 % paragraphs from the previous text, in case their lengths differ.
1281 % \begin{macrocode}
1282 \NewDocumentCommand \SetFistrumText { m }
1283 {
1284 \str_if_eq:VnF \g_@@_text_str {#1}
1285 {
1286 \tl_gset:Nn \g_@@_language_tl { english }
1287 \int_gzero:N \g_@@_par_int
1288 \file_input:n { #1.ftd }
1289 \str_gset:Nn \g_@@_text_str {#1}
1290 }
1291 }
1292 % \end{macrocode}
1293 % \end{macro}
1294 %
1295 % \begin{macro}{\SetFistrumLanguage}
1296 % This macro sets the language for hyphenation patterns of the dummy
1297 % text. When a new fistrum text is read, this is reset.
1298 % \begin{macrocode}
1299 \NewDocumentCommand \SetFistrumLanguage { m }
1300 { \tl_gset:Nn \g_@@_language_tl {#1} }
1301 % \end{macrocode}
1302 % \end{macro}
1303 %
1304 % \subsection{Package options and defaults}
1305 %
1306 % \begin{macro}[int]{
1307 % \fistrumRestoreParList,
1308 % \fistrumRestoreSentenceList,
1309 % \fistrumRestoreAll,
1310 % }
1311 % \begin{macro}{\@@_delim_restore:nnn}
1312 % \begin{macro}{\@@_restore_par_list:,\@@_restore_sentence_list:}
1313 % These are some auxiliaries for the package options and for setting
1314 % up the default behaviour.
1315 % \begin{macrocode}
1316 \cs_new_protected:Npn \@@_delim_restore:nnn #1 #2 #3
1317 {
1318 \keys_set:nn { fistrum }
1319 {
1320 #1-before = , #1-begin = , #1-end = , #1-after = ,
1321 #1-before* = , #1-begin* = , #1-end* = , #1-after* = ,
1322 #1-sep = {#2}, #1-sep* = {#3}
1323 }
1324 }
1325 \cs_new_protected:Nn \@@_restore_sentence_list:
1326 { \@@_delim_restore:nnn { sentence } { ~ } { ~ } }
1327 \cs_new_eq:NN \@@_restore_par_list: ?
1328 \cs_new_protected:Npn \fistrumRestoreParList
1329 {
1330 \@@_deprecated:n { FistrumRestoreParList }
1331 \@@_restore_par_list:
1332 }
1333 \cs_new_protected:Npn \fistrumRestoreSentenceList
1334 {
1335 \@@_deprecated:n { FistrumRestoreSentenceList }
1336 \@@_restore_sentence_list:
1337 }
1338 \cs_new_protected:Npn \fistrumRestoreAll
1339 {
1340 \@@_deprecated:n { FistrumRestoreAll }
1341 \@@_restore_par_list: \@@_restore_sentence_list:
1342 }
1343 % \end{macrocode}
1344 % \end{macro}
1345 % \end{macro}
1346 % \end{macro}
1347 %
1348 % \begin{macro}{\setfistrum}
1349 % Here are the options available at load-time and to \cs{setfistrum}.
1350 % \begin{macrocode}
1351 \NewDocumentCommand \setfistrum { +m }
1352 { \keys_set:nn { fistrum } {#1} }
1353 \keys_define:nn { fistrum }
1354 {
1355 % \end{macrocode}
1356 % \opt{nopar} is implemented as a choice key instead of a boolean so
1357 % we can update the separators using \cs{@@_delim_restore:nnn}.
1358 % It's initially false, and the default is |true| so that
1359 % |\usepackage[nopar]{fistrum}| works as it always did.
1360 % \begin{macrocode}
1361 nopar .choice: ,
1362 nopar / true .code:n =
1363 {
1364 \cs_gset_protected:Npn \@@_restore_par_list:
1365 { \@@_delim_restore:nnn { par } { ~ } { \par } }
1366 } ,
1367 nopar / false .code:n =
1368 {
1369 \cs_gset_protected:Nn \@@_restore_par_list:
1370 { \@@_delim_restore:nnn { par } { \par } { ~ } }
1371 } ,
1372 nopar .initial:n = false ,
1373 nopar .default:n = true ,
1374 % \end{macrocode}
1375 % \opt{auto-lang} sets \cs{l_@@_autolang_bool}. It is initially
1376 % |true|, changing the default behaviour from previous versions.
1377 % \begin{macrocode}
1378 auto-lang .bool_set:N = \l_@@_autolang_bool ,
1379 auto-lang .initial:n = true ,
1380 auto-lang .default:n = true ,
1381 % \end{macrocode}
1382 % \opt{text} just does \cs{SetFistrumText}. The |initial| value is not
1383 % set here because this chunk of code is executed in \pkg{expl3}
1384 % syntax, then thetextloadswithoutspaces, so |\setfistrum{text=fistrum-la}|
1385 % is used later.
1386 % \begin{macrocode}
1387 text .code:n = \SetFistrumText{#1} ,
1388 text .value_required:n = true ,
1389 % \end{macrocode}
1390 % \opt{language} sets the language to be used when typesetting.
1391 % \begin{macrocode}
1392 language .tl_gset:N = \g_@@_language_tl ,
1393 language .value_required:n = true ,
1394 % \end{macrocode}
1395 % \opt{default-range} does \cs{SetFistrumDefault}, initially |1-7|, as
1396 % documented. It's default is also |1-7| so that the key has two
1397 % meanings: \cs{setfistrum}|{default-range=|\meta{range}|}| sets the
1398 % range to the given value, while \cs{setfistrum}|{default-range}| sets
1399 % the range to the ``default default range''. Pretty neat :)
1400 % \begin{macrocode}
1401 default-range .code:n = \SetFistrumDefault{#1} ,
1402 default-range .initial:n = 1-7 ,
1403 default-range .default:n = 1-7 ,
1404 }
1405 % \end{macrocode}
1406 % This chunk defines the keys \meta{thing}-\meta{place}[*], where
1407 % \meta{thing} is |par| or |sentence|, \meta{place} is |before|,
1408 % |begin|, |sep|, |end|, and |after|, which totals~10 keys, and
1409 % another~10 with the |*| in the name. Each sets a token list called
1410 % \cs[no-index]{l_@@_\meta{thing}_\meta{place}_[no]star_tl}.
1411 % \begin{macrocode}
1412 \cs_set_protected:Npn \@@_tmp:w #1 #2 #3
1413 {
1414 \keys_define:nn { fistrum }
1415 {
1416 #1-before #2 .tl_set:c = l_@@_#1_start _#3star_tl ,
1417 #1-begin #2 .tl_set:c = l_@@_#1_itemstart _#3star_tl ,
1418 #1-sep #2 .tl_set:c = l_@@_#1_itemseparator _#3star_tl ,
1419 #1-end #2 .tl_set:c = l_@@_#1_itemend _#3star_tl ,
1420 #1-after #2 .tl_set:c = l_@@_#1_end _#3star_tl ,
1421 }
1422 }
1423 \@@_tmp:w { par } { } { no } \@@_tmp:w { sentence } { } { no }
1424 \@@_tmp:w { par } * { } \@@_tmp:w { sentence } * { }
1425 % \end{macrocode}
1426 % \end{macro}
1427 %
1428 % Now turn \cs{ExplSyntaxOff} for a while, and load the default \fist{}
1429 % text, then process the package options, and finally turn
1430 % \cs{ExplSyntaxOn} again. Finally, call \cs{@@_restore_par_list:} and
1431 % \cs{@@_restore_sentence_list:} to set the defaults
1432 % (\cs{@@_restore_par_list:} may have been redefined by \opt{nopar}).
1433 % \begin{macrocode}
1434 \ExplSyntaxOff
1435 \setfistrum{text=fistrum-es}
1436 \ProcessKeysOptions{fistrum}
1437 \ExplSyntaxOn
1438 \@@_restore_par_list:
1439 \@@_restore_sentence_list:
1440 % \end{macrocode}
1441 %
1442 % \subsection{Messages}
1443 %
1444 % Now define the messages used throughout the package.
1445 % \begin{macrocode}
1446 \msg_new:nnn { fistrum } { invalid-range }
1447 { Invalid~number~or~range~'#1'. }
1448 \msg_new:nnn { fistrum } { cmd-deprecated }
1449 {
1450 Command~'\iow_char:N\\#1'~deprecated. \\
1451 See~the~fistrum~documentation~for~help.
1452 }
1453 \msg_new:nnn { fistrum } { missing-language }
1454 {
1455 Unknown~language~'#1'.~Hyphenation~patterns~for~
1456 '\languagename'~will~be~used~instead.
1457 \sys_if_engine_luatex:T
1458 {
1459 \\ \\
1460 \cs_if_exist:cTF { [email protected] }
1461 {
1462 With~polyglossia,~you~have~to~explicitly~load~languages~
1463 with~\iow_char:N\\setotherlanguage{#1}~or~similar.
1464 }
1465 {
1466 With~LuaTeX,~fistrum~requires~babel~to~get~proper~
1467 hyphenation~(you~can~use~
1468 \iow_char:N\\usepackage[base]{babel}).
1469 }
1470 }
1471 }
1472 % \end{macrocode}
1473 %
1474 % \begin{macrocode}
1475 %</package>
1476 % \end{macrocode}
1477 %
1478 % \end{implementation}
1479 %
1480 % \endinput
1481 % Local Variables:
1482 % mode: doctex
1483 % TeX-master: t
1484 % End: