Debian Codegraph @

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

raw
1 % \iffalse meta-comment
2 % SPDX-FileCopyrightText: Copyright (c) 2021-2026 Yegor Bugayenko
3 % SPDX-License-Identifier: MIT
4 % \fi
5
6 % \CheckSum{0}
7 %
8 % \CharacterTable
9 % {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
10 % 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
11 % Digits \0\1\2\3\4\5\6\7\8\9
12 % Exclamation \! Double quote \" Hash (number) \#
13 % Dollar \$ Percent \% Ampersand \&
14 % Acute accent \' Left paren \( Right paren \)
15 % Asterisk \* Plus \+ Comma \,
16 % Minus \- Point \. Solidus \/
17 % Colon \: Semicolon \; Less than \<
18 % Equals \= Greater than \> Question mark \?
19 % Commercial at \@ Left bracket \[ Backslash \\
20 % Right bracket \] Circumflex \^ Underscore \_
21 % Grave accent \` Left brace \{ Vertical bar \|
22 % Right brace \} Tilde \~}
23
24 % \GetFileInfo{ffcode.dtx}
25 % \DoNotIndex{\endgroup,\begingroup,\let,\else,\fi,\newcommand,\newenvironment}
26
27 % \iffalse
28 %<*driver>
29 \ProvidesFile{ffcode.dtx}
30 %</driver>
31 %<package>\NeedsTeXFormat{LaTeX2e}
32 %<package>\ProvidesPackage{ffcode}
33 %<*package>
34 [2026-05-26 0.12.1 Fixed Font Code]
35 %</package>
36 %<*driver>
37 \documentclass{ltxdoc}
38 \usepackage[T1]{fontenc}
39 \usepackage{lmodern}
40 \usepackage{microtype}
41 \AddToHook{env/verbatim/begin}{\microtypesetup{protrusion=false}}
42 \usepackage{href-ul}
43 \usepackage{ffcode}
44 \usepackage{amsmath}
45 \usepackage{multicol}
46 \usepackage{xcolor}
47 \usepackage[dtx,runs=2]{docshots}
48 \PageIndex
49 \EnableCrossrefs
50 \CodelineIndex
51 \RecordChanges
52 \begin{document}
53 \DocInput{ffcode.dtx}
54 \PrintChanges
55 \PrintIndex
56 \end{document}
57 %</driver>
58 % \fi
59
60 % \title{|ffcode|: \LaTeX{} Package \\ for Fixed-Font Code Blocks\thanks{The sources are in GitHub at \href{https://github.com/yegor256/ffcode}{yegor256/ffcode}}}
61 % \author{Yegor Bugayenko \\ \texttt{[email protected]}}
62 % \date{\filedate, \fileversion}
63 %
64 % \maketitle
65 %
66 % \section{Introduction}
67 %
68 % This package typesets source code within articles
69 % and ensures a tidy, consistent appearance. Following installation from
70 % CTAN, the typical usage proceeds as follows (note the |\ff| command
71 % and the |ffcode| environment):
72 % \begin{docshot}
73 % \documentclass{article}
74 % \usepackage{ffcode}
75 % \pagestyle{empty}
76 % \begin{document}
77 % The function |fibo()| is recursive:
78 % \begin{ffcode}
79 % int fibo(int n) {
80 % if (n < 2) {
81 % return n; (*@ \label{ln:ret} @*)
82 % }
83 % return fibo(n-1)+fibo(n-2);
84 % }
85 % \end{ffcode}
86 % Line no.~\ref{ln:ret} returns \ff{n}
87 % and terminates it.
88 % \end{document}
89 % \end{docshot}
90
91 % \DescribeMacro{\ffinput}
92 % An |\ffinput| command is also provided, which reads content from a file
93 % and inserts it into the document, formatted in precisely the manner that
94 % would result from the |ffcode| environment. The |ffsave|
95 % environment may be employed beforehand; it behaves as the |ffcode|
96 % environment, save that the content is written to a file rather than
97 % printed, whence it may subsequently be retrieved by the |\ffinput| command.
98
99 % \section{Package Options}
100
101 % \DescribeMacro{samepage}
102 % The |samepage| package option prevents page breaks inside |ffcode| blocks.
103
104 % \DescribeMacro{noframes}
105 % The |noframes| package option omits the light gray frames around |\ff|
106 % texts.
107
108 % \DescribeMacro{nobars}
109 % The |nobars| package option omits the vertical gray bar at the left side
110 % of each snippet.
111
112 % \DescribeMacro{nonumbers}
113 % The |nonumbers| package option omits the line numbers.
114
115 % \DescribeMacro{nocn}
116 % By default, line numbering is continuous: numbers commence at the
117 % first snippet and increment until the end of the document. The |nocn|
118 % package option (an abbreviation for ``no continuous numbering'') causes
119 % the numbering to restart from one in each snippet.
120
121 % \DescribeMacro{bold}
122 % The |\ff| fragments may be rendered in a heavier weight than the default, which proves convenient for certain document classes
123 % (note the use of the \href{https://ctan.org/pkg/lmodern}{lmodern} package: without it, boldface fails to operate, as explained \href{https://tex.stackexchange.com/a/215489/1449}{here}):
124 % \docshotOptions{firstline=4,lastline=10}
125 % \begin{docshot}
126 % \documentclass{article}
127 % \usepackage[paperwidth=3in]{geometry}
128 % \pagestyle{empty}
129 % \usepackage{lmodern}
130 % \usepackage[bold,noframes]{ffcode}
131 % \begin{document}
132 % Sometimes it's necessary to make
133 % code pieces look bolder, like
134 % the |fibo()| function in this text.
135 % \end{document}
136 % \end{docshot}
137
138 % \DescribeMacro{sf}
139 % The font family of |\ff| fragments may be altered to |\sffamily|:
140 % \docshotOptions{firstline=4,lastline=10}
141 % \begin{docshot}
142 % \documentclass{article}
143 % \usepackage[paperwidth=3in]{geometry}
144 % \pagestyle{empty}
145 % \usepackage[sf,bold,noframes]{ffcode}
146 % \begin{document}
147 % Sometimes a less strictly fixed-width,
148 % more elegant look may be preferred,
149 % like the \emph{|fibo()|} here.
150 % \end{document}
151 % \end{docshot}
152
153 % \section{Typesetting}
154
155 % The package handles low-height text correctly, for instance a solitary
156 % dot: \ff{.}
157
158 % A pair of vertical bars decorates a \TeX{} command within a snippet.
159 % A single vertical bar may be produced by means of
160 % ``\verb+|\char`\\vert|+''.
161
162 % The |\ff| command behaves differently in math mode---it adds no
163 % grey frames:
164 % \docshotOptions{firstline=6,lastline=8}
165 % \begin{docshot}
166 % \documentclass{article}
167 % \usepackage{ffcode}
168 % \usepackage{mathtools}
169 % \pagestyle{empty}
170 % \begin{document}
171 % \begin{equation*}
172 % x = \int_{|home|}^{\ff{N}} f(x).
173 % \end{equation*}
174 % \end{document}
175 % \end{docshot}
176
177 % Lines within the |ffcode| environment may be highlighted,
178 % and any further configuration parameters from
179 % the |listings| package may likewise be supplied:
180 % \docshotOptions{firstline=6,lastline=13}
181 % \begin{docshot}
182 % \documentclass{article}
183 % \usepackage[paperwidth=3in]{geometry}
184 % \usepackage{ffcode}
185 % \pagestyle{empty}
186 % \begin{document}
187 % \begin{ffcode}[backgroundcolor=\color{gray!20}]
188 % while (true) {
189 % (*@\textcolor{red}{print("Hi!")}@*)
190 % print("Enter your name:")
191 % scan(x)
192 % print("Your name | " + x)
193 % }
194 % \end{ffcode}
195 % \end{document}
196 % \end{docshot}
197
198 % By means of the optional argument of |ffcode|,
199 % any other options from the |listings| package may be conveyed to the
200 % snippet.
201
202 % The |\lstset| command of the |listings| package may also be employed
203 % to establish defaults for the |ffcode| environment.
204 % In contrast to the optional argument, which applies solely to a single
205 % snippet, |\lstset| acts globally: every subsequent code listing in the
206 % document inherits the new settings, including any further |ffcode|
207 % blocks thereafter.
208 % To confine the change to a single |ffcode| block, the call should be
209 % wrapped within a |\begingroup|\ldots|\endgroup| pair:
210 % \docshotOptions{firstline=6,lastline=12}
211 % \begin{docshot}
212 % \documentclass{article}
213 % \usepackage[paperwidth=3in]{geometry}
214 % \usepackage{ffcode}
215 % \pagestyle{empty}
216 % \begin{document}
217 % \begingroup
218 % \lstset{backgroundcolor=\color{yellow!30}}
219 % \begin{ffcode}
220 % print("Hi!")
221 % \end{ffcode}
222 % \endgroup
223 % \end{document}
224 % \end{docshot}
225
226 % A snippet may be rendered in ``condensed'' mode, with reduced spacing
227 % between letters, by supplying |columns=fixed| together with a narrower
228 % |basewidth| from the |listings| package:
229 % \docshotOptions{firstline=6,lastline=12}
230 % \begin{docshot}
231 % \documentclass{article}
232 % \usepackage[paperwidth=3in]{geometry}
233 % \usepackage{ffcode}
234 % \pagestyle{empty}
235 % \begin{document}
236 % \begin{ffcode}[columns=fixed,basewidth=0.4em]
237 % while (true) {
238 % print("Enter your name:")
239 % scan(x)
240 % print("Hello, " + x)
241 % }
242 % \end{ffcode}
243 % \end{document}
244 % \end{docshot}
245
246 % \StopEventually{}
247
248 % \section{Implementation}
249 % \changes{v0.1.0}{2021/06/10}{Initial version}
250
251 % First, we parse package options with the help of
252 % \href{https://ctan.org/pkg/pgfopts}{pgfopts} package:
253 % \changes{v0.2.0}{2021/06/13}{Package options \texttt{nonumbers} and \texttt{noframes} added.}
254 % \changes{v0.3.0}{2021/09/07}{Package option \texttt{nocn} added.}
255 % \changes{v0.4.0}{2022/01/09}{Package option \texttt{nobars} added.}
256 % \changes{v0.6.0}{2022/11/16}{We use \texttt{pgfopts} instead of \texttt{xkeyval}.}
257 % \changes{v0.6.0}{2022/11/16}{Package option \texttt{novert} added, to disable the redefinition of the vertical bar.}
258 % \changes{v0.7.0}{2022/11/28}{Package option \texttt{bold} added, to make all \texttt{\char`\\ff} pieces look bolder than usual.}
259 % \changes{v0.7.0}{2022/11/28}{Package option \texttt{sf} added, to print all \texttt{\char`\\ff} pieces with \texttt{\char`\\sffamily}.}
260 % \changes{v0.9.2}{2024/02/04}{All lengths and sizes are in "em" instead of "pt".}
261 % \changes{v0.10.0}{2025/01/02}{Package option \texttt{samepage} added, to prevent each \texttt{ffcode} block from breaking across pages.}
262 % \changes{v0.11.1}{2026/05/01}{Reserve \texttt{xleftmargin} for line numbers so they sit inside the column instead of protruding into the page margin.}
263 % \begin{macrocode}
264 \RequirePackage{pgfopts}
265 \pgfkeys{
266 /ff/.cd,
267 bold/.store in=\ff@bold,
268 sf/.store in=\ff@sf,
269 samepage/.store in=\ff@samepage,
270 noframes/.store in=\ff@noframes,
271 nonumbers/.store in=\ff@nonumbers,
272 nobars/.store in=\ff@nobars,
273 novert/.store in=\ff@novert,
274 nocn/.store in=\ff@nocn,
275 }
276 \ProcessPgfPackageOptions{/ff}
277 % \end{macrocode}
278
279 % Then, we include the \href{https://ctan.org/pkg/xcolor}{xcolor} package:
280 % \begin{macrocode}
281 \RequirePackage{xcolor}
282 % \end{macrocode}
283
284 % Then, we configure the \href{https://ctan.org/pkg/listings}{listings} package.
285 % The defaults are applied here, at package load, so that a user may override
286 % them globally with \texttt{\char`\\lstset} after \texttt{\char`\\usepackage\{ffcode\}}:
287 % \changes{v0.9.0}{2024/01/09}{The \texttt{minted} package is replaced by the \texttt{listings} package.}
288 % \changes{v0.10.2}{2025/07/06}{We started to use \texttt{keepspaces} in order to guarantee correct visual rendering of multi-spaced content.}
289 % \changes{v0.12.0}{2026/05/05}{Static \texttt{\char`\\lstset} defaults moved from the per-environment hook to the preamble, so that user-supplied \texttt{\char`\\lstset} calls are no longer overwritten on every \texttt{ffcode} usage.}
290 % \begin{macrocode}
291 \RequirePackage{listings}
292 \makeatletter
293 % See \href{https://tex.stackexchange.com/questions/706858}{the explanation}:
294 \lst@AddToHook{Init}{\setlength{\lineskip}{0pt}}
295 \lstset{breaklines}
296 \lstset{escapeinside={(*@}{@*)}}
297 \lstset{basicstyle={\ttfamily}}
298 \lstset{columns=fullflexible}
299 \lstset{keepspaces=true}
300 \ifdefined\ff@nonumbers\else
301 \lstset{numbers=left,numbersep=.8em,
302 numberstyle={\tiny\sffamily\color{gray}},
303 xleftmargin=2.5em}
304 \fi
305 \ifdefined\ff@nobars\else
306 \lstset{frame=leftline,framerule=.05em,rulecolor={\color{gray}}}
307 \fi
308 \ifdefined\ff@nocn\else
309 \lstset{firstnumber=last}
310 \fi
311 \makeatother
312 % \end{macrocode}
313
314 % Then, we define a supplementary command \texttt{\char`\\ff@set} that
315 % applies per-environment options on top of the global defaults:
316 % \begin{macrocode}
317 \makeatletter
318 \newcommand\ff@set[1]{\lstset{#1}}
319 \makeatother
320 % \end{macrocode}
321
322 % \begin{macro}{ffcode}
323 % Then, we define the |ffcode| environment and its supplementary |ffcode*| counterpart:
324 % \begin{macrocode}
325 \makeatletter
326 \lstnewenvironment{ffcode}[1][]
327 {\ff@set{#1}\ifdefined\ff@samepage\noindent\minipage{\linewidth}\fi}
328 {\ifdefined\ff@samepage\endminipage\fi}
329 \makeatother
330 % \end{macrocode}
331 % \end{macro}
332
333 % \begin{macro}{ffinput}
334 % Then, we define the \texttt{\char`\\ffinput} command:
335 % \changes{v0.10.0}{2024/12/29}{The \texttt{\char`\\ffinput} command added.}
336 % \changes{v0.12.0}{2026/05/26}{Stopped \texttt{\char`\\ffinput} options from leaking into later listings.}
337 % \begin{macrocode}
338 \makeatletter
339 \newcommand\ffinput[2][]{%
340 \ifdefined\ff@samepage\noindent\minipage{\linewidth}\fi%
341 \lstinputlisting[#1]{#2}%
342 \ifdefined\ff@samepage\endminipage\fi%
343 }
344 \makeatother
345 % \end{macrocode}
346 % \end{macro}
347
348 % \begin{macro}{ffsave}
349 % Then, we define the \texttt{ffsave} environment:
350 % \changes{v0.11.0}{2025/07/06}{The \texttt{ffsave} environment added.}
351 % \begin{macrocode}
352 \RequirePackage{fancyvrb}
353 \newenvironment{ffsave}[1][ffsave.txt]
354 {\VerbatimEnvironment\begin{VerbatimOut}{#1}}
355 {\end{VerbatimOut}}
356 % \end{macrocode}
357 % \end{macro}
358
359 % \begin{macro}{\ff@print}
360 % Then, we define a supplementary macro |\ff@print|:
361 % \changes{v0.5.1}{2022/10/30}{Now, the command \texttt{ff} ignores italic and bold and always prints \texttt{\char`\\texttt} as it should be.}
362 % \begin{macrocode}
363 \makeatletter
364 \newcommand\ff@print[1]{%
365 \textnormal{%
366 \ifdefined\ff@sf\sffamily\else\ttfamily\fi%
367 \ifdefined\ff@bold\fontseries{b}\selectfont\fi%
368 #1%
369 }%
370 }
371 \makeatother
372 % \end{macrocode}
373 % \end{macro}
374
375 % \begin{macro}{\ff@rule}
376 % Then, we define a supplementary command |\ff@rule|:
377 % \begin{macrocode}
378 \makeatletter\newcommand\ff@rule
379 {\vrule height 0.6em depth 0.1em width 0em}
380 \makeatother
381 % \end{macrocode}
382 % \end{macro}
383
384 % \begin{macro}{\ff@box}
385 % Then, we use \href{https://ctan.org/pkg/tcolorbox}{tcolorbox} to define the |\ff@box|
386 % command for a gray box around a verbatim text block:
387 % \begin{macrocode}
388 \makeatletter
389 \ifdefined\ff@noframes\else
390 \RequirePackage{tcolorbox}
391 \newtcbox\ff@box{nobeforeafter,colframe=gray!80!white,
392 colback=gray!5!white,boxrule=0.01em,arc=0.1em,
393 boxsep=0.12em,left=0.05em,right=0.05em,top=0.02em,bottom=0.02em,
394 tcbox raise base}
395 \fi
396 \makeatother
397 % \end{macrocode}
398 % \end{macro}
399
400 % \begin{macro}{\ff@x}
401 % Then, we define the internal |\ff@x| command for printing a piece of fixed-width-font text:
402 % \begin{macrocode}
403 \makeatletter
404 \NewDocumentCommand\ff@x{v}{\ff{#1}}
405 \makeatother
406 % \end{macrocode}
407 % \end{macro}
408
409 % \begin{macro}{\ff}
410 % \changes{v0.8.0}{2022/12/01}{The \texttt{\char`\\ff} command is now a normal command, not verbatim.}
411 % Then, we define |\ff| macro:
412 % \begin{macrocode}
413 \makeatletter
414 \newcommand\ff[1]{%
415 \ifdefined\ff@noframes%
416 \ff@rule\ff@print{#1}%
417 \else%
418 \relax\ifmmode%
419 \ff@rule\ff@print{#1}%
420 \else%
421 \ff@box{\ff@rule\ff@print{#1}}%
422 \fi%
423 \fi%
424 }
425 \makeatother
426 % \end{macrocode}
427 % \end{macro}
428
429 % \begin{macro}{novert}
430 % Finally, we let vertical bars work similarly to |\ff|, as suggested
431 % \href{https://tex.stackexchange.com/a/665105/1449}{here}
432 % and \href{https://tex.stackexchange.com/a/665303/1449}{here}
433 % (unless the |novert| package option is used):
434 % \begin{macrocode}
435 \makeatletter\ifdefined\ff@novert\else
436 \catcode`\|\active
437 \AtBeginDocument{\catcode`\|\active\protected\def|{\ff@x|}}
438 \catcode`\| 12 %
439 \fi\makeatother
440 % \end{macrocode}
441 % \end{macro}
442
443 % \begin{macrocode}
444 \endinput
445 % \end{macrocode}
446
447 % \Finale
448
449 %\clearpage
450 %
451 %\PrintChanges
452 %\clearpage
453 %\PrintIndex