Debian Codegraph @

texmf-dist/source/latex/framedsyntax/FramedSyntax.dtx

raw
1 % \iffalse
2 % !TEX encoding = UTF-8 Unicode
3 %<*internal>
4 \begingroup
5 \input docstrip.tex
6 \keepsilent
7 \preamble
8
9 Copyright (C) 2024 Claudio Beccari all rights reserved.
10
11 Distributable under the LaTeX Project Public License,
12 version 1.3c or higher (your choice). The latest version of
13 this license is at: http://www.latex-project.org/lppl.txt
14
15 \endpreamble
16 \postamble
17 This Work has the status of `maintained'
18
19 The Current Maintainer is Claudio Beccari
20
21 This work consists of this file FramedSyntax.dtx,
22 and the derived files FramedSyntax.sty and FramedSyntax.pdf.
23 \endpostamble
24
25 \askforoverwritefalse
26
27 \generate{\file{FramedSyntax.sty}{\from{FramedSyntax.dtx}{package}}}
28
29 \def\tmpa{plain}
30 \ifx\tmpa\fmtname\endgroup\expandafter\bye\fi
31 \endgroup
32 %</internal>
33 % \fi
34 %
35 % \iffalse
36 %<*driver>
37 \ProvidesFile{FramedSyntax.dtx}%
38 %</driver>
39 %<package>\NeedsTeXFormat{LaTeX2e}[2019/01/01]
40 %<package>\ProvidesPackage{FramedSyntax}%
41 [2024-09-04 v.0.2.8 Typeset command syntax within a special frame]
42 %<*driver>
43 \documentclass{ltxdoc}\errorcontextlines=100
44 \hfuzz 10pt
45 \usepackage[utf8]{inputenc}% not really necessary
46 \usepackage{lmodern}% scalable fonts
47 \usepackage{mflogo}
48 \usepackage{multicol, amsmath, fancyvrb, graphicx, verbatim}
49 \usepackage{etoolbox, enumitem, xspace, xcolor, FramedSyntax
50 }
51 %
52 \providecommand*\diff{\mathop{}\!\mathrm{d}}
53 \providecommand\file{}
54 \renewcommand*\file[1]{{\normalfont\texttt{#1}}}
55 \providecommand\prog{}
56 \renewcommand*\prog[1]{{\normalfont\texttt{#1}}}
57 \providecommand\conta{}
58 \renewcommand*\conta[1]{\texttt{\slshape#1}}
59 \providecommand\cs{}
60 \renewcommand\cs[1]{{\normalfont\texttt{\char92#1}}}
61 \renewcommand\meta[1]{{\normalfont\textlangle\textit{#1}\textrangle}}
62 \renewcommand\marg[1]{\texttt{\{\meta{#1}\}}}
63 \providecommand\Marg{}
64 \renewcommand*\Marg[1]{\texttt{\{#1\}}}
65 \providecommand\oarg{}
66 \renewcommand*\oarg[1]{\texttt{[\meta{#1}]}}
67 \providecommand\Oarg{}
68 \renewcommand*\Oarg[1]{\texttt{[#1]}}
69 \providecommand\aarg{}
70 \renewcommand*\aarg[1]{\texttt{<\meta{#1}>}}
71 \providecommand\Aarg{}
72 \renewcommand*\Aarg[1]{\texttt{<#1>}}
73 \providecommand\parg{}
74 \renewcommand*\parg[1]{\texttt{(\meta{#1})}}
75 \providecommand\Parg{}
76 \renewcommand*\Parg[1]{\texttt{(#1)}}
77 \providecommand\pack{}
78 \renewcommand*\pack[1]{{\textsf{#1}}}
79 \let\class\pack
80 \providecommand\opt{}
81 \renewcommand*\opt[1]{{\normalfont\textsl{#1}}}\let\opz\opt
82 \providecommand\env{}
83 \renewcommand*\env[1]{{\normalfont\textit{\bfseries#1}}}\let\amb\env
84
85 \providecommand\TB{\mbox{\normalfont\slshape TUGboat}\xspace}
86
87 \definecolor{verdeguit}{rgb}{0, 0.40, 0}
88 \def\GuIT{\mbox{\color{verdeguit}\def\I{\textcolor{black}{I}}%
89 \fontfamily{lmr}\fontseries{m}\fontshape{sc}\selectfont
90 g\raisebox{-0.715ex}{\kern-0.26em u}\kern-0.13em\I\kern-0.14em t}\xspace}
91 \RequirePackage{etoolbox}
92
93 \makeatletter
94
95 \AfterEndPreamble{%
96 \DeclareRobustCommand{\TeX}{T\kern-.1667em
97 \lower.5ex\hbox{E}\kern-.125emX\@\xspace}% \TeX
98 \DeclareRobustCommand{\LaTeX}{L\kern-.36em%
99 {\sbox\z@ T%
100 \vbox to\ht\z@{\hbox{\check@mathfonts
101 \fontsize\sf@size\z@
102 \math@fontsfalse\selectfont
103 A}%
104 \vss}%
105 }%
106 \kern-.15em\TeX
107 }%
108 \DeclareRobustCommand{\LaTeXe}{L\kern-.36em%
109 {\sbox\z@ T%
110 \vbox to\ht\z@{\hbox{\check@mathfonts
111 \fontsize\sf@size\z@
112 \math@fontsfalse\selectfont
113 A}%
114 \vss}%
115 }%
116 \kern-.15em\TeX\kern-0.3em$_{\textstyle\mathrm{2e}}$
117 }%
118 }
119 \makeatother
120
121 \DeclareRobustCommand*\TeXLive{\TeX\ Live\xspace}
122 \DeclareRobustCommand*\MikTeX{Mik\TeX}
123 \DeclareRobustCommand*\MacTeX{Mac\TeX}
124 \DeclareRobustCommand*\pdfLaTeX{pdf\/\LaTeX}
125 \DeclareRobustCommand*\LuaLaTeX{Lua\LaTeX}
126 \DeclareRobustCommand*\XeLaTeX{X\ifdim\fontdimen1\font=0pt
127 \kern-0.15em\fi\lower.5ex\hbox{\rotatebox[origin=c]{180}{E}}%
128 \ifdim\fontdimen1\font=0pt\kern-0.15em\else\kern-0.275em\fi
129 \LaTeX}
130 \DeclareRobustCommand*\TikZ{Ti\emph{k}Z\xspace}
131
132 %\unless\ifcsname Gr@phGrid\endcsname
133 %\let\originalGraphGrid\GraphGrid
134 %\RenewDocumentCommand\GraphGrid{r() d()}{%
135 %\IfValueTF{#1}{\put(#1){\originalGraphGrid(#2)}}%
136 % {\put(0,0){\originalGraphGrid(#2)}}}\fi
137
138 \begin{document}\errorcontextlines=100
139 \GetFileInfo{FramedSyntax.dtx}
140 \title{The \textsf{FramedSyntax} package}
141 \author{Claudio Beccari\\[1ex]\texttt{claudio.beccari(at)gmail.com}}
142 \date{Version \fileversion~--~Last revised \filedate.}
143 \maketitle
144 \columnseprule=0.4pt
145 \begin{multicols}{2}
146 \tableofcontents
147 \end{multicols}
148 \DocInput{FramedSyntax.dtx}
149 \end{document}
150 %</driver>
151 % \fi
152 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
153 % \section*{Preface}
154 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
155 %
156 % The \pack{FramedSyntax} package contains the necessary code to
157 % implement a framed block of text that is emphasised compared to
158 % the normal text. I found this technique very handy for writing
159 % the documented \TeX files that describe the new packages that
160 % I create, and the user manuals of those packages. As a member
161 % of the Italian Tug I also wrote a number of thematic guides for
162 % the Italian users; they seem to appreciate that the syntax of
163 % \LaTeX, classes and packages are written with these framed
164 % emphasised blocks, clearly emerging form the surrounding text.
165 %
166 % This is why I would like to share my package with the other
167 % \TeX users. May be they would like to use the same approach.
168 % I perfectly know that there are other packages and classes to
169 % write down documented \TeX files, such as those that
170 % traditionally have a \file{.dtx} file extension. Some of them
171 % are really powerful; I wonder why I keep using the
172 % \pack{docstrip.tex} file and the \class{ltxdoc} class to write
173 % down my documented \TeX files. The first simplest answer is
174 % “Because I am used to it”. The second is “Because I don't like
175 % to use too powerful packages, such as, for example,
176 % \pack{tikz}”; this package is a beautiful one, extremely
177 % powerful, but it is memory consuming, and computer blocking
178 % due to exhausted \TeX working memory occurred to me more often
179 % than I could stand.
180 %
181 % Dear User: if you do not like the name \pack{FramedSyntax}
182 % downloaded with a full and updated TeX System installation,
183 % copy this file to your local \texttt{texmf} directory, and
184 % change the file name to another name that fits your
185 % preferences. Never change the names of the \TeX System files
186 % even if you have the administrator privileges. In any case,
187 % since this work was inspired by a style file of mine written
188 % in Italian, this package already contains an alias
189 % \amb{Sintassi} environment with the Italian name.
190 %
191 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
192 %\section{What the \pack{FramedSyntax.sty} package can do}
193 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
194 %
195 % The user can use this package and can specify the package
196 % options; these include the colours
197 % of the frame, the text, the background; the frame thickness and
198 % colour; the frame-text gap; the text font family, series,
199 % shape, and size. These settings can be global or local,
200 % therefore you can select some of these settings for specific
201 % syntax instances.
202 %
203 % Most often than not, you'll be using the default text fonts for
204 % the whole document. Please do not use the old Computer Modern
205 % fonts; they are not scalable, but may be chosen at a discrete
206 % set of sizes. The Latin Modern ones are stepwise continuously
207 % scalable, thanks to the scalable optical sizes they are built
208 % with. Other fonts, such as the Times, the Palatino, the
209 % Libertinus ones, and many others are continuously scalable
210 % over wide ranges.
211 %
212 % While describing and commenting the code, you will read more
213 % detailed comments on such font issues.
214 %
215 % In general the syntax frame fills up the whole \cs{textwidth};
216 % in reality it should fill up the current \cs{linewidth};
217 % within a list this frame will be shorter and indented as the
218 % list text.
219 %
220 % This framed syntax box will not split across a page break;
221 % matter of facts, the next section example height is too large
222 % to fit in the page, and a large white vertical space filled
223 % this page, in order to have the framed box completely in within
224 % the next section. If you need long framed texts, you should
225 % preferably use the \pack{tcolorbox} package (which relies on
226 % the extremely powerful \pack{tikz} one) and performs much
227 % better than my simple package, in particular it can split its
228 % boxes across page breaks.
229 %
230 % Warning: This small package does similar things as the
231 % \pack{wrapfig2} package, but such packages are not supposed
232 % to interfere with each other.
233 %
234 % \begin{FramedSyntax}
235 % \texttt{\% !TEX TS-program = } \meta{LaTeX based compiler}
236 % \texttt{\% !TEX encoding = UTF-8 Unicode}
237 % ~
238 % \cs{documentclass}\oarg{options}\marg{class}
239 % \dots\ \meta{Packages}
240 % \cs{usepackage}\oarg{key=value options}\Marg{FramedSyntax}
241 % \dots\ \meta{Other packages}
242 % ~
243 % \cs{begin}\Marg{document}
244 % \dots\ \meta{A part of document body}
245 % \cs{begin}\Marg{FramedSyntax}
246 % \dots\ \meta{Some syntax lines}
247 % \cs{end}\Marg{FramedSyntax}
248 % \dots\ \meta{Further document body}
249 % ~
250 % \cs{end}\Marg{document}
251 % \end{FramedSyntax}
252 %
253 %
254 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
255 %\section{Usage example}
256 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
257 % The above framed syntax box contains a sample for using
258 % this package.\footnote{You may notice that the framed box width
259 % is a little shorter than the \cs{linewidth}, exactly 10\,pt
260 % shorter. This happens with this particular documentation class
261 % \class{ltxdoc}: I was not able to find the cause, but
262 % several tests with other classes proved to perform as
263 % expected.}
264 %
265 % In order to use this package a user should use this syntax.
266 % The above elementary example was done with the following
267 % source code.
268 %\begin{Verbatim}[gobble=1]
269 % \begin{FramedSyntax}
270 % \texttt{\% !TEX TS-program = } \meta{LaTeX based compiler}
271 % \texttt{\% !TEX encoding = UTF-8 Unicode}
272 % ~
273 % \cs{documentclass}\oarg{options}\marg{class}
274 % \dots\ \meta{Packages}
275 % \cs{usepackage}\oarg{key=value options}\Marg{FramedSyntax}
276 % \dots\ \meta{Other packages}
277 % ~
278 % \cs{begin}\Marg{document}
279 % \dots\ \meta{A part of document body}
280 % \cs{begin}\Marg{FramedSyntax}
281 % \dots\ \meta{Some syntax lines}
282 % \cs{end}\Marg{FramedSyntax}
283 % \dots\ \meta{Further document body}
284 % ~
285 % \cs{end}\Marg{document}
286 % \end{FramedSyntax}
287 %\end{Verbatim}
288 %
289 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
290 %\section{Indexing}
291 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
292 %
293 % The syntax macros can send their arguments to an \file{.idx}
294 % file. If package \pack{imakeidx} is loaded in the preamble
295 % and the \cs{makeindex} macro (with its own options) is used
296 % to activate the indexing process, the index is created
297 % without the need of manually running the necessary programs
298 % to transform the information collected into the \file{.idx}
299 % to the proper code into the \file{.ind} file.
300 %
301 % For example the following source code
302 %\begin{Verbatim}[gobble=1]
303 % % !TEX TS-program = pdflatex
304 % % !TEX encoding = UTF-8 Unicode
305 % \documentclass[12pt]{article}
306 % \usepackage{imakeidx}\makeindex
307 % \usepackage{FramedSyntax}
308 % \usepackage{kantlipsum}
309 %
310 % \begin{document}
311 % \kant[1]
312 % \begin{FramedSyntax}
313 % \cs{Large}
314 % \end{FramedSyntax}
315 %
316 % \kant[2-3]
317 % \begin{FramedSyntax}
318 % \cs{small}
319 % \end{FramedSyntax}
320 %
321 % \kant[4]
322 %
323 % \printindex
324 %
325 % \end{document}
326 %\end{Verbatim}
327 % produces a three page article containing dummy test,
328 % with a framed syntax box in each page. Both framed commands,
329 % introduced by means of the \cs{cs} command, are listed in the
330 % third page, correctly pointung to page~1 end page~2.
331 % Users are suggested to copy the above short code, save it in a
332 % testing \file{.tex} file, and compile it with \prog{pdfLaTeX};
333 % with just one run the file gets compiled together with its
334 % index.
335 %
336 % \CheckSum{650}
337 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
338 %\StopEventually{}
339 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
340 %
341 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
342 %\section{The documented code}
343 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
344 %
345 % Here the package code is defined and commented.
346 %
347 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
348 %\subsection{The necessary packages}
349 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
350 %
351 %\pack{FramedSyntax} relies on a number of other packages;
352 % they are the following:
353 % \begin{macrocode}
354 \IfPackageLoadedF{pict2e}{\RequirePackage{pict2e}}
355 \IfPackageLoadedF{etoolbox}{\RequirePackage{etoolbox}}
356 \IfPackageLoadedF{xkeyval}{\RequirePackage{xkeyval}}
357 \IfPackageLoadedF{xcolor}{\RequirePackage{xcolor}}
358 %
359 % \end{macrocode}
360 % The last three packages are loadeed for obvious reasons, since
361 % they are connected to \LaTeX programming and the package
362 % specific functionalities.
363 % May be the most puzzling one is \pack{pict2e}; it is loaded in
364 % order to use its low level commands used to draw the frame
365 % with rounded corners, i.e. the lines and the corner arcs;
366 % they can be coloured and their thickness may be specified;
367 % they form closed paths that can be stroked in a specific
368 % colour or filled with another specific colour.
369 %
370 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
371 %\subsection{The syntax macros}
372 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
373 %
374 % These numerous commands are used to typeset in a specific
375 % style the command arguments, the files, classes, packages,
376 % options names; commands, and so on. If in any source file
377 % indexing is active, each command sends the relevant information
378 % to the \file{.idx} file.
379 %
380 % All package internal commands have names that are prefixed with
381 % the string \texttt{FS}, so as to avoid conflicts with similar
382 % named commands defined by other classes or packages. These are
383 % not user commands, they are only for internal use. At the
384 % beginning of the \amb{FramedSyntax} environment all user
385 % commands (that users input without this prefix) will be let to
386 % the internal commands, so that no interference exists and
387 % no clash errors take place.
388 %
389 % Notice the non prefixed names: \cs{marg} and \cs{Marg} (and
390 % its siblings): with the lower case initial letter the
391 % syntax \emph{mandatory} argument is printed in italics
392 % surrounded by angle brackets; with an uppercase initial letter
393 % the syntax \emph{mandatory} argument is printed in teletype
394 % and is not surrounded by angle brackets.
395 % Similarly syntax \emph{optional} arguments are typeset within
396 % square brackets but the initial letter case specifies the
397 % difference between an argument to be entered by the user,
398 % and an argument with a specific value.
399 %
400 % Since initially I wrote the package for myself, some unusual
401 % object names are spelled in mixed languages: for example it is
402 % evident that \texttt{marg} stands for \emph{mandatory
403 % argument} without any language mixture; the Italian word
404 % \texttt{stile} evidently stands for the English word
405 % \emph{style}; similarly \texttt{allineamento} stands for
406 % \emph{alignement}; \texttt{numeristyle} is in mixed languages
407 % but obviously it stands for \emph{numbers style}; possibly the
408 % only one, that may puzzle a non Italian user, is the word
409 % \texttt{chiave} that stands for \emph{key}.
410 %
411 % Entries for a possible index are already created in such a way
412 % as to use the correct language for the index in Italian or the
413 % index in English. Should another user prefer to create the
414 % index in a different language, such a user is free to redefine
415 % in his/her document the indexing macros defined in this
416 % package>
417 % \begin{macrocode}
418 \providecommand*\FSmeta[1]{\textnormal{$\langle$\textit{#1}$\rangle$}}
419 \providecommand*\FSmarg[1]%
420 {\textnormal{\texttt{\char123}\FSmeta{#1}\texttt{\char125}}}
421 \providecommand*\FSoarg[1]{\textnormal{\texttt{[}\FSmeta{#1}\texttt{]}}}
422 \providecommand*\FSArg[1]{\textnormal{\texttt{\{#1\}}}}
423 \let\FSMarg\FSArg
424 \providecommand*\FSOarg[1]{\textnormal{\texttt{[#1]}}}
425 \def\GT@splitargs#1,#2!{\def\@tempA{#1}\def\@tempB{#2}}
426 \providecommand\FSgarg[1]{\textnormal{\GT@splitargs#1!\%
427 \texttt{(}\FSmeta{\@tempA}\texttt{,}\FSmeta{\@tempB}\texttt{)}}}
428 \providecommand*\FScomando[1]{\textnormal{\texttt{\string#1}}}
429 \providecommand*{\FScs}[1]%
430 {\textnormal{\texttt{\char92#1}\index{#1@\texttt{\char92#1}|textsc}}}
431 \let\FScsindex\FScs
432 %
433 \providecommand*\SFSambiente[2]{%
434 \FScomando{\begin}\FSmarg{#1}\FSoarg{#2}\,\dots
435 \FScomando{\end}\FSmarg{#1}}
436 \providecommand*\DFSambiente[3]{%
437 \FScomando{\begin}\FSmarg{#1}\FSoarg{#2}\FSoarg{#3}\,\dots
438 \FScomando{\end}\FSmarg{#1}}
439 \providecommand*\BFSambiente[1]{\FScomando{\begin}\FSmarg{#1}}
440 \providecommand*\EFSambiente[1]{\FScomando{\end}\FSmarg{#1}}
441 \IfPackageLoadedF{cfr-lm}{\let\texttm\texttt \let\texttv\texttt}
442 %
443 \DeclareRobustCommand*\FSambstyle[1]{%
444 {\normalfont\textsf{\slshape#1}}}
445 \DeclareRobustCommand*\FSclassstyle[1]{%
446 {\normalfont\texttv{\itshape#1}}}
447 \DeclareRobustCommand*\FSfilestyle[1]{%
448 {\normalfont\texttm{\texttt{#1}}}}
449 \DeclareRobustCommand*\FSpackstyle[1]{%
450 {\normalfont\texttm{\ifbool{PDFTeX}{\textit}{\itshape}{#1}}}}%
451 \DeclareRobustCommand*\FSprogstyle[1]{{\normalfont\textsf{#1}}}
452 \DeclareRobustCommand*\FSprog[1]{\FSprogstyle{#1}%
453 \iflanguage{english}{\index{program!#1@\FSprogstyle{#1}|textsc}}%
454 {\index{programma!#1@\FSprogstyle{#1}|textsc}}}%
455 \DeclareRobustCommand*\FSpack[1]{\FSpackstyle{#1}%
456 \iflanguage{english}{\index{package!#1@\FSpackstyle{#1}|textsc}}%
457 {\index{pacchetto!#1@\FSpackstyle{#1}|textsc}}}
458 \DeclareRobustCommand*\FSclass[1]{\FSclassstyle{#1}%
459 \iflanguage{english}{\index{class!#1@\FSclassstyle{#1}|textsc}}%
460 {\index{classe!#1@\FSclassstyle{#1}|textsc}}}%
461 \DeclareRobustCommand*\file[1]{\FSfilestyle{#1}%
462 \index{file!#1@\FSfilestyle{#1}|textsc}}%
463 \DeclareRobustCommand*\FSamb[1]{\FSambstyle{#1}%
464 \iflanguage{english}%
465 {\index{environment!#1@\FSambstyle{#1}|textsc}}%
466 {\index{ambiente!#1@\FSambstyle{#1}|textsc}}}%
467 \DeclareRobustCommand*\FSopzstyle[1]{%
468 {\normalfont\textsf{\slshape{#1}}}}%
469 \DeclareRobustCommand*\FScontastyle[1]{{\normalfont\texttm{#1}}}
470 \DeclareRobustCommand*\FSstilestyle[1]{{\normalfont\texttm{#1}}}
471 \DeclareRobustCommand*\FSnumeristyle[1]{{\normalfont\texttm{#1}}}
472 \DeclareRobustCommand*\FSumisurastyle[1]{{\normalfont\texttm{#1}}}
473 \DeclareRobustCommand*\FSchiavestyle[1]{{\normalfont\texttm{#1}}}
474 \DeclareRobustCommand*\FSdescrittorestyle[1]{{\normalfont\texttm{#1}}}
475 \DeclareRobustCommand*\FSposizionestyle[1]{{\normalfont\texttm{#1}}}
476 \DeclareRobustCommand*\FSallineamentostyle[1]{{\normalfont\texttm{#1}}}
477 %
478 \DeclareRobustCommand*\FSopz[1]{\opzstyle{#1}%
479 \iflanguage{english}{\index{option!#1@\FSopzstyle{#1}|textsc}}%
480 {\index{opzione!#1@\opzstyle{#1}|textsc}}}%
481 \DeclareRobustCommand*\FSconta[1]{\Fcontastyle{#1}%
482 \iflanguage{english}{\index{counter!#1@\FScontastyle{#1}|textsc}}%
483 {\index{contatore!#1@\FScontastyle{#1}|textsc}}}
484 \DeclareRobustCommand*\FSstile[1]{\FSstilestyle{#1}%
485 \iflanguage{english}{\index{page style!#1@\FSstilestyle{#1}|textsc}}%
486 {\index{stile della pagina!#1@\FSstilestyle{#1}|textsc}}}
487 \DeclareRobustCommand*\FSnumeri[1]{\FSnumeristyle{#1}%
488 \iflanguage{english}{\index{numbering!#1@\FSnumeristyle{#1}|textsc}}%
489 {\index{numerazione!#1@\FSnumeristyle{#1}|textsc}}}
490 \DeclareRobustCommand*\FSumisura[1]{\FSumisurastyle{#1}%
491 \iflanguage{english}{measuring unit!#1@\FSumisurastyle{#1}|textsc}%
492 {\index{unità di misura!#1@\FSumisurastyle{#1}|textsc}}}
493 \DeclareRobustCommand*\FSchiave[1]{\FSchiavestyle{#1}%
494 \iflanguage{english}{\index{key!#1@\FSchiavestyle{#1}|textsc}}%
495 {\index{chiave!#1@\chiavestyle{#1}|textsc}}}
496 \DeclareRobustCommand*\FSdescrittore[1]{\FSdescrittorestyle{#1}%
497 \iflanguage{english}%
498 {\index{column descriptor!#1@\FSdescrittorestyle{#1}|textsc}}%
499 {\index{descrittore di colonna!#1@\FSdescrittorestyle{#1}|textsc}}}
500 \DeclareRobustCommand*\FSposizione[1]{\FSposizionestyle{#1}%
501 \iflanguage{english}%
502 {\index{floating object position!#1@\FSposizionestyle{#1}|textsc}}%
503 {\index{posizione degli oggetti flottanti!#1@\FSposizionestyle{#1}|textsc}}}%
504 \DeclareRobustCommand*\FSallineamento[1]{FS\allineamentostyle{#1}%
505 \iflanguage{english}%
506 {\index{allignment code!#1@\FSallineamentostyle{#1}|textsc}}%
507 {\index{codice di allineamento!#1@\FSallineamentostyle{#1}|textsc}}}
508 %
509 % \end{macrocode}
510 %
511 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
512 %\subsection{Register and colour definitions}
513 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
514 %
515 % Here we define some length and dimension registers.
516 % They will be used by the local commands and environments.
517 % Length \cs{insertwidth} might be already defined, therefore we
518 % test this possibility.
519 % \begin{macrocode}
520 \newlength\SIfrthick
521 \newlength\SIfrgap
522 \newlength\SIfrwidth
523 \newlength\SIfrheight
524 \ifcsdef{insertwidth}{}{\newlength\insertwidth}
525 \newlength\SIXR \newlength\SIYD
526 \newlength\SIXL \newlength\SIYU
527 \newdimen\radius
528 \newdimen\framewidth
529
530 \definecolor{SIbackground}{rgb}{0.95,0.95,0.95}
531 \definecolor{SIframe}{rgb}{0.1,0.1,0.1}
532 \definecolor{SItext}{rgb}{0,0,0}
533
534 % \end{macrocode}
535 % The default background color is a very light gray; the default
536 % frame colour is a very dark gray; the default text colour is
537 % just black. Such colours are deemed suitable for the
538 % application of the framed syntax box, but when necessary users
539 % can use the \cs{textcolor} command to emphasise specific
540 % phrases.
541 %
542 % As it can be seen, these colours are defined by means of the
543 % colour defining macros of the \pack{xcolor} package.
544 % They define some default colours; but the next commands
545 % redefine them at the user choice; actually the user shall
546 % specify some \textit{key = value} options to the main syntax
547 % environment.
548 % \begin{macrocode}
549 \def\SetSIbgd#1{\colorlet{SIbackground}{#1}}
550 \def\SetSIfrm#1{\colorlet{SIframe}{#1}}
551 \def\SetSItxt#1{\colorlet{SItext}{#1}}
552
553 % \end{macrocode}
554 %
555 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
556 %\subsection{Option settings}
557 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
558 %
559 % The next code is the strength of the package; the definition
560 % of the option settings. They form an option family defined by
561 % the angle brackets delimited string \texttt{sintassi}.
562 % Therefore they cannot be redefined by any other class or
563 % package unless the above family name is used.
564 % \begin{macrocode}
565 \DeclareOptionX<sintassi>{fboxrule}[1pt]{\fboxrule=#1}
566 \DeclareOptionX<sintassi>{fboxsep}[1ex]{\fboxsep=#1}
567 \DeclareOptionX<sintassi>{framecolor}[SIframe]{\SetSIfrm{#1}}
568 \DeclareOptionX<sintassi>{backgroundcolor}[SIbackground]{\SetSIbgd{#1}}
569 \DeclareOptionX<sintassi>{fontstyle}[\normalfont]{#1}
570 \DeclareOptionX<sintassi>{radius}[\fboxsep]{\radius=#1}
571 \DeclareOptionX<sintassi>{insertionwidth}[\linewidth]{\insertwidth=#1}
572
573 \DeclareOptionX*{%
574 \packageWarning{FramedSyntax}{`\CurrentOption' ignored}%
575 }
576
577 % \end{macrocode}
578 % Notice that the option defining macro \cs{DeclareOptionX}
579 % is created by the \pack{keyvalue} package in a simplified way,
580 % so as to imitate the \LaTeXe syntax.
581 %
582 %
583 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
584 %\subsection{Activate all options}
585 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
586 % With just two macros we activate all options of family
587 % \texttt{sintassi}
588 % \begin{macrocode}
589 \ExecuteOptionsX<sintassi>{%
590 fboxrule,
591 fboxsep,
592 framecolor,
593 backgroundcolor,
594 fontstyle,
595 radius,
596 insertionwidth
597 }
598 \ProcessOptionsX*\relax
599
600 % \end{macrocode}
601 %
602 %
603 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
604 % \subsection{A couple of useful local macros}
605 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
606 % The following macros are generally useful for the end users;
607 % the first one provides a simple means to scale the font size
608 % to any specified integer or fractional value. It comes useful
609 % when a line contained in a framed syntax box is too long and
610 % gets broken at the end of the box measure. According where the
611 % line is broken there are two ways to correct the source file:
612 %\begin{itemize}
613 %\item
614 % the user choses the best point where to break the line,
615 % inserts an explicit comment character (|\%|)
616 % at the end of the broken line and inserts a horizontal space
617 % at the beginning of the remaining part of the broken line.
618 %\item
619 % At the beginning of the environment body the user may insert a
620 % \cs{setfontsize} selecting the specific font size at a smaller
621 % integer or fractional value than the normal text size.
622 %\end{itemize}
623 % This \cs{setfontsize} macro accepts two different syntaxes in
624 % order to reach the same result: For example:
625 %
626 %\verb|\setfontsize{9.5}[1.1]|\par
627 %\verb|\setfontsize[1.1]{9.5}|
628 %
629 % In any case the base line skip value is optional and its
630 % default value is 1.2 times the font size. Actually the
631 % optional value is not the base line skip value, but it is
632 % the \cs{linestretch} value, i.e. the ratio between the desired
633 % base line skip and the font size.
634 %
635 % The second macro exploits the \pack{etoolbox} functionalities
636 % to define a user macro that activates an internal native \TeX
637 % macro protected by a |%| character.
638 % \begin{macrocode}
639 \providecommand\setfontsize{}
640 \RenewDocumentCommand\setfontsize{O{1.2} m O{#1}}{%
641 \fontsize{#2}{\fpeval{#1*#2}}\selectfont}
642
643 \providecommand\strippt{}
644 \renewcommand\strippt[1]{\csuse{strip@pt}#1}
645
646 % \end{macrocode}
647 %
648 %
649 %
650 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
651 % \subsection{The framed box requires several settings}
652 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
653 %
654 % The following macro \cs{framedbox} in a certain sense is the
655 % heart of the whole construction of the \amb{FramedSyntax}
656 % environment. It requires 5 arguments, four mandatory ones and
657 % one optional. In order they are as follows
658 % \begin{enumerate}
659 % \item[\texttt{\#1}]
660 % mandatory: the width of the box/
661 %
662 % \item[\texttt{\#2}]
663 % mandatory: the thickness of the frame.
664 %
665 % \item[\texttt{\#3}]
666 % mandatory: the gap width between the frame and the contents
667 % of the box.
668 %
669 % \item[\texttt{\#4}]
670 % optional: the radius of curvature of the box corners.
671 %
672 % \item[\texttt{\#5}]
673 % mandatory: the text to be included within the framed box
674 % \end{enumerate}
675 % Although the corner radius may be chosen, it is suggested to
676 % avoid specifying this optional parameter; its default value
677 % equals the gap width; if the frame thickness is zero, macro
678 % avoids tracing a frame with an invisible line.
679 % \begin{macrocode}
680 \providecommand\framedbox{}
681 \RenewDocumentCommand\framedbox{m m m O{#3} m}{%
682 \bgroup
683 \dimen2=#1\relax
684 \dimen0=\dimexpr#1-(#2+#3)*2\relax
685 \setbox0\hbox{\parbox{\dimen0}{#5}}%
686 \SIfrthick=#2\relax
687 \SIXR=\dimexpr\wd0/2\relax \SIXL=-\SIXR\relax
688 \SIYU=\dimexpr(\ht0+\dp0)/2\relax \SIYD=-\SIYU\relax
689 \dimen4=#1\relax % box total width
690 \dimen6=\dimexpr\ht0+\dp0+(#2+#3)*2\relax% box total height
691 \dimen8=#4\relax % corner arc radius
692 \edef\SIbase{\strippt{\dimen4}}
693 \edef\SIalt{\strippt{\dimen6}}
694 \edef\SIxoff{\strippt{\dimexpr0.5\dimen4}}
695 \edef\SIyoff{\strippt{\dimexpr0.5\dimen6}}
696 \unitlength=1pt
697 \begin{picture}(\SIbase,\SIalt)(-\SIxoff,-\SIyoff)
698 \Frame*{\dimen4}{\dimen6}{\dimen8}%
699 \ifdim\SIfrthick>0pt\Frame{\dimen4}{\dimen6}{\dimen8}\fi
700 \put(0,0){\makebox(0,0){\box0}}%
701 \end{picture}
702 \egroup
703 \ignorespaces}
704
705 % \end{macrocode}
706 %
707 %
708 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
709 % \subsection{The frame}
710 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
711 %
712 % The actual frame path may be filled with colour; the frame
713 % border may be coloured with its own specified colour; such
714 % colours are established by the FramedSyntax environment
715 % options or by the global options.
716 %
717 % The \cs{Frame} command requires four parameters already
718 % computed by the \cs{framedbox} command; in any case they are
719 % the following:
720 % \begin{enumerate}
721 % \item[\texttt{\#1}]
722 % optional: a boolean asterisk; if the asterisk is missing the
723 % frame contour is drawn with its colour \texttt{SIframe}; if
724 % the asterisk is present the contour is not drawn, but the
725 % framed box is filled with the \texttt{SIbackground} colour.
726 % \item[\texttt{\#2}]
727 % mandatory: overall box width.
728 % \item[\texttt{\#3}]
729 % mandatory: total box height.
730 % \item[\texttt{\#4}]
731 % mandatory: the corner arc radius.
732 % \end{enumerate}
733 %
734 % The following code contains the low level \pack{pict2e}
735 % commands to draw lines to form a closed path to be stroked or
736 % colour filled. They do not form a \pack{pict2e} \cs{oval},
737 % although the contour is similar, because the default \cs{oval}
738 % cannot be filled.
739 % \begin{macrocode}
740 \providecommand\Frame{}
741 \RenewDocumentCommand\Frame{s m m m}{%
742 \bgroup
743 \SIXR=\dimexpr#2/2\relax \SIXL=-\SIXR%
744 \SIYU=\dimexpr#3/2\relax \SIYD=-\SIYU%
745 \IfBooleanTF{#1}{\linethickness{0pt}\color{SIbackground}}%
746 {\linethickness{\SIfrthick}\color{SIframe}}%
747 \moveto(\SIXR,\SIYD+#4)%
748 \circlearc{\SIXR-#4}{\SIYU-#4}{#4}{0}{90}%
749 \circlearc{\SIXL+#4}{\SIYU-#4}{#4}{90}{180}%
750 \circlearc{\SIXL+#4}{\SIYD+#4}{#4}{180}{270}%
751 \circlearc{\SIXR-#4}{\SIYD+#4}{#4}{270}{360}%
752 \closepath
753 \IfBooleanTF{#1}{\fillpath}{\strokepath}%
754 \egroup\ignorespaces}
755
756 % \end{macrocode}
757
758 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
759 % \subsection{Filling the frame with the syntax text}
760 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
761 %
762 % We are almost at the end. Here we define another macro to put
763 % the syntax text inside the frame over the background
764 % colour. The next command \cs{includeframedtext} provides the
765 % necessary arguments to be passed to the lower level command
766 % \cs{framedbox}; the arguments are the following:
767 % \begin{enumerate}
768 % \item[\texttt{\#1}]
769 % optional: box width; default value \cs{insertwidth}, which is
770 % the actual boxed text width; if it is larger than
771 % \cs{linewidth} it is reduced to this value; in this case
772 % users should revise they source code in order to fix this
773 % little problem.
774 % \item[\texttt{\#2}]
775 % mandatory: the syntax text to be framed.
776 % \item[\texttt{\#3}]
777 % optional: the local \textit{key = value} options.
778 % \end{enumerate}
779 %
780 % The code is the following.
781 % \begin{macrocode}
782 \providecommand\includeframedtext{}
783 \RenewDocumentCommand\includeframedtext{O{\insertwidth} m O{}}%
784 {\bgroup
785 \ExecuteOptionsX<sintassi>{#3}%
786 \ifdimgreater{\insertwidth}{\linewidth}{\insertwidth=\linewidth}{}%
787 \framedbox{\insertwidth}{\fboxrule}{\fboxsep}[\radius]{#2}%
788 \egroup}
789
790 % \end{macrocode}
791 %
792 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
793 % \subsection{The user environment}
794 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
795 % Originally this environmente was named \amb{Sintassi}, but in
796 % this package we name it \amb{FramedSintax}. The opening
797 % statement is very long, because it must contain all the
798 % \cs{let} commands that allow the user to use the command names
799 % without the \texttt{FS} prefix; such \cs{let} equivalences are
800 % local because the \texttt{FS} prefixes were introduced only to
801 % avoid clashes with possible definitions of the same names with
802 % other purposes.
803 %
804 % But besides these numerous equivalences, this environment
805 % \amb{FramedSyntax} determines the necessary parameters to pass
806 % to the service macros
807 %
808 % The environment requires just two optional arguments.
809 % \begin{enumerate}
810 % \item[\texttt{\#1}]
811 % optional: the font size. The default value is the current
812 % font size. This size should be specified only when the syntax
813 % lines are marginally longer than the available measure and
814 % they get broken close to their natural length. Please,
815 % remember that in order to have this size specification work
816 % properly, it is necessary to use continuously scalable fonts.
817 % This command will not have any useful effect with the original
818 % \TeX default Computer Modern fonts; Latin Modern fonts, on
819 % the contrary, work very well.
820 % \item[\texttt{\#2}]
821 % optional: \textit{key = value} options that locally override
822 % the global default ones or those that possibly were
823 % specified by the user when loading this package.
824 % \end{enumerate}
825 % \begin{macrocode}
826 \ProvideDocumentEnvironment{FramedSyntax}{}{}{}
827 \RenewDocumentEnvironment{FramedSyntax}{o D(){}}
828 {% environment opening commands
829 \IfValueT{#1}{\setfontsize{#1}}% font size setting
830 \ExecuteOptionsX<sintassi>{#2}% key = value options
831 \ifdimgreater{\insertwidth}{\linewidth}% width corrrection
832 {\insertwidth=\linewidth}{}%
833 \framewidth=\insertwidth
834 %
835 \let\meta\FSmeta \let\marg\FSmarg \let\oarg\FSoarg
836 \let\Arg\FSArg \let\Marg\FSMarg \let\Oarg\FSOarg
837 \let\garg\FSgarg \let\comando\FScomando \let\cs\FScs
838 \let\csindex\FScs \let\Sambiente\SFSambiente
839 \let\Dambiente\DFSambiente
840 \let\Bambiente\BFSambiente \let\Eambiente\EFSambiente
841 \let\amb\FSamb \let\ambstyle\FSambstyle
842 \let\class\FSclass \let\classstyle\FSclassstyle
843 \let\file\FSfile \let\filestyle\FSfilestyle
844 \let\pack\FSpack \let\packstyle\FSpackstyle
845 \let\prog\FSprog \let\progstyle\FSprogstyle
846 \let\opz\FSopz \let\opzstyle\FSopzstyle
847 \let\conta\FSconta \let\contastyle\FScontastyle
848 \let\stile\FSstile \let\stilestyle\FSstilestyle
849 \let\numeri\FSnumeri \let\numerystyle\FSnumeristyle
850 \let\umisura\FSumisura \let\umisurastyle\FSumisurastyle
851 \let\chiave\FSchiave \let\chiavestyle\FSchiavestyle
852 \let\descrittore\FSdescrittore
853 \let\descrittorestyle\FSDescrittorestyle
854 \let\posizione\FSposizione \let\posizionestyle\FSposizionestyle
855 \let\allineamento\FSallineamento
856 \let\allineamentostyle\FSallineamentostyle
857
858 %
859 \begin{lrbox}{2}% open the necessary boxes
860 \begin{minipage}{%
861 \dimexpr\framewidth-2\fboxrule-2\fboxsep}\obeylines
862 }{% environment closing commands
863 \end{minipage}\end{lrbox}% close the above boxes
864 \begin{flushleft}% set the syntax thext flush left
865 \includeframedtext{\box2}[#2]
866 \end{flushleft}}%
867
868 % \end{macrocode}
869 %
870 %
871 %
872 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
873 % \subsection%{Backwards compatibility environment \amb{Sintassi}}
874 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
875 %
876 % As said in the Preface, this package was inspired by a
877 % \file{.sty} file of mine written in Italian; I might conserve
878 % my older file but, since it is not so safe against macro
879 % definition clashes, in the several document source files I
880 % wrote with the previous implementation. I am going to change
881 % the name of the imported file, but I will conserve the
882 % multitude of instances of the old environment name, by an
883 % alias defined in this package.
884 % \begin{macrocode}
885 \NewDocumentEnvironment{Sintassi}{o D(){}}%
886 {\begin{FramedSyntax}[#1](#2)}{\end{FramedSyntax}}
887 % \end{macrocode}
888 %.
889 %
890 %\iffalse
891 %<*package>
892 %\fi
893 %
894 % \begin{center}\color{red}\fontsize{50}{50}\selectfont
895 % Enjoy \LaTeX
896 %\end{center}
897 %\iffalse
898 %</package>
899 %\fi
900 % \Finale
901
902 \endinput
903
904 %
905 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
906 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
907 %
908 %
909 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
910 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
911 %
912 %
913 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
914 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
915 %
916 %
917 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
918 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
919 %
920 %
921 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
922 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
923 %
924 %
925 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
926 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
927 %
928 %
929 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
930 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%