diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/examplep/eurotex_2005_examplep.tex')
-rw-r--r-- | Master/texmf-dist/doc/latex/examplep/eurotex_2005_examplep.tex | 1848 |
1 files changed, 1848 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/examplep/eurotex_2005_examplep.tex b/Master/texmf-dist/doc/latex/examplep/eurotex_2005_examplep.tex new file mode 100644 index 00000000000..e6052aca4db --- /dev/null +++ b/Master/texmf-dist/doc/latex/examplep/eurotex_2005_examplep.tex @@ -0,0 +1,1848 @@ +% +% eurotex_2005_examplep.tex +% by pts@fazekas.hu at Thu Nov 11 20:44:25 CET 2004 +% -- Wed Jan 12 00:42:06 CET 2005 +% +% Dat: this is the supposed final version of the article, without corrections +% Dat: required houses.{eps,pdf} pexaminipage.{eps,pdf} shorthyp_t1xtts.{eps,pdf} +% Dat: auxilary files: eurotex_2005_examplep.bib ttt.tex +% OK: eliminate Overfull \hbox{}es +% OK: submit to CTAN +% + +\documentclass[a4paper]{article} +\usepackage[latin2]{inputenc}% Dat: because of `á' etc.; also ÷ +\usepackage{t1enc} +\usepackage{booktabs} +\usepackage{graphicx}% Dat: after Babel +\usepackage{mflogo} + +% Dat: for \documentclass[a4paper]{article} +\special{\string!\expandafter\expandafter\csname @gobble\endcsname + \string\%xdvi.dvo: -expert -s 6 -xoffset -1.54cm -yoffset -1.54cm + -paper 12.8cmx23cm} % -xoffset 7mm -yoffset 13mm -paper 385ptx576pt} + +\title{Verbatim phrases and listings in {\LaTeX}} +\author{P\'eter Szab\'o $\langle$\texttt{pts@fazekas.hu}$\rangle$ +\thanks{Thanks to Ferenc Wettl for the fruitful long discussion about the +line syntax of the \texttt{code} environment, and also for reviewing the +article.} +\\[3pt]%\par\smallskip +\normalsize Budapest University of Technology and Ecomomics,\\[-3pt] +\normalsize Department of Analysis,\\[-3pt] +\normalsize M\H{u}egyetem rakpart 3--9.,\\[-3pt] +\normalsize Budapest, Hungary H-1111} +\date{2004-11-11} + +\def\verbatizee#1{\begingroup\ttfamily + \toks0{#1}\edef\next{\the\toks0}% + %\dimen0=\the\fontdimen2\font % Dat: disable spaces, `=' is required here + \dimen0\fontdimen2\font % Dat: disable spaces, `=' is required here + %\showthe\dimen0 + \fontdimen2\font=0pt + {\expandafter\stripit\meaning\next}% Dat: grouping to keep \dimen0 + \unskip % Dat: strip final space, possibly after command + \fontdimen2\font=\dimen0 + %\showthe\dimen0 + \endgroup} +\def\next{} +\expandafter\def\expandafter\stripit\meaning\next{} + +%** So \verb+÷+ works. +\DeclareInputText{247}{\ensuremath{\div}} + +\belowcaptionskip0pt + +\begin{document} + +\maketitle + +\begin{abstract} + + The \textsf{examplep} package written by the author recently provides + sophisticated features for typesetting verbatim source code listings, + including the display of the source code and its compiled \LaTeX{} or + \textsf{METAPOST} output side-by-side, with automatic width detection and + enabled page breaks (in the source), without the need for specifying the + source twice. Special care is taken so section, page and footnote numbers + do not interfere with the main document. For typesetting short verbatim + phrases, a replacement for the \verb+\verb+ command is also provided + in the package, which can be used inside tables and moving arguments such as + footnotes and section titles. The listings package is used for syntax + highlighting. + + The article reviews the design decisions + made during the package development and also presents some interesting + implementation internals. \textsf{examplep} is compared to standard + \LaTeX{} packages such as \textsf{listings}, \textsf{ltxdoc}, + \textsf{sverb} and \textsf{moreverb}. The new \textsf{codep} package and + its accomanying \textsf{Perl} script, + which provide a convenient interface to the \textsf{examplep} package for + authors of manuals, is also presented. With \textsf{codep} it is possible + to generate the source code, the \LaTeX{} or \textsf{METAPOST} output and + the compilable example file onto the CD from a single source embedded + into the appropriate place of the \texttt{.tex} document file. +%%%WF A CD-re irasnak semmi koze a lenyeghez, sajnos a dolgozat +%%% hatralevo reszeben is folyton CD-file es egyebekrol szolsz, de +%%% valojaban csak arrol van szo, hogy kulon file-ba irjuk a +%%% futtathato kodot (amit aztan a web-re, CD-re, DVD-re... lehet tenni). +%% -- kellett neki nevet adni, ez lett +\end{abstract} + + +\section{Terminology} + +\begin{description} + +\item[verbatim text] A visually distinguishable textual part of the + document (usually typeset with a monospaced, or typewriter font) that is + allowed to contain the full ASCII character set. Verbatim text is often + used to typeset parts of program source files, including \TeX{} source. + Verbatim text must be marked up (i.e.\ surrounded) + in the source of the \LaTeX{} + document, so backslash and other control characters are typeset verbatim + instead of being interpreted as commands or special \LaTeX{} characters. + +%%%WF a kovetkezo 2 def nem pontos, nem biztos, hogy paragrafusok kozt +%%% van a kiemelt verbatim. Sorban? vagy sorok kozt van? +%% -- lehetne még pontosítani, de szerintem ebből rögtön lehet tudni, mire +%% gondolok +\item[inline verbatim] A verbatim text passage inside a paragraph + or table cell. + +\item[display verbatim] is a vertical verbatim text block between + paragraphs. + +\item[side-by-side display] + When typesetting program source in a display verbatim, it is often + desirable to show the output of the program as well. This is especially + useful when teaching scripting languages, so the reader can see the + command and its effect side-by-side in a quick glance. For \TeX{} or + \textsf{METAPOST} sources and EPS and PDF source files it is also useful to + see the source and the typeset result side-by-side. + +\item[Source and Sample] + Side-by-side displays can be divided to \emph{Source} and \emph{Sample}, + the latter being program output or typeset material. + +\item[CD-files] + Files accompanying a book, usually on a CD or DVD shipped with the book, + or avalable for download on the home page of the book. These + files usually contain some of the display verbatim material in the book, + so readers do not have to retype them. + +\end{description} + +\section{Special characters in the \LaTeX{} source} + +The special meaning of the input characters in the source file must be +disabled in verbatim mode -- except for the character(s) that delimit the end +of the verbatim text. The following characters have to be dealt with: + +\begin{description} + +\item[ASCII symbols] The ligatures have to be disabled, especially \verb+?`+ $\to$ +\texttt{?`} etc. The safest way is to make both characters of such a ligature +active, and %then +defining \verb+\def?{\relax\string?\relax}+ +and \verb+\def`{\relax\string`+\allowbreak\verb+\relax}+. \hskip0pt +minus3.3pt\relax \textsf{examplep} issues similar +definitions covering all such ligatures in the OT1- and T1-encoded CM fonts. + +\item[ASCII letters] Most verbatim fonts don't contain the ``fi'' or similar +ligatures, so \textsf{examplep} takes no care to disable them. + +\item[special \TeX{} source symbols] To disable the special meaning of the symbols +\verb+\+ +\verb-{- +\verb-}- +\verb+$+ %%%$ +\verb+%+ +\verb+^+ +\verb+&+ +\verb+_+, +\textsf{examplep} redefines their \verb+\catcode+ for display verbatim. +However, catcode changes are not always appriopriate for inline verbatim, +so \textsf{examplep} provides \verb+\÷+ (see below) which doesn't change +catcodes at all. + +\item[other ASCII punctuation] Some of these characters (% +\verb+[+ +\verb+]+ +\verb+;+ +\verb+'+ +\verb+,+ +\verb+.+ +\verb+/+ +\verb+~+ +\verb+!+ +\verb+@+ +\verb+*+ +\verb+(+ +\verb+)+ +\verb-+- +\verb-|- +\verb-:- +\verb-"- +\verb-<- +\verb->- +\verb-?- +\verb+`+ +\verb+-+ +\verb+=+) may be active, for example, \verb+~+ is ÷\nobreakspace÷, +\verb+`+ is a Babel shorthand (e.g.\ in the Hungarian language module, +\textsf{magyar.ldf}); \verb+"+ is a Babel shorthand (e.g\ in the German +language module); \verb+?+, \verb+!+, \verb+:+ and \verb+;+ are activated +(e.g.\ by the French language module), and other characters may be activated, +too. So \textsf{examplep} sets the catcode of all characters in the range +$33\ldots126$ to other (12). This includes all ASCII punctuation, letter and +digit characters. + +\item[double carets] For example, the letter +``J'' can be input as its ASCII code in hex, +prefixed by double carets: \verb+^^4a+. However, in verbatim mode we want the +4 characters, not the letter {J}. There is no problem in inline verbatim +mode, because \verb+^+ loses its special meaning once its catcode is changed. +However, when the verbatim material is written to a file or to the terminal, +\TeX{} may change ``unprintable'' characters to escapes prefixed by \verb+^^+. +These changes must be reverted when reading the file back. See Subsection +\ref{tcx} for more. + +\item[high characters] Input characters in the range $128\ldots255$ are +usually activated by the \textsf{inputenc} package, and they know how to +typeset themselves -- so \textsf{examplep} leaves the catcode of such +characters intact. However, in some modes, \textsf{examplep} has already +changed all catcodes to 12 and 10 (with \verb+\meaning+), so it has to change +the catcodes of such high codes back to 13 (active). + +\end{description} + +\section{Features of \textsf{examplep}} + +These are the most important, unique features: + +\begin{itemize} + +\item layout of side-by-side display may depend on maximum Source width +\item automatic hyphenation of inline verbatim. The text is divided into + words and punctuation symbols (based on catcodes). For words, the normal + \TeX{} hyphenation patterns apply, and it is allowed to break the line on + both sides of a punctuation symbol. +\item customizable isolation of page, section etc.\ numbers in the Sample + and the host document with the \texttt{PexaMiniPage} environment +\item besides the outer level, inline verbatim (when properly escaped inside + \verb+\Q+ or \verb+\÷+) works safely inside macro arguments, section + titles, footnotes, table cells and index entries +\item generated CD-files with automatic page and chapter number +\item writing verbatim data to CD-files with a \textsf{Perl} script; exact, + binary reproduction of verbatim text is guaranteed +\item ability to write different material to Source, Sample and CD-files +\item the accents \verb+\H+ and \verb+\.+ work as expected with monospaced + fonts in the OT1 encoding. By default, \verb+\texttt{\H o}+ produces + \hbox to0pt{\verb+}+\hss}\verb+o+ in OT1 encoding, because such + typewriter fonts (such as \textit{cmtt10}) have those accents +%%%WF repaced + replaced + by ASCII symbols. \textsf{examplep} solves the problem by getting the + accent from the \textit{cmr} font family. + +\end{itemize} + +\noindent Some other features: + +\begin{itemize} + +\item side-by-side display of the Source and the Sample +\item between-word hypenation of inline verbatim +\item customizable left and right indentation of display verbatim +\item specifying inline verbatim with nested braces (\verb+\PVerb+, + \verb+\Q+) or terminating character (\verb+\PVerb+, \verb+÷+, \verb+\÷+) +\item automatic line breaks with hyphenation in display verbatim +\item the discretionary hyphen (\verb+\hyphenchar+) of verbatim text is + different from the one in normal text +\item line numbering in display verbatim +\item writing to temporary files only if needed +\item reading back contents of any file in display verbatim +%\item writing verbatim data to temporary files (\verb+^+\relax\verb+^+ab, .tcx) +% Dat: not a feature: automatic \textsf{METAPOST} processing, see the \texttt{eempost} package +\item inline verbatim with a single character ($\div$) and its escaped + version (\textbackslash$\div$ and \verb+\Q+) +\item automatic \verb+\indent+\allowbreak/\allowbreak\verb+\noindent+, + based on empty line above \verb+\begin{...}+ +\item ISO Latin accented input character support in all modes (also present + in \verb+\verb+) +\item support for syntax highlighting with the \textsf{listings} package + \cite{listings} +%%%WF a (\cite{...}) kicserelendo \cite{...} -re az EGESZ DOLGOZATBAN, +%%% nem kell kerek zarojel, ott van mar a szogletes +%% -- javítva +\item emits a tab as eight spaces in normal mode, but tabs are supported + properly with \texttt{ttlistings=yes} and \texttt{ttlistings=showtabs} +\item simple side-by-side display emulation without temporary files, + using \texttt{src\allowbreak style=leftboth} or \texttt{srcstyle=leftleft} + +\end{itemize} + + +\subsection{Escaped mode of inline verbatim locations}\label{escaped} + +For compatibility reasons, \textsf{examplep} doesn't change the original +%%%WF ÷\verb+ and ÷\verb*+ +\verb+\verb+ and \verb+\verb*+ +%%% +commands in any way, but defines its own commands: +\verb+\PVerb+, \verb+\PVerbH+, \verb+\PVerbInner+, +\verb+\PVerbOpt+, \verb+\Q+, \verb+÷+ and \verb+\÷+. Most of the +\verb+\PVerb+\ldots{} +commands are historical. For new documents, only the use of +\verb+\PVerbOpt+, \verb+\Q+, \verb+÷+ and \verb+\÷+ is recommended. Some of +these commands have to be activated with package load options: +\verb+\usepackage[Q=yes,div=yes,bsdiv=yes]{examplep}+. The reason why +\verb+÷+ was introduced is that it is a high Latin-1 (and Latin-2) character +available on the Hungarian keyboard, which is usually not used in \LaTeX{} +documents (in fact, \verb+$\div$+ is used instead). Inline verbatim sources +with such a character are compact, and they can contain all ASCII symbols. + +\begin{table} +\caption{Contexts and features of inline verbatim commands}\label{contexts} +\vskip\abovecaptionskip +\small +\noindent\hfil\begin{tabular}{@{}llllll@{}}\toprule + & outer& argument& tablular& elsewhere& escaped \\\midrule +\verb+\verb+ & + & $-$$^1$ & + & $-$$^1$ & no \\ +\verb+\PVerbOpt+ & + & +$^2$ & + & $-$ & no \\ +\verb+÷+ & + & +$^2$ & $-$ & +$^2$ & no \\ +\verb+\÷+ & + & + & + & + & yes \\ +\verb+\Q+ & + & + & + & + & yes \\ +\bottomrule +\end{tabular} +\par\smallskip +$^1$sometimes displays the proper error message\par +$^2$inner mode only (spaces compressed or lost, \verb+%+ is comment etc.) +\end{table} + +\textsf{examplep} supports inline verbatim text at the outer level, +inside macro arguments, in table cells and elsewhere (in section titles, in +footnotes and in index entries), see also in Table \ref{contexts}. +The reason why some of these cases are treated differently +is that catcode changes must be timed correctly so that the proper catcodes +are active by the time \TeX{} reads the verbatim text from the input file for +the first time. (Please note that section titles and index entries are also +written to and read back from auxilary files.) + +This is quite hard to accomplish in several cases (because \TeX{}'s mouth +gathers macro arguments at high speed, a way before \TeX{}'s stomach could +change the catcodes), so \textsf{examplep} provides the commands \verb+÷+ +and \verb+\Q+, which do not change catcodes at all, so they work everywhere. +Each special (say, not alphanumeric) character of the source text of these +commands must be prefixed by a backslash, so \TeX's eyes will see it as a +controls sequence token. The backslashes are retained when the construct is +written to auxilary files, but they get removed upon typesetting. Letters, +when prefixed by a backslash, get special meaning, for example \verb+\V+ +denotes a visible space. For example, The construct +\verb+\÷\\\}÷+ is seen by \TeX's eyes as +\verb+\÷+$_{13}$\allowbreak +\verb+\\+$_{13}$\allowbreak +\verb+\}+$_{13}$\allowbreak +\verb+÷+$_{13}$, and its gets typeset as \verb+\}+ (by running the command +\verb+\÷+). Please note that the construct is properly nested, because all +braces are inside control sequence names. The same result (\verb+\}+) can be +achieved with \verb+\Q{\\\}}+. Both constructs are safe, because they can be +freely moved to anywhere in the source file. However, for compatibility +reasons, \verb+\Q+ is recommended, because its execution doesn't rely on the +current catcode of the terminating \verb+÷+ of \verb+\÷+. A more complicated +example: \verb+``\Q{\\\V X\ }''+ gets typeset as ``\verb*+\ X+\verb+ +''. +In escaped mode, \verb+\V+ dentoes a visible, unbreakable space, +\verb+\S+ and \verb*+\ + denote default space (affected by the +\texttt{pverb-space=} option), \verb+\B+ allows a line break there with a +discreationary hyphen (affected by the \texttt{pverb-linebreak=} option), +and \verb+\n+ flushes left and starts a new line. + +The \verb+\PVerb+ macros can detect whether they have been invoked from +within a macro argument. If so, they do not insist on catcode changes, but +they emit all the tokens that has been seen by \TeX's eyes. (Spaces are +already compressed now, and everything after \verb+%+ +is ignored etc., so this is not purely verbatim anymore.) However, this works +only if the macro argument is properly nested with respect to braces, and it +is delimited by braces (not a terminator character). + +Please note that there might be problems with verbatim material in index +entries processed by \textsf{makeindex} if characters +\verb+"+, \verb+@+, \verb+!+ and \verb+|+ are not quoted properly with +\verb+"+. This is a generic \textsf{makeindex} issue. The quoting must be +applied even inside verbatim material. + +\subsection{Horizontal alignment of the Source lines}\label{srcstyle} + +The \texttt{verbatim} environment of standard \LaTeX{} reads the whole +verbatim text into a macro argument, thus limiting the length of the verbatim +material to the available main memory. This is enough for about 3400 +80-character lines. The \textsf{verbatim}, \textsf{moreverb}, +\textsf{listings} and +% Dat: moreverb pkg uses verbatim pkg +\textsf{examplep} packages parse the input line-by-line, so there is no such +limit. However, with \textsf{examplep}, additional memory is required for +aligned mode, which limits the maximum number of lines to about 2200 +(32 pages) when the average line width is 80 characters. Please note that +the maximums mentioned here may be lower if more packages are loaded; in +another situatian the maximum number of lines was 375. As a reference, +a plain \verb+\halign+ with all lines having +\verb+(9999)\hfil\cr+ only could accomodate about 5000 lines when no packages +were loaded. The +maximum memory can be increased by increasing the \verb+extra_mem_bot+ +variable in \textsf{texmf.cnf} or in the environment. +%As a reference measurement. +%%%WF mi itt ez az utso mondat? +%% -- tényleg hülyeség, hihúzva + +There are two display modes used for display verbatim: paragraph and aligned +(see the \verb+\pexa@show@pars+ and \verb+\pexa@show@halign+ macros, +respectively, in the source). Aligned mode is used when multiple columns +(such as line numbers and text) have to be aligned horizontally. Aligned mode +uses the \TeX{} \verb+\halign+ primitive to do the alignment, and this +primitive reads the whole construct into memory before typesetting it (in +order to be able to calculate the column widths). The other one, +paragraph mode, is used when +horizontal alignment is not needed and side-by-side display is not used. In +paragraph mode, each line is typeset as a seperate paragraph, so the length +of the verbatim text is only limited by the available disk space to hold the +resulting DVI file. \textsf{examplep} chooses the mode automatically: for +side-by-side display it always chooses aligned mode (so it can measure the +width of the Source before typesetting it), otherwise, if the +\texttt{srcstyle=} makes it possible, it chooses paragraph mode, otherwise +it chooses aligned mode. See Figure \ref{fig:srcstyle} for details about +Source styles. + +\begin{figure}\small +{\relax\normalsize \parindent1em + \advance\leftskip\parindent %\advance\rightskip\parindent % Dat: automatic for \hsize + \advance\hsize-2\parindent + \parindent0pt +\texttt{srcstyle=left} \emph{PAF}\par +\leavevmode\hbox to0pt{\hss\scriptsize9}\texttt{srcstyle=leftnumhang} \emph{PAF}\par +{\scriptsize9}\texttt{srcstyle=leftnum} \emph{PAF}\par +\leavevmode{\scriptsize\phantom99}\texttt{srcstyle=leftnumcol} \emph{AF} when the last page number has 2 digits\par +\hfil\texttt{srcstyle=center} \emph{PAF}\par +\hfill\texttt{srcstyle=right} \emph{PAF}\par +\texttt{srcstyle=paralign}\hfill\emph{PF}\hfill with\hfill \texttt{source-par-align=justjust}\par +\strut\texttt{srcstyle=leftboth}\ \vrule\ srcstyle=leftboth \emph{A}\par +\leavevmode{\scriptsize\phantom99}\strut\texttt{srcstyle=leftbothnumcol}\ \vrule\ srcstyle=leftbothnumcol \emph{A}\par +\strut\texttt{srcstyle=leftleft}\ \vrule\ anything \emph{A}\par +%%%WF eleg zavaros egy tablazat, es harom sorban a | utani dolgok is +%%% erthetetlenek +%% -- mivel nincs jobb ötletem, marad ez +% Imp: boxed? +} +\medskip +\emph{P:} works in paragraph mode\\ +\emph{A:} works in aligned mode\\ +\emph{F:} works when Source is read back from file +\caption{The effect of the \texttt{srcstyle=} option}\label{fig:srcstyle} +\end{figure} + +Please note that the Source styles \texttt{leftboth} and +\texttt{leftbothnumcol} display each line twice, as Source and as Sample, +too. This is different from regular side-by-side display, because lines of +the Source and Sample here are forcibly aligned, and this solution doesn't +use a temporary file. The source style \texttt{leftleft} is similar, but it +lefts the author specify different Source and Sample for the same line (they +should be separated by \verb+&+ in the source). + + +\subsection{Display verbatim isolation}\label{pexaminipage} + +The \texttt{PexaMinipage} environment is provided, which is similar to the +%%%WF bulilt-in +built-in +%%% +\texttt{minipage} environment, but provides better isolation of the +Sample from the container document, because it saves and restores section, +page, equiation (etc.) numbers and also marks (section titles in +page headers). +Labels (for \verb+\label+, \verb+\ref+ etc.) are not isolated, because many +packages use them in a non-standard way. +See Figure \ref{fig:pexaminipage} for an example. + +\begin{figure}\small +\noindent\hfil\hbox to0pt{\hss\includegraphics{pexaminipage}\hss} +\caption{Display verbatim isolation with the \texttt{PexaMinipage} environment}% +\label{fig:pexaminipage} +\end{figure} + +The environment also +cancels vertical skips (including \verb+\belowdisplayskip+) at the bottom +of its contents. For space conservation, \verb+\abovedisplayskip+ above the +very first displayed equation is also canceled. To vaid this, put +\verb+\everydisplay{}+ before the formula. The environment starts with +\verb+\noindent+, but subsequent paragraphs are indented. + + +\subsection{Feature comparison} + +Although there are several \LaTeX{} packages providing display and/or inline +verbatim environments for \LaTeX{}, \textsf{examplep} has some important +unique features not found in other packages (see the beginning of this +section for details). The author has tried the following packages before +deciding to write \textsf{examplep}: + +\begin{description} + +\item[\normalfont\textsf{verbatim}] + Although the \texttt{verbatim} environment is built-in into \LaTeX{}, its + most important limitation is that it eats up \TeX{} memory when typesetting + very long verbatim material (of several hundred or thousand lines). The + \textsf{verbatim} package fixes this, and provides the + \verb+\verbatiminput+ command (similar to the \verb+\PexaShowSource+ + command of \textsf{examplep}) and the \texttt{comment} environment (similar + to \texttt{PIgnore} in \textsf{examplep}). + +\item[\normalfont\textsf{moreverb}] + This package extends the \textsf{verbatim} package with additional + features: proper handling of tabulators (also accessible from + \textsf{examplep} with the \textsf{listings} interface), line numbering + (also available in \textsf{examplep} with much more customization), + verbatim surrounded by a frame (this is not available in \textsf{examplep}, + but it works with \textsf{listings}, with page breaks allowed), the + \texttt{verbatimwrite} environment writes its contents to a file (similar + to the \texttt{WFile} environment in \textsf{examplep}). + +\item[\normalfont\textsf{sverb}] + It provides display verbatim with tabulators and long environments, and it + can read and write text from files. It also has a side-by-side environment + (\texttt{demo}) with fancy frames. + The \textsf{verbfwr} package (part of the \textsf{examplep} distribution) + was derived from parts of this package. + +\item[\normalfont\textsf{syntax}] + This package is written by the author of \textsf{sverb}. It provides + generic and customizable inline verbatim support and it also has powerful + features to typeset BNF-like grammars and syntax diagrams. It is documented + that no attempt is made to make the constructs work inside macro arguments + or section titles. + +\item[\normalfont\textsf{alltt}] + This standard \LaTeX{} package defines the \texttt{alltt} environment in + which the characters \verb+\ { }+ retain their original meaning, so it is + possible to do some manual formatting in the verbatim text. + +\item[\normalfont\textsf{fancyvrb}] \cite{fancyvrb} + This is extremely configurable verbatim package provides inline + verbatim even in footnotes, display verbatim even with side-by-side, line + numbers on any side, all + kinds of francy frames even with page breaks, text formatting and + writing and reading from files; and very long diplay verbatim text. + Options can be specified any time within the argument of the \verb+\fvset+ + command. The original \texttt{verbatim} environment is not modified, + but a new one, \texttt{Verbatim} is defined. Setting the background color + is not possible. + + This package is not actively developed. Version 2.7 (dated + 2000/03/21) is part of te\TeX{}. Oddly enough, the newest version on CTAN + is 2.6, which a file timestamp in 2004, but it dated 1998/07/17). + +\item[\normalfont\textsf{fvrb-ex}] + This package is part of the \textsf{fancyvrb} distribution and uses the + \textsf{fancyvrb} package. It provides a + side-by-side display verbatim environment (\texttt{SideBy\allowbreak SideExample}). A + page break is not allowed in the Source after the Sample. % Dat: tested + The \texttt{xrightmargin} option has to be specified manually (e.g.\,% + \texttt{xrightmargin\allowbreak=3cm}. The first two + characters of each line in the environment are ignored. + +\item[\normalfont\textsf{ltxdoc}] + The most important features of \textsf{examplep} inspired by the \LaTeX{} + documentation package are display verbatim line numbering with + \texttt{srcstyle=left\allowbreak num} and inline verbatim started with \verb+÷+. + The \textsf{ltxdoc} package typesets everything between two \verb+|+ + characters as inline verbatim. This is not supported by \textsf{examplep} + to avoid making an ASCII character active. + +\item[\normalfont\textsf{listings}] \cite{listings} + The most important layout elements of this sophisticated, highly + customizable, actively developed package missing from + \textsf{examplep} are: background color, frames (with page breaks allowed), + syntax highlighting and proper tabulator support. Except for the background + color and frames, these features can be used from \textsf{examplep} with + its interface to \textsf{listings}, see in Subsection \ref{listings}. + Use \verb+\lstset{columns=fullflexible,lang+\allowbreak\verb+uage=C,back+\allowbreak\verb+groundcolor=\color{red},frame=trBL}+ + to try these features. \textsf{listings} also provides inline verbatim + mode (with syntax highlighting), in the character-delimited argument of the + command \verb+\lstinline+;\,unfortunately, spaces at line breaks (with + option \texttt{breaklines}) are rendered in an inconsistent way, and line + breaks do not work well with background color. + + \textsf{listings} has an important weak point: it cannot typeset ISO Latin + accented characters with the \textsf{inputenc} package; + the way described in the manual doesn't work as expected: it puts the + accented characters to the wrong place in the line. This problem, + however, is solved when \textsf{listings} is invoked from + \textsf{examplep}. See more about listings in Subsection \ref{listings}. + +%%%WF This package is actively developed. +%%% ezt mar emlitetted a bekezdes elejen +\end{description} + +\section{Customization}\label{customization} + +The operation of \textsf{examplep} can be customized with options as +$\langle$key$\rangle${}$=${}$\langle$value$\rangle$ pairs. Global options, which affect all subsequent commands within +the current block, can be specified as package load options +(\verb+\usepackage[+\ldots\verb+]{examplep}+) or as argument of the \verb+\PexaDefaults+ +command. \LaTeX{} doesn't allow complicated option values (such as values +containing some expandable macros, for example after \texttt{linenumberformat=}) +to be specified in the \verb+\usepackage+ +line -- use \verb+\PexaDefaults+ in such cases. +Many commands and environment accept local options, which affect +only that construct. + +All options have default values, which are indicated below right after the +option name. If the option has a fixed set of possible values, all of them +are mentioned, and they are prefixed by \texttt{=}. The defaults have been +chosen so the \texttt{PSource} environment matches the builtin +\texttt{verbatim} environment as closely as possible. Note that the original +environment is not overridden before the \texttt{verbatimenv=yes} is +specified. + +\begin{description} +\makeatletter % Dat: for \verbatizee{\z@} + +\item[\verbatizee{Q=unchanged}] + To enable \verb+\Q+, use \texttt{=yes} instead of the default. +\item[\verbatizee{abreak=unchanged}] + To enable \verb+\abreak+, use \texttt{=yes} instead of the default. +\item[\verbatizee{addvspace-bottom={\vskip\z@skip\addvspace}}] + \hskip0pt plus4pt + Specifies the command to add vertical space below display verbantim. The default works + fine, but e.g.\ packages maintaining the baseline grid might want to + change it. +\item[\verbatizee{addvspace-top=\addvspace}] + Command to add vertical space above display verbantim. The default works + fine, but for example, packages maintaining the baseline grid might want to + change it. +\item[\verbatizee{allowbreak=yes}] + Use \texttt{=no} to disable page breaks in the Source of display verbatim. +\item[\verbatizee{allowshrink=yes}] + The default will shrink the Sample horizontally if the + Source is too wide. Use \texttt{=no} to disable this. + Use \texttt{=force} to enable shrinking of Source, and with + \texttt{srcstyle=leftleft} or \texttt{srcstyle=leftboth}, also enable + shrinking of the Source if it is narrow. +\item[\verbatizee{baseline-grid=no}] + Use \texttt{=yes} to adjust the height of the Sample to be an integer + multiply of \verb+\baselineskip+ (with \texttt{yalign=u} and + \texttt{yalign=v}). +\item[\verbatizee{boxstyle=p}] Controls how the Sample is boxed. Capital + letters are not allowed for side-by-side display. By default (\texttt{=p}), + a \texttt{PexaMinipage} environment is put inside a \verb+\vtop+. Use + \texttt{=h} to put a \verb+\hbox+ only, \texttt{=v} to put a \verb+\vtop+ + only, \texttt{=V} to put a \verb+\vbox+ only, + \texttt{=m} to put a \texttt{minipage} environment inside a \verb+\vtop+, + \texttt{=M} to put a \texttt{minipage} environment inside a \verb+\vbox+, + \texttt{=P} to put a \texttt{PexaMinipage} environment inside a \verb+\vbox+, + \texttt{=G} to add \verb+\begingroup+ and \verb+\endgroup+ only. + The default is recommended for most cases, because the \verb+\vtop+ + provides proper alignment with the Source, and the \texttt{PexaMinipage} + environment provides isolation (of page and section numbers etc.) from the + main document. +\item[\verbatizee{bsdiv=unchanged}] + To enable \verb+\÷+, use \texttt{=yes} instead of the default. +\item[\verbatizee{div=unchanged}] + To enable \verb+÷+, use \texttt{=yes} instead of the default. +\item[\verbatizee{firstlinenum=1}] + Specifies the number of the first line of a numbered Source listing. + Useful with \texttt{srcstyle=leftnumcol} and \texttt{srcstyle=leftnumhang}. +\item[\verbatizee{linenumberformat={{...}}}] + %\item[\verbatizee{linenumberformat={{\normalfont\rmfamily\scriptsize\number-\pexa@@cntb}\pexa@default@linenumbersep}}] + Commands to display a line number and the separator in a numbered Source + listing. See the default value in \texttt{examplep.sty}. +\item[\verbatizee{linenumbersep={}}] + Commands to display the separator in a numbered Source listing. +\item[\verbatizee{listings=no}] + Use \texttt{=yes} to display each Source line with the \textsf{listings} + package. Specify options (to be executed in \verb+\lstset+), separated by + commas in the argument. Read more about the options in the documentation of + the \textsf{listings} package. For example, \verb+listings=yes+ and + \verb+listings={}+ uses \textsf{listings} with default options (no syntax + highlighting), and \verb+listings={language=+\allowbreak\verb+C,showtabs}+ enables syntax + highlighting for C language and enables visible tabulators. See + Subsection \ref{listings} for more information. +\item[\verbatizee{listings-verbatimfont=pexavf}] + Set the font to be used in the Source when \texttt{listings=} is active. See + \texttt{source-verbatimfont=} for the possible values. +\item[\verbatizee{mp-equation-reset=yes}] + Use \texttt{=no} to make the main document and the Samples inside + \texttt{PexaMinipage} share the same equation counter. +\item[\verbatizee{mp-varioref-reset=no}] + Use \texttt{=yes} to make the internal counter \texttt{vrcnt} of the + \textsf{varioref} package to be reset for each Sample inside + \texttt{PexaMinipage}. This option doesn't affect the final output, and + \textsf{varioref} expects this counter not to be reset, so it is not + recommended to change the default. +\item[\texttt{noligs=some}] + By default, only those ligatures are disabled whose second character is one + of \verb+`+ \verb+'+ \verb+,+ \verb+-+ \verb+<+ \verb+>+. Use + \texttt{=kernel} to get the same effect, but using the \LaTeX{} built-in + \verb+\@noligs+. Use \verb+=most+ to get all ligatures with either the + first or the second character having code between 32 and 127 and catcode + 12. Please note that ligatures in inline verbatim mode are disabled anyway, + because \verb+\allowbreak+ is inserted between characters of catcode 12, + depending on the value of \texttt{pverb-linebreak=}. +\item[\verbatizee{pexaminipage-setuphook={}}] + Extra commands to run when starting the \texttt{Pexa\allowbreak MiniPage} environment, + just after the environment has finished its own initialization. +\item[\verbatizee{pverb-hash=full}] + Use \texttt{=half} to make \verb+\PVerb+ convert \verb+##+ to \verb+#+. + The command \verb+\PVerbH+ is the same as \verb+\PVerb+ but + forces \texttt{=half}. This is required when \verb+\PVerb+ or \verb+÷+ is + used inside a macro argument. For example, \verb+\textit{÷#÷}+ yields + the error message \textit{Illegal parameter number in definition of + \string\reserved@a}, but \verb+\textit{\PVerbH{##}}+ works fine. The error + message is a general \LaTeX{} kernel limitation, for example + \verb+\textit{\@gobb+\allowbreak\verb+le{#}}+ doesn't work either. +\item[\verbatizee{pverb-hyphenchar=hyphen}] + By default, the minus character (ASCII code 45) is used to for automatic word + hyphenation in inline verbatim. Use \texttt{=char'30} to have character + with code 24; see also Subsection \ref{char'30}. Use \texttt{=none} to + disable word hyphenation (by setting \verb+\hyphenchar+ to $-1$). + Use \texttt{=unchanged} to get the hyphenchar from + the font (the \textit{cmtt} and \texttt{ectt} fonts have word hyphenation + disabled). Please note that hyphenation around symbols is affected + the \texttt{pverb-linebreak=} option, not this one. +\item[\verbatizee{pverb-leftbreakmin=2}] + Specifies the minimum number of characters in inline verbatim after which it + is allowed to break the line (with \texttt{pverb-linebreak\allowbreak=}). Values + allowed are $0$, $1$ and $2$, but $0$ usually doesn't make sense. +\item[\verbatizee{pverb-linebreak=char}] + By default, \verb+\PexaAllowBreak+ is inserted around symbols in inline + verbatim, so a line break (with a discreationary hyphen affected by + \texttt{pverb-linebreakchar=}) is allowed there. Use \texttt{=yes} to insert + \verb+\allowbreak+ instead, which allows a line break without + discretionaries. Use \texttt{=no} to disable line breaks around symbols in + inline verbatim. The option \texttt{pverb-hyphenchar=} affects + intra-word hyphenation in inline verbatim, not this one. +\item[\verbatizee{pverb-linebreakchar={$\lnot$}}] + Specifies the discreationary hyphen to be used in \verb+\PexaAllowBreak+. + See also \texttt{pverb-linebreak=}. +\item[\verbatizee{pverb-space=invbreak}] + By default, spaces in inline verbatim are invisible, variable width (as + allowed by the font, see also \texttt{pverb-stretchshrink=}) + and breakable (i.e.\ a space can be replaced by a line + break if necessary). Use \texttt{=invdisc} to get an invisible, variable + width space which becomes visible (\verb*+ +) when it is broken at the end + of the line. Use \texttt{=invfixbreak} to get an invisible, fixed width and + breakable space. Use \texttt{=invnobreak} to get an visible, variable width + and unbreakable space. Use \texttt{=visnobreak} to get a visible, fixed + width and unbreakable space. Use \texttt{=visbreak} to get a visible, fixed + width space with line breaks allowed on both sides. Use + \texttt{=invbreakleft} to get a visible, variable width space with infinite + stretchablility if the line is broken there (this may have strange effect + on other line breaks in the paragraph, so please try to avoid it). + The built-in \verb+\verb*+ command uses + \texttt{source-space=visnobreak}. +\item[\verbatizee{pverb-stretchshrink=yes}] + By default, spaces in inline verbatim are forced to be stretchable and + shrinkable (by \verb+\quad+${}/9$). Use \texttt{=no} to disable + stretchability and shrinkability. Use \texttt{=unchanged} to keep the + settings in the font. Note that \verb+\fontdimen+$3$ and + \verb+\fontdimen+$4$ are changed by this option, and the changes are local + to inline verbatim mode. +\item[\verbatizee{pverb-verbatimfont=pexavf}] + Set the font to be used in inline verbatim mode. See + \texttt{source-verbatimfont=} for the possible values. +\item[\verbatizee{samplewidth=.5\PexaWidth}] + Specifies the maximum width of the Sample in side-by-side display as a + \TeX{} dimension. The actual Sample can become actually narrower (see + \texttt{allowshrink=}. The dimensions \verb+\hsize+, \verb+\linewidth+ and + \verb+\PexaWidth+ can be used. (Our \LaTeX{} book used + \verb+sample+\allowbreak\verb+width=.45\PexaWidth+.) \verb+\leftskip+ and \verb+\rightskip+ + do not affect this option. \verb+\hsize+ can be used, which is the total + width available (including the extra margins added by surrounding list + environments), \verb+\linewidth+ is \verb+\hsize+ widtout the extra margins + produced by lists, and \verb+\PexaWidth+ is the total width of the Source, + the separator (see \texttt{vrule=}) and the Sample. +\item[\verbatizee{source-par-align=left}] + Specifies the alignment of Source lines when \texttt{srcsty\allowbreak le=paralign} is + active. Use \texttt{=left} (default), \texttt{=right} or \texttt{=center} to + specified flush-left, flush-right or centered alignment, respectively. Use + \texttt{=justi\allowbreak fy} to have the last line flush-left and the previous line + justified (please note that each Source line is mapped to a single + paragraph, so the paragraph will have more than 1 line only if the source + line is too long). Use \texttt{=justjust} to have all lines justified. + Use \texttt{=unchanged} to keep the alignment of the enclosing block. +\item[\verbatizee{source-sepwidth=\tabcolsep}] + Specifies the horizontal distance between the Source and the Sample. + See also \texttt{vrule=}. +\item[\verbatizee{source-space=invfixbreak}] + Specifies how to typeset spaces of the Source. See \texttt{pverb-space=} + for the possible values. The built-in \texttt{verbatim*} environment uses + \texttt{source-space=visnobreak}. +\item[\verbatizee{source-verbatimfont=pexavf}] + Sets the font to be used for the Source when \texttt{listings=} is not + active (see also \texttt{listings-verbatimfont=} for + \texttt{listings\allowbreak=}). + Give + \texttt{=ttfamily} to use \verb+\ttfamily+, + \texttt{=pexavf} to use \verb+\pexa@@verbatim+\allowbreak\verb+font+ (which defaults to + \verb+\verbatim@font+), + \texttt{=latexvf} to use \verb+\verbatim@+\allowbreak\verb+font+ (which defaults to \verb+\normalfont\ttfamily+), + \texttt{=unchanged} to keep the current font, + or \texttt{=normalfont} to use \verb+\normalfont+. +\item[\verbatizee{srcstyle=left}] + Specifies the horizontal alignment of the Source lines. See more in + Subsection \ref{srcstyle} and Figure \ref{fig:srcstyle}. +\item[\verbatizee{ttlistings=}\normalfont\ (no default)] % Dat: $\varnothing$ + Shorthand of \texttt{listings-verbatimfont=ttfamily,\allowbreak listings=}. +\item[\verbatizee{url=unchanged}] + To enable \verb+\url+, use \texttt{=yes} instead of the default. The + \verb+\url+ will be defined as \verb+\def\url{\PVerbOpt{}}+. This has the + disadvantage that inside \verb+\textit+ etc.\ it cannot typeset URLs having + a single \verb+#+ (see \texttt{pverb-hash=} for more), but the \textsf{url} + package has the same limitation. A quick fix: use \verb+\itshape+ instead + of \verb+\textit+ etc. +\item[\verbatizee{usewidth=skipwidth}] + Specifies which horizontal part of the main text should be used in a + display verbatim. By default, left and right margins introduced by list + environments (such as \texttt{itemize}) and \verb+\leftskip+ and + \verb+\rightskip+ are respected. Use \texttt{=linewidth} to ignore + \verb+\leftskip+ and \verb+\rightskip+ but respect list environments. Use + \texttt{=hsize} to use the whole width of main text. Note that this option + affects the calculation of \verb+\PexaWidth+. +\item[\verbatizee{vextrabotdepth=\z@}] + Dimension to add to the depth of the display verbatim with + \texttt{yalign=v}. The default works + fine, but for example, packages maintaining the baseline grid might want to + change it for each instance. +\item[\verbatizee{vextravskip=\z@}] + Amount of vertical space to be added above display verbantim with + \texttt{yalign=v}. The default works + fine, but for example, packages maintaining the baseline grid might want to + change it for each instance. +\item[\verbatizee{vsmallht=1pt}] + Specifies Sample height threshold for \texttt{yalign=v}. If the Sample is + lower than this (or sample a higher than the 1st line of the Source plus + \verb+\vextravskip+ -- + typical for \verb+\includegraphics+), its top will be aligned to the top of + the Source, otherwise + its top baseline (with \verb+\vtop+) will be aligned to the top baseline of + the Source. +\item[\verbatizee{xalign=l}] + Specifies horizontal alignment (\texttt{=l} for left, \texttt{=r} for + right) of the Sample box (and the separator) within its allocated width for + side-by-side display. Please note that \texttt{=r} works only + with \texttt{boxstyle=h}, because all other box sizes use their + full allocated width. +\item[\verbatizee{xindent=deeppre}] + Specifies additional horizontal indentation in display verbatim mode. Use +%%%WF \texttt{=nonoe} + \texttt{=none} +%%% + to get no extra indentation. Use \texttt{=narrower} to get + \verb+\narrower+ (both \verb+\leftskip+ and \verb+\rightskip+ are decreased + by \verb+\parindent+). + Use \texttt{=deeper} to move one level deeper in the list environment + hierarchy and get that indentation. +%%%WF na most akkor mi a default? a deeper vagy a deeppre? + Use \texttt{=deeppre} (default) to move one level deeper, but don't change + indentation (this is useful with \texttt{yindent=deeper} -- + otherwise it is equivalent to \texttt{=none}). % Dat: really?? + Use \texttt{=deepright} to set both left and right indentation from + the left indentation of \texttt{=deeper}. +\item[\verbatizee{yalign=u}] + Specifies vertical alignment in side-by-side display. By default, the top + of the bounding boxes of the Source and the Sample is aligned, which looks + nice if the Sample is an image, but doesn't align properly if the Sample is + text with a font of similar size to the Source. Use \texttt{=b} to align + the topmost baselines of the Sample and the Source. This looks nice if the + Sample is text, but it is ugly if the Sample is an image higher than + \verb+\baselineskip+. The use of \texttt{=v} is recommended, which decides + between \texttt{=b} and \texttt{=u} based on the height of the Sample (see + \texttt{vsmallht=} for the details). +\item[\verbatizee{yindent=deeper}] + Specifies the vertical space separating display verbatim from the + surrounding text. Use \texttt{=none} no have no extra vertical space, the + display verbatim appears to be a new paragraph as far as + \verb+\baselineskip+ and \verb+\vskip+s are concerned. Use \texttt{=deeper} + (default) to move one level deeper in the list environment hierarchy + (and use the \verb+\parsep+ and \verb+\partopsep+ etc.\ specified there). + It is recommended to have \texttt{yindent=deeper} and + \texttt{xindent=deeppre} together, so there is no extra horizontal + indentation. +\item[\verbatizee{verbatimenv=unchanged}] + Use \texttt{=yes} + to change the implementation of the \texttt{verba\allowbreak tim} and \texttt{verbatim*} + environments to use the \texttt{PSource} environment. +\item[\verbatizee{vrule=rule}] + By default, the Source and the Sample are separated with a vertical rule + of width \verb+\arrayrulewidth+ in the middle of a horizontal space + specified by \texttt{source-sepwidth=}. Use \texttt{=skip} to omit the rule + but keep the space. Use \texttt{=none} to have no separator at all. + +\end{description} + +The other packages (\textsf{codep} and \textsf{verbfwr}) shipped with +\textsf{examplep} do not have load options. + + +\subsection{Interface to the \textsf{listings} package}\label{listings} + +The \textsf{listings} package \cite{listings} provides advanced typographic for display +verbatim, including proper typesetting of tabulators and syntax highlighting +for more than a hundred languages. \textsf{examplep} doesn't try to +reimplement these features, but it supports calling the \textsf{listings} +package to typeset the Source lines in display verbatim. The surroundings +(line numbers, vertical separation, horizontal margins and the Sample) are +not effected, only the Source line contents are passed to \textsf{listings}. +This implies that the border and the background color support provided by the +\textsf{listings} package doesn't work with \textsf{examplep}. To use the +interface, the \textsf{listings} package must be loaded, and either the +\textsf{listings=} or the \textsf{ttlistings=} options of \textsf{examplep} +has to be active when the Source is typeset. Additional options +can be specified to \textsf{listings} in the argument of \verb+\lstset+ at +any time. The interface has been tested +with the \textsf{listings} package dated 2000/08/23 and 2004/09/07. + +\textsf{examplep} treats tabulators (ASCII code 9) as 8 spaces. This is +acceptable at the beginning of the line, but it may be incorrect elsewhere. +To get tabs right, specify the \verb+ttlistings=yes+, or, to be more precise, +the \verb+ttlistings={tabsize+\allowbreak\verb+=8}+ option to \textsf{examplep}. It is also +possible to have visible tabulators: specify, for example, +\verb+ttlistings={tabsize=8,showtabs}+. In our tests \textsf{listings} failed +to detect the width of a character of a fixed width font, so +\textsf{examplep} enforces character width using the natural width of the +space each time it calls \textsf{listings}. This workaround made the +\texttt{showtabs} \textsf{listings} option work properly. +See the documentation of the +\textsf{listings} package for options that affect the typesetting of +Source line contents. See an example of using \textsf{listings} from +\textsf{examplep} on page \pageref{pag:use-listings}. + +\textsf{listings} supports fixed width characters with a variable with fonts. +However, this support seems to be broken when used with \textsf{examplep}, so +the \texttt{columns=full\allowbreak flexible} \textsf{listings} option is enforced so +proportional fonts will look proportional. Although the +\textsf{listings} package claims that it has accented letter support, this +didn't work well with the single-character accented letters input using +the \textsf{inputenc} package (those characters were positioned to a wrong +place inside the line, possibly because \textsf{listings} has failed to +recognise that \verb+\lst@UseLostSpace\lst@+\allowbreak\verb+PrintToken+ has to be inserted +in front of the accented character into its internal token list). +\textsf{examplep} contains a work-around to this problem, with the following +limitations: multibyte input encodings such as UTF-8 are not supported (will +print strange error message); accented characters may not be part of keyword +names in syntax highlighting; accented characters are shown as \verb+^^+ hex +escapes in aligned mode (see in Subsection \ref{srcstyle}), so they don't +work with \verb+\PexaShowBoth+. + +\textsf{listings}, when called from \textsf{examplep}, failed to break +ligatures such as \verb+`?+ and \verb+<<+. This has the side effect that +guillemots would be typeset instead of bitwise right shift in C language +sources. \textsf{examplep} modifies +the \verb+\lst@FillOutputBox@+ macro so it will add a \verb+\relax+ between +each character displayed -- so all ligatures are broken. (This approach is +quite differrent from the way \LaTeX{} disables a few ligatures +with \verb+\@noligs+; \verb+\pexa@noligs+ is similar to \verb+\@noligs+ in +this respect.) + +It is possible to customize the \textsf{listings} package so it typesets some +strings differently. For example, with the +\verb+literate={<=}{{$\leq$}}1+ \textsf{listings} option, all occurences of +\verb+<=+ (even those inside strings of the target programming language) +are typeset as $\leq$. There are no problems when using this feature from +within \textsf{examplep}. It is also possible for strings and comments in the +syntax-highlighted Source to span multiple lines -- \textsf{listings} takes +care to remember its internal state between lines. + + +\section{Commands and environments} + +The arguments between brackets (\verb+[+ and \verb+]+) are optional: either +the the argument and the brackets are all missing all all present. The +arguments named ``options'' is a comma-separated list of local customization +options, defined in Section \ref{customization}. The \texttt{\{}$^+$ notation +in front of an argument means that the argument can be delimited by braces +(thus it must be properly nested), or with any symbol in +\verb+\dospecials+ (% +\verb+\+ \verb+$+ \verb+&+ \verb+#+ \verb+^+ \verb+_+ \verb+%+ +\verb+~+) %%%WF $ +or in \verb+\pexa@cverb@donormals+ (% +\verb+`+ \verb+!+ \verb+@+ \verb+*+ \verb+-+ \verb-+- \verb+=+ \verb+|+ +\verb+:+ \verb+;+ \verb+'+ \verb+"+ \verb+,+ \verb+.+ \verb+/+ \verb+?+ +\verb+<+ \verb+>+ \verb+(+ \verb+)+ \verb+[+ \verb+]+). + +\begin{description} + +\def\cearg #1{{\normalfont\texttt{\{}$\langle $\relax#1\relax$\rangle$\texttt{\}}}} +\def\verarg#1{{\normalfont\texttt{\{}$^+\langle$\relax#1\relax$\rangle$\texttt{\}}}} +\def\delarg#1{{\normalfont $\langle $\relax#1\relax$\rangle $}} +\def\optarg#1{{\normalfont[$\langle$\relax#1\relax$\rangle$]}} + +\item[\verbatizee{\PVerb}\optarg{options}\verarg{verbatimtext}] + Typesets its argument in inline verbatim mode. Similar to the \LaTeX{} + \verb+\verb+ macro, but respects the options. The use of \verb+[]+ is + recommended instead of omitting the options altogether, because \verb+[]+ + will ensure that the proper catcode changes are in effect even for the + first verbatim character. + This command is robust. +\item[\verbatizee{\PVerbH}\verarg{verbatimtext}] + Shorthand for \verb+\PVerb[pverb-hash=half]+\ \hskip0pt plus2pt + (extra options cannot be specified). + This command is robust. +\item[\verbatizee{\PVerbInner\PVerb}\ldots] + Forces the \verb+\PVerb+\ldots{} command immediately following it to work + in inner mode, thus compressing spaces, respecting comment characters etc. + Because of how \TeX{} works, it is impossible to go the other way round, + and force outer mode, because it is too late change catcodes -- the + argument has already been tokenized in inner mode. + This command is robust. +\item[\verbatizee{\PVerbOpt}\cearg{options}\verarg{verbatimtext}] + Equivalent to \verb+\PVerb+, but uses a different syntax. + For example, \verb+\item[\PVerb[pverb-space=visbreak]{xy+\allowbreak\verb+}]+ doesn't work + because of the nested \verb+[+. Use this instead: + \verb+\item[\PVerb+\allowbreak\verb+Opt{pverb-space=+\allowbreak\verb+visbreak}{xy}]+, + \hskip0pt plus4pt or \hskip0pt plus4pt + \verb+\item[{\PVerb[pverb-space=+\allowbreak\verb+visbreak]{xy}}]+. + This command is robust. +\item[\verbatizee{\Q}\cearg{verbatimtext}] + Similar to \verb+\PVerb+, but its argument must be escaped + (see in Subsection \ref{escaped}), and it can be used in section titles etc. + Must be enabled with \texttt{Q=yes}. + This command is robust. +\item[$\div$\delarg{verbatimtext}$\div$] + Similar to \verb+\PVerb+, but it can be used in section titles etc. (but not + int \texttt{tabular}) (see in Subsection \ref{escaped}). + Must be enabled with \texttt{div=yes}. + This command is robust. +\item[\textbackslash$\div$\delarg{verbatimtext}$\div$] + Equivalent to \verb+\Q+, but the argument delimiter is different. + Similar to \verb+\PVerb+, but its argument must be escaped + (see in Subsection \ref{escaped}), and it can be used in section titles etc. + Must be enabled with \texttt{bsdiv=yes}. + This command is robust. +\item[\verbatizee{\url}\cearg{url}] + Must be enabled with \texttt{url=yes}. + This command is robust. +%%%WF az eleme jelet NE HASZNALD, osszesen 3-szor szerepel, irj +%%% valamit, hogy pl.: (after laoding verbfwr package) +%%% vagy valami hasonlot +%% -- javítva +\item[\verbatizee{\begin{WFile}}\cearg{filename}] (defined in the \textsf{verbfwr} package) + Writes its contents verbatim to the specified file. + \TeX{} \texttt{.tcx} and line ending transformations apply, so it is + possible that accented letters will be converted to \verb+^^+hex according + to the input encoding. +\item[\verbatizee{\begin{WAux}}] (defined in the \textsf{verbfwr} package) + Writes its contents verbatim into the current \texttt{.aux} file. + \TeX{} \texttt{.tcx} and line ending transformations apply, so it is + possible that accented letters will be converted to \verb+^^+hex according + to the input encoding. +\item[\verbatizee{\begin{PWSource}}\optarg{options}] + Comination of \verb+\begin{WSource}+ and \verb+\PexaShow+\allowbreak\verb+Source+. + It is recommended to have a \verb+[]+ even if there are no + options, so the very first token of the contents will be read with proper + catcodes. +\item[\verbatizee{\begin{WBoth}}] + Writes its contents to the Source and the Sample temporary file. It is + a combination of \texttt{WSample} and \texttt{WSample}. +\item[\verbatizee{\begin{WSample}}] + Writes its contents to the Sample temporary file (\texttt{pexa-sam.\allowbreak tex}), + to be typeset by a subsequent \verb+\PexaShowSample+ or + \verb+\PexaShowBoth+. + The line must end at \verb+\end{WSample}+ because of technical reasons. +\item[\verbatizee{\begin{WSource}}] + Writes its contents to the Source temporary file (\texttt{pexa-src.\allowbreak tex}), + to be typeset by a subsequent \verb+\PexaShowSource+ or + \verb+\PexaShowBoth+. It is similar to + \verb+\begin{verbwrite}+ in the \texttt{sverb} package + and the \verb+\begin{+\allowbreak\verb+filecontents}+ \LaTeX{} built-in environment. + The line must end at \verb+\end{+\allowbreak\verb+WSource}+ because of technical reasons. +\item[\verbatizee{\begin{PIgnore}}] + Ignores everything up to \verb+\end{PIgnore}+. The environment closer must + be at the end of its line. Similar to the \texttt{comment} environment in + some other packages. +\item[\verbatizee{\begin{PSource}}\optarg{options}] + Typesets its contents in display verbatim. Similar to the \LaTeX{} + \verb+\begin{verbatim}+ environment, but respects the customization + options. It is recommended to have a \verb+[]+ even if there are no + options, so the very first token of the contents will be read with proper + catcodes. This environment is similar to \texttt{PWSource}, but it doesn't + create a temporary file, so it is faster, \texttt{srcstyle=leftboth} (etc.) + can be used, and there is no ambiguity between \verb+^^e1+ and + \texttt{\'a} (etc., see more in Subsection \ref{tcx}). Page breaks are + allowed between each Source line. (The implementation of this environment + is fairly complex compared to \texttt{PWSource}.) +\item[\verbatizee{\begin{verbatim}}] + Equivalent to \verb+\begin{PSource}[]+. + Must be enabled with \texttt{verbatimenv=yes}. +\item[\verbatizee{\begin{verbatim*}}] + Equivalent to \verb+\begin{PSource}[source-space=visbrea+\allowbreak\verb+k]+. + Must be enabled with \texttt{verbatimenv=yes}. +\item[\verbatizee{\begin{PexaMinipage}}\optarg{vbox-type}\cearg{width}] + Similar to the \LaTeX{} \texttt{minipage} environment (and + accepts the same arguments), but + isolates (concerning section numbers etc.) of its contents from the main + document more thoroughly. See Subsection \ref{pexaminipage} for + details of isolation. +\item[\verbatizee{\PexaShowBoth}\cearg{options}] + Typeets the Source and the Sample side-by-side in display verbatim mode. + The Source comes from the temporary file written by the last + \texttt{WSource} or \texttt{WBoth} environment, and + the Sample comes from the temporary file written by the last + \texttt{WSample} or \texttt{WBoth} environment. + By default, a vertical separator line is drawn between the Source and the + Sample, and page breaks are allowed in the Source after the end of + Sample. + It can be called multiple times with different options for the same file. +%\item[\verbatizee{\PexaShowBothMany}]% Dat: for internal use +\item[\verbatizee{\PexaShowSample}\cearg{options}] + Typesets the Sample (written by\,the\,last + \texttt{WSample} or \texttt{WBoth} environment) in display mode. + It can be called multiple times with different options for the same file. +%\item[\verbatizee{\PexaShowSampleMany}]% Dat: for internal use +\item[\verbatizee{\PexaShowSource}\cearg{options}] + Equivalent to \verb+\PexaInputSource+ with the file written by the last + \texttt{WSource} or \texttt{WBoth} environment. + It can be called multiple times with different options for the same file. +%\item[\verbatizee{\PexaShowSourceMany}]% Dat: for internal use +\item[\verbatizee{\PexaInputSource}\cearg{filename}\cearg{options}] + Typesets the contents of the specified file as Source in display verbatim + mode. +% \item[\verbatizee{\PexaAddlastskip}] (not used anymore, see comment in lb.sty) +\item[\verbatizee{\begin{code}}] (defined in the \texttt{codep} package) + Typesets its contents side-by-side and also marks its contents to be dumped + to the CD. By default, each line is emitted to all +%%%WF thre + three +%%% + streams, but lines + with special prefixes will go into the Source, Sample or CD-file stream + only. See Section \ref{code} for details. +\item[\verbatizee{\PexaAllowBreak}] + Allows a line break here with a discreationary specified + in the option \texttt{pverb-linebreakchar=} inserted. +\item[\verbatizee{\abreak}] + A robust command which + inserts \verb+\PexaAllowBreak+ when the font \verb+{\ttdefault}{m}{n}+ + is active; inserts \verb+\allowbreak+ otherwise. + Must be enabled with \texttt{abreak=yes}. + +\end{description} + +\section{Writing examples with the \textsf{codep} package}\label{code} + +Textbooks and manuals tend to have many display verbatim examples. The +examples are usually code snippets which can be further processed by a +compiler or another program. +Sometimes minor modifications, such as adding the proper header or trailer, +are necessary before the code snippet can be processed. It is customary to +put all code snippets in the book onto the CD accompanying the book. The +\texttt{code} environment of the \textsf{codep} package (part of the +\textsf{examplep} distribution) generates CD-files automatically. + +Three streams are generated from the contents of each \texttt{code} +%%%WF environemnt: +environment: +%%% +the Source, the Sample and the CD-file streams. Most parts of +these streams are identical. The Sample usually differs from the Source +because the code snippet has to be typeset specially in the book (for +example, \verb+\includegraphics+ has to be used to typeset an EPS file whose +Source is displayed). The CD-file differs from Source because additional +header and footer may be required (such as \verb+\begin{document}+ etc.), +which are omitted from the book to conserve space. + +The \texttt{code} environment reads the code snippet line-by-line. The type +of the line is specified in first two characters. Lines having the default +type are written to all 3 streams, and special line types exist to write to a +specific stream only. The \texttt{code} environment writes the Source and +Sample streams to temporary files, and upon the end of the environment, it +calls \verb+\PexaShowBoth+ (or \verb+\PexaShowSource+, if the Sample stream +is empty) to typeset the example. The CD-file stream is not written to a file +by \TeX{}, but the file name and starting line number of the \texttt{code} +environment is reported in the \texttt{.aux} file. A \textsf{Perl} script +(\textsf{wrfiles.pl}, part of the \textsf{examplep} distribution) has to be +called later to the actual generaton of CD-files. It will examine the +\texttt{.aux} files, extract the CD-file stream from the \texttt{.tex} files, +and dump these streams to individual files in the \texttt{CDfiles} directory. +The file names can be specified in the \texttt{code} enviroment, and the +environment can generate file names based on chapter and page numbers (so the +reader will know from the file name where to read more about the example). +The same file name is never generated again. + +The \textsf{code} package was used in our recent \LaTeX{} textbook \cite{lakk} +to typeset its examples. Most of the examples were written in \LaTeX{}, but +many +%%%WF of of +of +%%% +them were \textsf{METAPOST} sources, and some of them were others +(e.g.\ configuration files, shell scripts or EPS files). Because of the huge +amount of \LaTeX{} examples, special features were added to make them easy +and convenient to input for the author. For example, +\begin{verbatim} +\begin{code} +t \usepackage{url} + URL: + \\\url{http://foo.org/~user/} +\end{code} +\end{verbatim} +is displayed as (depending on the \textsf{examplep} options) +\par\medskip +\noindent\begin{tabular}{@{}l@{}l@{}l@{}} +{\scriptsize1}\verb+%^\usepackage{url}+&\ \vrule\ \null&URL:\\ +{\scriptsize2}\verb+URL:+&\ \vrule\ \null&\verb+http//foo.org/~user/+\\ +{\scriptsize3}\verb+\\\url{http//foo.org/~user/}+&&\\ +\end{tabular} +\par\medskip\par +As seen above, examples are quite convenient to input, and \textsf{examplep} +takes care of typesetting side-by-side, determining width of the Source, +allowing page breaks, putting margins and \verb+\vskip+s right, adding the rule the +separate the Source and the Sample, adding line numbers, generating file name +for CD-file and writing the CD-file with header and footer. + +With \textsf{codep} it is easy to fulfill the following quality criterias: +the Sample must be consistent with the Source (i.e.\ if the Source is +changed during editing to book, the Sample should change automatically); the +CD-file must be consistent with the Source; the CD-file must be directly +compilable with \LaTeX{} (so a header and a footer have to be added). When +the deadline of finishing the book approaches, there might not be enough time +left to ensure these manually, so a package such as \textsf{codep} is very +useful in this situation. + +\subsection{Example files on the CD}\label{codewritereasons} + +The following CD-file is generated from the code snippet above: +\begin{verbatim} +\documentclass{article} + +\usepackage[latin2]{inputenc} +\usepackage[T1]{fontenc} +\usepackage[magyar]{babel} +\usepackage{url} + +\begin{document} + +URL: +\\\url{http://foo.org/~user/} + +\end{document} +\end{verbatim} + +The \texttt{CodeDefaultD}, \texttt{CodeDefaultL}, \texttt{CodeDefaultB} and +\texttt{CodeDefaultE} environments can be used in the preamble to customize +the default header and footer generated into the CD-file. For example: +\begin{verbatim} +\begin{CodeDefaultD} +\documentclass[10pt]{article} +\end{CodeDefaultD} +\begin{CodeDefaultL} +\usepackage[latin2]{inputenc} +\usepackage[T1]{fontenc} +\usepackage[english]{babel} +\end{CodeDefaultL} +\end{verbatim} + +Although \TeX{} is able to write to external files with \verb+\textsfrite+, there +were several reasons for using an external program (a \textsf{Perl} script) to +extract the source snippets from the document sources: +% +\begin{itemize} + +\item with \verb+\write+ the file always ends at end-of-line +\item \verb+\write+ forces \texttt{.tex} if no extension is specified +\item \verb+\write+ removes whitespace from end-of-line +\item \verb+\write+ translates accented letters to hat-escapes + (e.g.\ \texttt{á} to \verb+^+\verb+^e1+) unless + compiled with \texttt{latex --translate-file cp8bit.tcx} + (\texttt{--translate-file il2-t1.tcx} makes \texttt{\H{o}} in DVI + incorrect). There is the same problem when emitting UTF-8 text. +\item it is impossible to distinguish missing files from empty files, + so accidental file overwrites are hard to prevent +\item it is too late to verbatize if the verbatim text is inside + braced macro arguments + +\end{itemize} +% +The only limitations of this solution are: is not possible to \verb+\input+ +or \verb+\include+ a subfile, and then use the \texttt{code} environment in +the referrer file; the subfile has to be included with +\verb+\include{...}+ or \verb+\input{...}+ (with braces); +and the subfile must have extension \texttt{.tex}. +The first one is usually not a problem, since referrer files themselves do not +typeset text, they only include subfiles. See Subsection +\ref{codeimpl} for implementation details. + + +\subsection{\texttt{\textbackslash begin\{code\}} invocation} + +The input syntax of the \texttt{code} environment has been designed so that +typing the most common examples (short \LaTeX{} code snippets) is simple and +straightforward, but the author can have full control over all three streams +if he wants to. The contents of the environment is divided into lines. The +first two characters of each line specify the line type and the rest is the +line data. +% Lines with type \verb+% + are ignored. +The first character of the line type is usually a lowercase +ASCII letter or a punctuation symbol. Line types belong to classes, which are +denoted by capital ASCII letters. The order of the classes in the environment +is significant, but the order of the individual types or lines within the +class is irrelevant. Some classes have default lines, which are used +only if the class is omitted from the environment. The default lines make it +possible to have default CD-file header and trailer. The clases, in proper +order with allowed types in parentheses), are: +% +\begin{description} + +\item[F (f, f!, v, v!)] specify the file name. + +% G | | |ide visz egy F-beli parancs + +\item[D (d)] the \verb+\documentclass+ line, default uses article + +%%%WF kicsit fura, hogy a magyar a default, valami megjegyzessel itt +%%%enyhiteni kellene, pl hogy ez hogy irhato folul... +%% -- javítva +\item[L (l)] the preamble specific to the natural language, defaults for + Hungarian \textsf{babel}, Latin-2 \textsf{inputenc}, T1 \textsf{fontenc}. + Use the \texttt{CodeDefaultL} environment to override. + +\item[P (p$\equiv$0, t)] the preamble with the \verb+\usepackage+ lines + +\item[B (b)] \verb+\begin{document}+ + +\item[C (<$\equiv$c, >$\equiv$o, \textvisiblespace$\equiv$2, w, s, x, \%)] the document contents + +\item[E (e)] \verb+\end{document}+ + +% Z | | |ide visz az \end{code} + +\end{description} +% +The meaning of the complicated types are: +% +\begin{description} + +\item[f] Accepts a file name with extension. The use of \verb+_+ in the name + is not recommended. The extension (e.g.\ \texttt{.tex}) is mandatory. The + chapter and page numbers will be prepended to the file name (only the + page number for document classes without chapters), for example + \texttt{f foo.mp} may become \texttt{2\textunderscore 63\textunderscore foo.mp} in chapter 2, on page 63. + +\item[v] Like \texttt{f}, but removes the default lines from classes + D, L, P, B and E. This is ideal for emitting non-\LaTeX{} examples. + +\item[f!] Like \texttt{f}, but don't prepend numbers to the file name. + +\item[v!] Like \texttt{v}, but don't prepend numbers to the file name. + +\item[p$\equiv$0] Writes only to the preamble of the CD-file. + +\item[t] Writes to CD-file, appends line prefixed by \verb+%^+ + to Source. Useful to indicate in the book that a package is needed. + Example: \verb*+t \usepackage{url}+. + +\item[<$\equiv$c] Writes to Source and CD-file. +\item[>] Writes only to Sample. +\item[x] Writes to Sample and CD-file. +\item[\textvisiblespace$\equiv$2] Writes %%%WF only + to Source, CD-file and Sample. +\item[w] Writes only to CD-file. +\item[s] Writes only to Source. +\item[\%] Comment, ignored. + +\end{description} + +The \texttt{code} environment omits the Sample part from the book if the +Sample is empty, +and it omits the whole display verbatim environment (but still writes to +CD-files) if both the Sample and Source are empty. + +\subsection{An example with METAPOST code} + +If the \textsf{eempost} package is also loaded, the following code can be +used to typeset a simple, syntax-highlighted \MP{} source and its output: +\begin{verbatim} +{\PexaDefaults{listings={language=metapost}}\begin{code} +v house.mp +> \begin{EempDef}{house.1}{}{} +w beginfig(1) + u:=18bp; picture V; V:=image( + draw unitsquare scaled u xscaled 2; + fill (0,u)--(2u,u)--(u,1.5u)--cycle + withcolor red); + draw V rotated 10; + draw V shifted (3u,0); +w endfig; end +> \end{EempDef} +> \leavevmode\EempUseFig{house.1}{0}{0} +% ^^^ Dat: \leavevmode to get the Overfull \hbox warning +\end{code} +} % Dat: nothing allowed after \end{code} in its line +\end{verbatim} +% +If \textsf{eempost} is not loaded, the following code should be used instead: +% +\begin{verbatim} +{\PexaDefaults{listings={language=metapost}}\begin{code} +v house.mp +> \begin{WFile}{house.mp} +x beginfig(2) + u:=18bp; picture V; V:=image( + draw unitsquare scaled u xscaled 2; + fill (0,u)--(2u,u)--(u,1.5u)--cycle + withcolor red); + draw V rotated 10; + draw V shifted (3u,0); +x endfig; end +> \end{WFile} +> \leavevmode\includemps{house.2} +\end{code} +} +\end{verbatim} +The \verb+\includemps+ command should be defined in the preamble as: +\begin{verbatim} +\usepackage{graphicx} +\DeclareGraphicsRule{*}{mps}{*}{} +\makeatletter +\@ifundefined{Ginclude@eps}{}{\def\Ginclude@mps{\Ginclude@eps}} +\def\includemps{\@ifnextchar[\includempsb{\includempsb[]}} +\def\includempsb[#1]#2{\includempsc{#1}#2\@nil} +\def\includempsc#1#2.#3\@nil{% + \IfFileExists{#2.#3}{\includegraphics[#1]{#2.#3}}{ + \GenericWarning{}{Please run: mpost #2^^J\@gobble}}} +\makeatother +\end{verbatim} +This should work with both \textsf{dvips} and \textsf{pdflatex}. The typeset +output looks like this:\label{pag:use-listings} +\par\medskip +\noindent\begin{tabular}{@{}l@{}l@{}l@{}} +{\scriptsize1}u:=18\textbf{bp}; \textbf{picture} V; V:=\textbf{image}( &\ \vrule\ \null&\\ +{\scriptsize2}\ \ \textbf{draw} \textbf{unitsquare} \textbf{scaled} u \textbf{xscaled} 2;&\ \vrule\ \null&\\ +{\scriptsize3}\ \ \textbf{fill} (0,u)$-${}$-$(2u,u)$-${}$-$(u,1.5u)$-${}$-$\textbf{cycle}&\ \vrule\ \null& + \setbox0\hbox{\includegraphics{houses}}\ht0=0pt \box0 \\ +{\scriptsize4}\ \ \ \ \textbf{withcolor} \textbf{red}); & &\\ +{\scriptsize5}\textbf{draw} V \textbf{rotated} 10; & &\\ +{\scriptsize6}\textbf{draw} V \textbf{shifted} (3u,0); & &\\ +\end{tabular} +\par\medskip\par + + +\section{Some implementation details} + +\subsection{Starting from poor man's inline verbatim} + +The following macro, derived from a macro in the \texttt{.dtx} documentation +of David Kastrup's \textsf{binhex} package \cite{binhex}, +typesets its argument in inline verbatim mode: +% +\begin{verbatim} +{\catcode\string`>12 \gdef\stripprefix#1>{}} +\def\verbatize#1{{\ttfamily + \toks0{#1}\edef\next{\the\toks0}% Dat: make # OK + \fontdimen2\font=0pt % Dat: hide spaces + \expandafter\stripprefix\meaning\next + \unskip % Dat: strip final space, possibly after command + \fontdimen2\font=\dimen0}}% Dat: reset global change +\end{verbatim} +% +This demonstration show how useful the \TeX{} primitives \verb+\string+ and +\verb+\meaning+ are. Both of them convert tokens to characters with catcode +12 (other) or 10 (space). Token lists with spaces are hard to post-process by +\TeX{} macros, because \TeX{} macro expansion ignores spaces before +undelimited macro arguments. But it is possible to write a macro which +converts spaces to anything with catcode 12, for example the \verb+\sca+ +macro below does this: +% +\begin{verbatim} +\begingroup\catcode\string``12 \lccode```\%\lowercase{\endgroup + \def\scc#1 {\ifx\hfuzz#1\else#1`\expandafter\scc\fi}} +\def\scb#1#2{\scc#2\hfuzz#1} \def\sca{\scb{ }} +% try with: \message{\sca{foo bar }} +\end{verbatim} +% +It is possible to change \verb+%+ +in the definition above to anything, including a space: the replacement +character will have catcode 12. After such a conversion, the text to be +emitted can be easily processed to add \TeX{} macros, change catcodes back to +13 for ISO Latin high accented characters, replace spaces with appropriate +constructs, insert \verb+\allowbreak+ to the right places to enable line +breaks etc. The \verb+\PVerb+ macro, when invoked in inner mode (i.e.\ read +inside a macro argument) works this way, and respects the options specified +by the author. + +\subsection{Hex escapes with output translation}\label{tcx} + +The \TeX{} primitives \verb+\write+, \verb+\message+ and \verb+\errmessage+ +may escape some characters when printing them. By default, \TeX{} changes the +code ranges 0--31 and 127--255 (the codes outside the printable ASCII range), +escaping such codes with a \verb+^^+: for example, +the tabulator (code 9) becomes \verb+^^I+, and characters having a high code +in the font (not the input) encoding are dumped in hexadecimal, for example +\texttt{\H{o}} (having code 174 in T1 encoding) becomes \texttt{^^ae}. +(This behaviour depends on the default \texttt{.tcx} file the \TeX{} +distribution uses. No translation occurs with \textsf{cp8bit.tcx}. +To spot the difference, run +\verb+tex -translate-file cp8bit "\messa+\allowbreak\verb+ge{^^I^^1f+\allowbreak\verb+á}\end"+, and then change +\texttt{cp8bit} to \texttt{.missing.}, and run again.) +The transformation is lossy: %, for example % e.g.\ +both +\verb+\message{+\texttt{\H{o}}\verb+}+ and +\verb+\message{\string^^ae}+ yield the same result: \verb+^^ae+. Escaping the caret +as \verb+^^5e+ doesn't help either, because the \TeX{} unescapes carets +recursively when reading back the written file. Since ISO Latin +accented characters are +more often needed in verbatim environments than double carets, +\textsf{examplep} does the necessary unescaping when it reads the file back. +% Dat: doesn't work The back-transformation works with UTF-8, too, because it is timed properly. +The back-transformation doesn't work with UTF-8, because the 2nd byte is not +decoded by the time the first one is being executed. +The unescaping would be done by \TeX{} itself if the caret had its original +catcode 7, but that would imply that the non-escaping, verbatim carets +wouldn't work. + +The unescaping is implemented in a straighforward, but ugly way in the +\verb+\pexa@dohex@low+\ldots{} macros. The caret escapes are parsed in a +huge \verb+\if+%\ldots +\verb+\else+\allowbreak\verb+\if+ construct nested in 40 levels, and once +the hexadecimal code is available and converted to upper case, the +\verb|\lccode`+="|$\langle$code$\rangle$\verb*|\lowercase{+}| construct is +used to insert the appropriate character with catcode 12 (\verb+~+ is +used instead of \verb|+| to get an active character, catcode 13). The +construct is not expandable, but it works because it is used for typesetting. +The caret is made active and defined to execute \verb+\pexa@dohex+, so each +caret in the file will get unescped. + +\subsection{Disabling ligatures} + +The only way to disable a ligature in \TeX{} is to insert a nonexpandable +tokens into the input stream between the characters forming the ligature. +For example, \verb+f{}i+ or \verb+f\relax i+ can be used to get ``f{}i'' +instead of ``fi''. The most important ligatures (in addition to ligature +letters) to be disabled in verbatim mode are: +\verb+<<+ \verb+>>+ \verb+?`+ \verb+!`+ \verb+,,+ \verb+``+ \verb+''+ +\verb+--+ and \verb+---+. This can be accomplised by inserting a \verb+\relax+ +token in front of each \verb+`+ \verb+'+ \verb+,+ \verb+-+ \verb+<+ +and \verb+>+. The \verb+\pexa@noligs@some+ command of \textsf{examplep} does +exactly this, for example, it defines +\verb+{\lccode`~`<13 \gdef~{\relax+\allowbreak\verb+\string~}}+. The definition +slightly different from the one of the \verb+\@noligs+ command in the +\LaTeX{} kernel: \verb+\def<{\leavevmode\kern\z@\char`\<}+; but the effect is +the same. The \verb+\pexa@noligs@most+ command, on the other hand, makes +all characters with category code 12 in the range 32\ldots127 active, and +adds \verb+\relax+ to both sides. This change doesn't affect ASCII or +accented letters, but usually there are no ligatures with letters in +typewriter fonts. See also the \texttt{noligs=} load option. + +\subsection{Detecting inner/outer brace in inline verbatim mode} + +The \verb+\PVerb+ commands work differently based on whether they are inside +a macro argument or not. More precisely, they detect whether they are able +to change the catcode of the following token. If so, they are in outer mode +(i.e.\ outside a macro argument), so they change all the other catcodes as +well, so consecutive spaces and comment characters will be included in +verbatim, too. Otherwise, they are in inner mode, their argument is already +read and tokenized by \TeX{}'s eyes, so changing catcodes is pointless. + +The auto-detection works this way: the catcode of all the special characters +(as enumerated in \verb+\dospecials+; including braces) is changed to 3 +(math-shift). Then the next token is read into \verb+\reserved@a+ with +\verb*+\afterassignment\pexa@+\allowbreak\verb+cverb@gottoken\let\reserved@a= +. No tokens are +ignored this way, not even spaces. The \verb+\pexa@cverb@gottoken+ macro then +examines the catcode of the character in +\verb+\reserved@a+, and if it is 3, it continues in +outer mode, otherwise it continues in inner mode. In inner mode, the next +token is forced to be an open-brace, because verbatim material with braces +not nested cannot be read into inner mode anyway (\TeX{} would print an error +message when it is trying to find the end of the macro argument containing +the \verb+\PVerb+ construct). + +Another common trick is used when parsing the argument in outer mode when it +is delimited by braces. Normally a \TeX{} macro expansion +(using the definition \verb+\def\pexa@cverb@outerc#1{...}+) can read an +argument that is in braces, but in our case the very first opening brace has +been already read (by \verb+\let+ above), so we have to insert it back: +\verb+\catcode`\{1 \catcode`\}2 \ex+\allowbreak\verb+pandafter\pexa@cverb@outerc\expandafter{\iffalse}\fi+. +The \verb+\iffalse+\allowbreak\verb+}\fi+ here is needed for making the definition properly +nested. + +\subsection{Inline verbatim in section titles} + +The \TeX{} command \verb+\write+, \verb+\message+ and \verb+\edef+ fully +expand their arguments, and similar expansion is enforced by the +\verb+\markboth+ built-in \LaTeX{} macro for section titles and page +headings. Therefore macros in section titles have to be protected so their +expansion is delayed until the section title is typeset. \LaTeX{} offers +\verb+\protect+ for this: if the macro control sequence is preceded by +\verb+\protect+, its expansion is properly delayed; the expansion of the +argument has to be delayed manually in a similar way. Some macros have +\verb+\protect+ion included; they are called ``robust''. If the definition a +macro starts with \verb+\DeclareRobustCommand+ instead of \verb+\newcommand+, +the macro is defined to be robust (and its body can be retrieved by looking +at the control sequence with a space added, e.g.\ +\verb*+\expandafter\show\csname sqrt \endcsname+). + +\verb+\protect+ can have three definitions depending on what time it is +processed: it is \verb+\string+ in a \verb+\typeout+ or a \LaTeX{} error or +warning message (try \verb+\typeout{\meaning\protect}+); +it is \verb+\noexpand\protect\noexpand+ when +\verb+\write+ing to a file (most commonly the \texttt{.aux} file); otherwise +it is just \verb+\relax+ ($\equiv{}$\verb+\@typeset@protect+; try +\verb+\pagestyle{headings}\section{\meaning\pro+\allowbreak\verb+tect}+ and spot the difference +between the main text, the section title and the \texttt{.aux} file). + +The \verb+\÷+ and \verb+\Q+ inline verbatim commands are made robust, so they +can be used in macro arguments. In fact, they are extra-robust, since they +take care of protecting their arguments when being written to a file by +\LaTeX{}. Protecting here means adding \verb+\noexpand+ in front of each +token in the argument. The token parsing is easy since the argument -- by the +nature of these commands -- may not contain braces or spaces. The +implementation looks like this. +% +\begin{verbatim} +\long\def\÷#1÷{\Q{#1}} +\long\def\Q{\ifx\protect\@typeset@protect\expandafter\@gobble\fi + \@thirdofthree\@firstoftwo\displayit\protectit} +\def\displayit#1{...} +\def\protectit#1{\noexpand\÷\protectnext#1÷} +\long\def\protectnext#1{\noexpand#1% + \ifx#1÷\else\expandafter\protectnext\fi} +\end{verbatim} +% +The first trick is in the body of \verb+\Q+: the argument is passed to +either \verb+\displayit+ or \verb+\protectit+, depending on the current value +of \verb+\protect+. If the condition is true, \verb+\@gobble+ is called, +which removes \verb+\@thirdofthree+, so \verb+\@firstoftwo+ will choose +\verb+\displayit+ (otherwise, \verb+\@thirdofthree+ chooses +\verb+\protectit+). +The second, more classical trick is the r\^ole of +\verb+\expandafter+ in the definition of \verb+\protectnext+: it makes the +\verb+\fi+ token disappear, so the tail-recursive call to \verb+\protectnext+ +will grab the next token into \verb+#1+ instead of \verb+\fi+ itself. + + +\subsection{Special hyphenchar in inline verbatim}\label{char'30} + +When inline verbatim is hyphenated, care has to be taken to make the +discretionary hyphen different from a regular, verbatim hyphen. (There is a +similar problem with spaces disappearing when the line is broken; to avoid +this, try setting the option \texttt{pverb-space=visbreak} or +\texttt{pverb-space=invdisc}.) \TeX{} auto-hyphenation takes the +discretionary hyphen from the \verb+\hyphenchar+ of the font. So the solution +is adding a new glyph to the verbatim font, changing the font encoding +vector to include the glyph, and then setting \verb+\hyphenchar+. + +We have chosen character position 24 (per-thousand sign) of the T1 encoding to +be replaced by a soft hyphen (\includegraphics[scale=0.009]{shorthyp_t1xtts}), +which is deliberately narrower than all the other characters, so the +reader immediately sees its function. For example: +``\texttt{foo\includegraphics[scale=0.009]{shorthyp_t1xtts}\break bar}''. +We have drawn the glyph in \textsf{Fontforge}, saved the data to PFB, +converted it to human-readable format with the command +\texttt{type1fix.pl shorthyp.pfb gsx: shorthyp.gsx}, extracted the human +readable glyph definition (\verb+/short+\allowbreak\verb+hyp { ... }+) from the output. +We have changed the \texttt{/FontName} and +injected the glyph to original font with the following command: +% +\begin{verbatim} +perl -x -S type1fix.pl --set-leniv=0 --dump-spaces=no --pack \ + --dump-bars --dump-stde --dump-ends=no --debug-warnings \ + --chk-insize=no --set-uniqueid=random --set-fontname=t1xtts \ + --set-glyph="/shorthyp { 50 354 hsbw 315 vmoveto -17 vlineto 0 + -8 0 -8 6 -4 rrcurveto 4 -6 8 0 5 0 rrcurveto 195 hlineto -124 + vlineto -11 0 -21 15 vhcurveto 2 0 3 1 2 1 rrcurveto 10 2 1 12 + 0 12 rrcurveto 0 8 -1 8 0 5 rrcurveto 130 vlineto 0 5 1 7 0 7 + rrcurveto 0 12 -2 11 -11 3 rrcurveto -5 1 -6 0 -5 0 rrcurveto + -12 0 -12 -1 -10 0 rrcurveto -98 hlineto -16 0 -19 2 -17 0 + rrcurveto -32 -6 -3 -24 hvcurveto closepath endchar} def" \ + t1xtt.pfb pfb: t1xtt-shorthyp.pfb +\end{verbatim} +% +We have changed six lines in \textsf{tex256.enc} to match the glyph names +in the font (e.g. \texttt{/endash} $\to$ \texttt{/rangedash}), and we have +changed position 24 to \texttt{/shorthyp}. We have also changed the name of +the encoding in the beginning of the file. We have inserted the following +line to the PostScript font map files (e.g.\ \textsf{psfonts.map}), without +the line break: +% +% into psfonts.map: +% ul9r8r LuxiMono "TeXBase1-shorthypEncoding ReEncodeFont" <8r-shorthyp.enc <ul9r8a-shorthyp.pfb +\begin{verbatim} +t1xtts t1xtts "TeX256-shorthypEncoding ReEncodeFont" + <tex256-shorthyp.enc <t1xtt-shorthyp.pfb +\end{verbatim} +% +We have +also added a new TFM file based on the old one. We have dumped the old one +with \texttt{tftopl -charcode-format=octal t1xtt.tfm}, modified the +width (\texttt{CHARWD}) of character 24 (\texttt{CHARACTER O 30}), and saved +the modifications with \texttt{pltotf modified.pl t1xtts.tfm}. +We've added the \LaTeX{} font map file \textsf{t1xtts.fd} with the following +content: +% +\begin{verbatim} +\DeclareFontFamily{T1}{xtts}{\hyphenchar\font\m@ne} +\DeclareFontShape {T1}{xtts}{m}{n}{<->t1xtts} +\end{verbatim} +% +The \verb+\hyphenchar+ settings above disables automatic word hyphenation, so +words inside \verb+\texttt+ etc.\ won't be accidentally hyphenated. We have +copied all the files above to the appropriate directories and we have run +\textsf{mktexlsr} to update the file list. We have included some options in +\verb+\PexaDefaults+ line in the document preamble: + \texttt{pverb-hyphenchar=char'30} (for automatic word hyphenation) + \texttt{pverb-linebreak=char}, + \texttt{pverb-linebreakchar=}\verb*+{\string\char'30 }+ (insert\-ed around symbols). +We have also defined +\verb+\def\pexa@verbatimfont{\normal+\allowbreak\verb+font\fontfamily{xtts}\selectfont}+, +and we have made sure that the T1 encoding is in use +(\verb+\usepackage{t1enc}+). + +The overall effect of these modifications was that \textsf{examplep} now used +our glyph for automatic word hyphenation and as discreationary hyphen around +symbols in inline verbatim mode. The demonstrations above shows that it is +quite complicated to change a single glyph in a \LaTeX{} font. It is hoped +that the situtation will improve with \TeX's successors. + + +\subsection{Passing information about the CD-files to \textsf{wrfiles.pl}}\label{codeimpl} + +\textsf{wrfiles.pl} is used to extract the CD-files from the \LaTeX{} sources +of a book. The reasons why an external program is used instead of \TeX{}'s +built-in \verb+\write+ command are described in Subsection +\ref{codewritereasons}. + +The file names and environment start line numbers are passed to +\textsf{wrfiles.pl} in the \texttt{.aux} file(s). For example, the line +\verb+\@gobble{code:foo.tex:156:2_pic3.+\allowbreak\verb+mp}+ is a declaration that there is a +\texttt{code} environment starting at line 156 in the file \texttt{foo.tex}. +\textsf{wrfiles.pl} understands such declarations, and it also understands +lines like \verb+\@input{foo1.aux}+, so dumping works even if the document is +separated to several \verb+\include+d source files. The declaration above is +ignored by \LaTeX{} when it reads back the \texttt{.aux} file (because +\verb+\@gobble+ gobbles its argument). + +Although the \verb+\inputlineno+ primitive is mentioned twice in the +\TeX{}book \cite{texbook}, its -- rather straightforward -- purpose is not +documented there. But the real problem is that \TeX{} doesn't remember the +name of the file being read. \verb+\jobname+ contains the name of the +top-level \texttt{.tex} file, so it doesn't work when that file +\verb+\include+s or \verb+\input+s subfiles containing \texttt{code}. The +\textsf{codep} package thus modifies the \verb+\InputIfFileExists+ command to +save the file name to the macro \verb+\codep@code@@inputfile+ if the +extension is \texttt{.tex}. (The other most common extension after the preamble is +\texttt{.fd}: such a file is loaded each time a \LaTeX{} font that has not +been used yet is selected.) The implicit limitation here that \texttt{code} +won't work unless the extension of the file included is \texttt{.tex}. +Hooking \verb+\InputIfFileExists+ affects \verb+\include{...}+ and +\verb+\input{...}+, but not not \verb*+\input ...+, \verb+\documentclass+ or +\verb+\usepackage+. This is not a problem if the author remember that he has +to use braces around the file name. + +Since there is no hook for \verb+\endinput+ (and some packages rely on that +\verb+\endinput+ is an expandable primitive), it is not possible to set up a +stack of names of files being read. Thus, if file $A$ has included file $B$, +an after that \texttt{code} environment placed in $A$ will not work, because +the declaration line read by \textsf{wrfiles.pl} will contain the name of $B$ +instead of $A$. This is not a serious limitation, becase files including +other files usually don't typeset text by themselves after the inclusion. + +The primary reason why \textsf{wrfiles.pl} needs the \texttt{.aux} +file is that it has to embed the page and chapter numbers into the file +names. Although \textsf{wrfiles.pl} could find the source file with the +\texttt{code} environments by trying to match line numbers with all source +files in the current directory, we have decided to make it fail when the file +name is not emitted properly into the declaration, so it is sure that the +examples in the book and on the CD are consistent. + + +\section{Future work} + +The most important features to be added and other improvement possibilites: + +\begin{itemize} + +%\item func-tion better hyphenation point in \verb+\Q+ than functi-on +\item a better approach towards automatic hyphenation of inline verbatim, + after studies in typography +\item allow wider sample if source is small enough +\item why doesn't \verb+\selectlanguage+ work inside + \verb+\begin{PSource}[srcstyle=+\allowbreak\verb+leftboth]+ +\item \verb+\PVerb{foo}+ mustn't insert ``$\lnot$'' if foo is at end-of-line +\item \verb+\PVerb{...}+ inner unnested braces (\verb+\futurelet+?) +\item differentiated \verb+\penalty+ values in \verb+\PVerb+ +\item paragraph mode should work with side-by-side displays (of course, + measuring the width of the Source has still to be done in aligned mode) +\item ASCII tabulator (9) characters aren't supported properly, they are just + converted to spaces. The width of the tab character should depend on its + horizontal position in the line. (With \texttt{listings=}, the results are + already correct.) +\item framing and background color support to display verbatim +\item accented characters should work with \textsf{listings} and + \verb+\PexaShowBoth+. The original catcode of \verb+^+ should be kept + so \TeX{} itself would parse the hex escapes. +\item an interface to \verb+\lstinline+ in \textsf{listings}, with line + breaks allowed +\end{itemize} + +\section{Conclusion} + +\textsf{examplep}, as it is now, is a highly customizable \LaTeX{} package +that provides both inline and display verbatim mode with several advanced +features, many of which are not available in any other packages. The +\textsf{code} environment is also provided which can typeset both the Source +and the Sample column of a side-by-side display verbatim from the same +\LaTeX{} source stream, furthermore it can emit the stand-alone working +version of the Source into a CD-file. These features make the \textsf{code} +environment especially useful for sofware textbook and manual authoring. The +whole \textsf{examplep} distribution is under the GNU GPL, and it is freely +available from CTAN. An earlier version of the packages was used to typeset +all the examples in a 770-page introductionary book about \LaTeX{}. + +\textsf{examplep} is not complete. Some important features are not +implemented yet and the package has not been tested thoroughly. Some parts of +the code are really ugly, partially because it has not been polished up after +writing, and partially because the architecture of \TeX{} and \LaTeX{} +doesn't provide an elegant way to address the problem. For example, active +characters are overloaded: they are used by \textsf{inputenc}, \textsf{babel} +(shorthands) and \textsf{listings} (syntax highlighting) for different +purposes -- these packages have to make extra effort to cooperate with each +other. We hope that \TeX's successors will improve these +conditions, and the core system will provide a generic way to tokenize +verbatim text instead of changing catcodes. + +\iffalse +\bibliographystyle{plain} +\bibliography{eurotex_2005_examplep} +\else +\begin{thebibliography}{1} + +\bibitem{listings} +Carsten Heinz. +\newblock {\em The \textsf{Listings} Package}, 7~September 2004. +\newblock \\CTAN:\texttt{macros/latex/contrib/listings/listings-1.3.dtx}. + +\bibitem{binhex} +David Kastrup. +\newblock {\em The \texttt{binhex.tex} package for expansible conversion into + binary-based number systems}, 2001. +\newblock \\CTAN:\texttt{macros/generic/kastrup/binhex.dtx}. + +\bibitem{texbook} +Donald~E. Knuth. +\newblock {\em The {{\TeX}book}}. +\newblock Addison--Wesley, 1984. + +\bibitem{lakk} +Ferenc Wettl, Gyula Mayer, and P\'eter Szab\'o. +\newblock {\em {\LaTeX} k\'ezik\"onyv}. +\newblock Panem, Budapest, 2004. + +\bibitem{fancyvrb} +Timothy~Van Zandt, Denis Girou, and Sebastian Rahtz. +\newblock {\em The `\textsf{fancyvrb}' package. Fancy Verbatims in \LaTeX{}}, + 1998. +\newblock \\CTAN:\texttt{macros/latex/contrib/fancyvrb/fancyvrb.dtx}. + +\end{thebibliography} +\fi + +\end{document} |