% % 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 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}