diff options
author | Karl Berry <karl@freefriends.org> | 2019-02-28 22:37:22 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2019-02-28 22:37:22 +0000 |
commit | 97eed0e5d61bdb3aa50b351f2cdae80c39e6bad7 (patch) | |
tree | 2a7bdec96bce1add39588436597a6caf8cd715a7 /Master/texmf-dist/source/latex/listings/listings.dtx | |
parent | b37375f523e3b3b381dae4bbda2befbfd776e863 (diff) |
listings (28feb19)
git-svn-id: svn://tug.org/texlive/trunk@50175 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/listings/listings.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/listings/listings.dtx | 2170 |
1 files changed, 1191 insertions, 979 deletions
diff --git a/Master/texmf-dist/source/latex/listings/listings.dtx b/Master/texmf-dist/source/latex/listings/listings.dtx index 4756e7e2400..2a9216744ab 100644 --- a/Master/texmf-dist/source/latex/listings/listings.dtx +++ b/Master/texmf-dist/source/latex/listings/listings.dtx @@ -25,13 +25,11 @@ % 1.3 of this license or (at your option) any later version. % The latest version of this license is in % http://www.latex-project.org/lppl.txt -% and version 1.3 or later is part of all distributions of LaTeX +% and version 1.3c or later is part of all distributions of LaTeX % version 2003/12/01 or later. % % The package has the LPPL maintenance status "maintained". % -% $Id$ -% % The Current Maintainer is Jobst Hoffmann <j.hoffmann(at)fh-aachen.de>. % % end of software license @@ -64,20 +62,33 @@ %\lstisaspect[comment styles]{b,d,l,n,s,ib,id,il,in,is} %\lstisaspect[pod]{printpod,podcomment} %\lstisaspect[escape]{texcl,escapebegin,escapeend,escapechar,escapeinside,mathescape} -%\lstisaspect[keywords]{sensitive,classoffset,keywords,morekeywords,deletekeywords,keywordstyle,ndkeywords,morendkeywords,deletendkeywords,ndkeywordstyle,keywordsprefix,otherkeywords} +%\lstisaspect[keywords]{sensitive,classoffset,keywords,morekeywords,^^A +% deletekeywords,keywordstyle,ndkeywords,morendkeywords,deletendkeywords,^^A +% ndkeywordstyle,keywordsprefix,otherkeywords} %\lstisaspect[emph]{emph,moreemph,deleteemph,emphstyle} %\lstisaspect[tex]{texcs,moretexcs,deletetexcs,texcsstyle} %\lstisaspect[directives]{directives,moredirectives,deletedirectives,directivestyle} %\lstisaspect[html]{tag,usekeywordsintag,tagstyle,markfirstintag} -%\lstisaspect[keywordcomments]{keywordcomment,morekeywordcomment,deletekeywordcomment,keywordcommentsemicolon} +%\lstisaspect[keywordcomments]{keywordcomment,morekeywordcomment,^^A +% deletekeywordcomment,keywordcommentsemicolon} %\lstisaspect[index]{index,moreindex,deleteindex,indexstyle,\string\lstindexmacro} -%\lstisaspect[procnames]{procnamestyle,indexprocnames,procnamekeys,moreprocnamekeys,deleteprocnamekeys} -%\lstisaspect[style]{style,\string\lstdefinestyle,\string\lst@definestyle,\string\lststylefiles} -%\lstisaspect[language]{language,alsolanguage,defaultdialect,\string\lstalias,\string\lstdefinelanguage,\string\lst@definelanguage,\string\lstloadlanguages,\string\lstlanguagefiles} -%\lstisaspect[formats]{format,fmtindent,\string\lstdefineformat,\string\lst@defineformat,\string\lstformatfiles} -%\lstisaspect[labels]{numbers,numberstyle,numbersep,stepnumber,numberblanklines,firstnumber,\string\thelstnumber,numberfirstline} -%\lstisaspect[lineshape]{xleftmargin,xrightmargin,resetmargins,linewidth,lineskip,breaklines,breakindent,breakautoindent,prebreak,postbreak,breakatwhitespace} -%\lstisaspect[frames]{framexleftmargin,framexrightmargin,framextopmargin,framexbottommargin,backgroundcolor,fillcolor,rulecolor,rulesepcolor,rulesep,framerule,framesep,frameshape,frameround,frame} +%\lstisaspect[procnames]{procnamestyle,indexprocnames,procnamekeys,^^A +% moreprocnamekeys,deleteprocnamekeys} +%\lstisaspect[style]{style,\string\lstdefinestyle,\string\lst@definestyle,^^A +% \string\lststylefiles} +%\lstisaspect[language]{language,alsolanguage,defaultdialect,^^A +% \string\lstalias,\string\lstdefinelanguage,\string\lst@definelanguage,^^A +% \string\lstloadlanguages,\string\lstlanguagefiles} +%\lstisaspect[formats]{format,fmtindent,\string\lstdefineformat,^^A +% \string\lst@defineformat,\string\lstformatfiles} +%\lstisaspect[labels]{numbers,numberstyle,numbersep,stepnumber,^^A +% numberblanklines,firstnumber,\string\thelstnumber,numberfirstline} +%\lstisaspect[lineshape]{xleftmargin,xrightmargin,resetmargins,linewidth,^^A +% lineskip,breaklines,breakindent,breakautoindent,prebreak,postbreak,^^A +% breakatwhitespace} +%\lstisaspect[frames]{framexleftmargin,framexrightmargin,framextopmargin,^^A +% framexbottommargin,backgroundcolor,fillcolor,rulecolor,rulesepcolor,^^A +% rulesep,framerule,framesep,frameshape,frameround,frame} %\lstisaspect[make]{makemacrouse} %\lstisaspect[fancyvrb]{fancyvrb,fvcmdparams,morefvcmdparams} %\lstisaspect[lgrind]{lgrindef,\string\lstlgrindeffile} @@ -94,7 +105,8 @@ % inputencoding,delim,moredelim,deletedelim,upquote,numberbychapter,^^A % \string\lstMakeShortInline,\string\lstDeleteShortInline} %\lstisaspect[doc]{lstsample,lstxsample}^^A environment -%\lstisaspect[experimental]{includerangemarker,rangebeginprefix,rangebeginsuffix,rangeendprefix,rangeendsuffix,rangeprefix,rangesuffix} +%\lstisaspect[experimental]{includerangemarker,rangebeginprefix,rangebeginsuffix,^^A +% rangeendprefix,rangeendsuffix,rangeprefix,rangesuffix} % %^^A %^^A The long awaited beginning of documentation @@ -119,7 +131,7 @@ % Hoffmann became the maintainer of the \packagename{listings} % package in 2013; see the Preface for details.}~ % % \textless\lstemail\textgreater} -% \date{2018/09/02\enspace\enspace Version 1.7\ \box\abstractbox} +% \date{2019/02/27\enspace\enspace Version 1.8b\ \box\abstractbox} % \def\lstemail{\href{mailto:j.hoffmann@fh-aachen.de}{\texttt{j.hoffmann(at)fh-aachen.de}}} % \ifhyper % \hypersetup{pdfsubject=Package guide,pdfauthor=Jobst Hoffmann <j.hoffmann(at)fh-aachen.de>} @@ -307,7 +319,9 @@ % Note that you possibly need to specify the relative path to the file. % Here now the result is printed below the verbatim code since both together % don't fit the text width. -% \begin{lstsample}{\lstset{comment=[l]\%,columns=fullflexible}}{\lstset{alsoletter=\\,emph=\\lstinputlisting,emphstyle=\rstyle}\lstaspectindex{\lstinputlisting}{}} +% \begin{lstsample}{\lstset{comment=[l]\%,columns=fullflexible}}^^A +% {\lstset{alsoletter=\\,emph=\\lstinputlisting,emphstyle=\rstyle}^^A +% \lstaspectindex{\lstinputlisting}{}} % \lstinputlisting[lastline=4]{listings.sty} % \end{lstsample} % \begin{advise} @@ -330,7 +344,8 @@ % Keywords are typeset bold, comments in italic shape, and spaces in strings % appear as \textvisiblespace. You don't like these settings? Look at this: %\ifcolor -% \begin{lstxsample}[basicstyle,keywordstyle,identifierstyle,commentstyle,stringstyle,showstringspaces] +% \begin{lstxsample}[basicstyle,keywordstyle,identifierstyle,commentstyle,^^A +% stringstyle,showstringspaces] % \lstset{% general command to set parameter(s) % basicstyle=\small, % print whole listing small % keywordstyle=\color{black}\bfseries\underbar, @@ -341,7 +356,8 @@ % showstringspaces=false} % no special string spaces % \end{lstxsample} %\else -% \begin{lstxsample}[basicstyle,keywordstyle,identifierstyle,commentstyle,stringstyle,showstringspaces] +% \begin{lstxsample}[basicstyle,keywordstyle,identifierstyle,commentstyle,^^A +% stringstyle,showstringspaces] % \lstset{% general command to set parameter(s) % basicstyle=\small, % print whole listing small % keywordstyle=\bfseries\underbar, @@ -479,7 +495,9 @@ % One more little teaser? Here you are. But note that the result is not % produced by the \LaTeX\ code on the right alone. The main parameter is % hidden. -% \begin{lstsample}{\lstset{literate={:=}{{$\gets$}}1 {<=}{{$\leq$}}1 {>=}{{$\geq$}}1 {<>}{{$\neq$}}1}}{} +% \begin{lstsample}{^^A +% \lstset{literate={:=}{{$\gets$}}1 {<=}{{$\leq$}}1 {>=}{{$\geq$}}1 ^^A +% {<>}{{$\neq$}}1}}{} % \begin{lstlisting} % if (i<=0) then i := 1; % if (i>=0) then i := 0; @@ -528,7 +546,7 @@ % program listings and not a document with some listings, this is the best % choice. % -% \paragraph{\href{http://www.ctan.org/tex-archive/nonfree/support/lgrind}{\packagename{LGrind}}} +% \paragraph{\href{http://mirror.ctan.org/support/lgrind}{\packagename{LGrind}}} % is a cross compiler and comes with many predefined programming languages. % For example, you can put the code on the right in your document, invoke % \packagename{LGrind} with \texttt{-e} option (and file names), and run the @@ -579,12 +597,12 @@ % chosen by command-line option. Unfortunately it isn't documented how other % programming languages can be added. % -% \paragraph{\href{http://www.ctan.org/tex-archive/support/C++2LaTeX-1_1pl1}{\packagename{\Cpp2\LaTeX}}} +% \paragraph{\href{http://mirror.ctan.org/support/C++2LaTeX-1_1pl1}{\packagename{\Cpp2\LaTeX}}} % is a C/\Cpp\ to \LaTeX\ converter. You can specify the fonts for comments, % directives, keywords, and strings, or the size of a tabulator. But as far as % I know you can't number lines. % -% \paragraph{\href{http://www.ctan.org/tex-archive/support/slatex}{\packagename{S\LaTeX}}} +% \paragraph{\href{http://mirror.ctan.org/support/slatex}{\packagename{S\LaTeX}}} % is a pretty-printing Scheme program (which invokes \LaTeX\ automatically) % especially designed for Scheme and other Lisp dialects. It supports stand % alone files, text and display listings, and you can even nest the @@ -592,14 +610,15 @@ % Keywords, constants, variables, and symbols are definable and use of % different styles is possible. No line numbers. % -% \paragraph{\href{http://www.ctan.org/tex-archive/support/tiny_c2l}{\packagename{tiny\textunderscore c2ltx}}} +% \paragraph{\href{http://mirror.ctan.org/support/tiny_c2l}^^A +% {\packagename{tiny\textunderscore c2ltx}}} % is a C/\Cpp/Java to \LaTeX\ converter based on \packagename{cvt2ltx} (or the % other way round?). It supports line numbers, block comments, \LaTeX\ code % in/as comments, and smart line breaking. Font selection and tabulators are % hard-coded, i.e.~you have to rebuild the program if you want to change the % appearance. % -% \paragraph{\href{http://www.ctan.org/tex-archive/macros/latex/contrib/misc}{\packagename{listing}}} +% \paragraph{\href{http://mirror.ctan.org/macros/latex/contrib/misc}{\packagename{listing}}} % ---note the missing \packagename{s}---is not a pretty-printer and the % aphorism about documentation at the end of \texttt{listing.sty} is not % true.\space ^^A :-) @@ -607,11 +626,12 @@ % All font selection and indention must be done by hand. However, it's % useful if you have another tool doing that work, e.g.~\packagename{LGrind}. % -% \paragraph{\href{http://www.ctan.org/tex-archive/macros/latex/contrib/alg}{\packagename{alg}}} +% \paragraph{\href{http://mirror.ctan.org/macros/latex/contrib/alg}{\packagename{alg}}} % provides essentially the same functionality as \packagename{algorithms}. % So read the next paragraph and note that the syntax will be different. % -% \paragraph{\href{http://www.ctan.org/tex-archive/macros/latex/contrib/algorithms}{\packagename{algorithms}}} +% \paragraph{\href{http://mirror.ctan.org/macros/latex/contrib/algorithms}^^A +% {\packagename{algorithms}}} % goes a quite different way. You describe an algorithm and the package % formats it, for example % \begin{center} @@ -645,7 +665,8 @@ % and floating algorithms, a list of algorithms, and you can customize the % terms \textbf{if}, \textbf{then}, and so on. % -% \paragraph{\href{http://www.mimuw.edu.pl/~wolinski/pretprin.html}{\packagename{pretprin}}} +% \paragraph{\href{http://www.mimuw.edu.pl/~wolinski/pretprin.html}^^A +% {\packagename{pretprin}}} % is a package for pretty-printing texts in formal languages---as the title % in TUGboat, Volume 19 (1998), No.~3 states. It provides environments which % pretty-print \emph{and} format the source code. Analyzers for Pascal and @@ -657,7 +678,8 @@ % |}| have their usual meanings. This means that you can use commands in the % verbatims, e.g.~select different fonts or enter math mode. % -% \paragraph{\href{http://www.ctan.org/tex-archive/macros/latex/contrib/moreverb}{\packagename{moreverb}}} +% \paragraph{\href{http://mirror.ctan.org/macros/latex/contrib/moreverb}^^A +% {\packagename{moreverb}}} % requires \packagename{verbatim} and provides verbatim output to a file, % `boxed' verbatims and line numbers. % @@ -665,7 +687,8 @@ % defines an improved version of the standard \texttt{verbatim} environment and % a command to input files verbatim. % -% \paragraph{\href{http://www.ctan.org/tex-archive/macros/latex/contrib/fancyvrb}{\packagename{fancyvrb}}} +% \paragraph{\href{http://mirror.ctan.org/macros/latex/contrib/fancyvrb}^^A +% {\packagename{fancyvrb}}} % is, roughly speaking, a superset of \packagename{alltt}, % \packagename{moreverb}, and \packagename{verbatim}, but many more parameters % control the output. The package provides frames, line numbers on the left or @@ -702,7 +725,7 @@ % either version 1.3 of this license or (at your option) any later version. % The latest version of this license is in % \href{http://www.latex-project.org/lppl.txt}{http://www.latex-project.org/lppl.txt} -% and version 1.3 or later is part of all distributions of LaTeX version +% and version 1.3c or later is part of all distributions of LaTeX version % 2003/12/01 or later. % % \paragraph{Contacts} @@ -1038,7 +1061,8 @@ % \ref{gSeduceToUse}. Here now we deal with continued listings. % You have two options to get consistent line numbering across listings. % -% \begin{lstsample}[firstnumber]{\lstset{numbers=left,numberstyle=\tiny,stepnumber=2,numbersep=5pt}}{} +% \begin{lstsample}[firstnumber]{\lstset{numbers=left,numberstyle=\tiny,^^A +% stepnumber=2,numbersep=5pt}}{} % \begin{lstlisting}[firstnumber=100] % for i:=maxint to 0 do % begin @@ -1338,7 +1362,8 @@ % The examples are typeset with centered \texttt{minipage}s. That's the reason % why you can't see that line numbers are printed in the margin. Now we % separate the minipage margin and the minipage by a vertical rule: -% \begin{lstsample}{\lstset{frame=l,framesep=0pt,numberstyle=\tiny,stepnumber=2,numbersep=5pt}}{} +% \begin{lstsample}{\lstset{frame=l,framesep=0pt,numberstyle=\tiny,stepnumber=2,^^A +% numbersep=5pt}}{} % Some text before % \begin{lstlisting} % for i:=maxint to 0 do @@ -1349,7 +1374,8 @@ % \end{lstsample} % The listing is lined up with the normal text. The parameter \ikeyname{xleftmargin} % moves the listing to the right (or left if the dimension is negative). -% \begin{lstsample}{\lstset{frame=l,framesep=0pt,numberstyle=\tiny,stepnumber=2,numbersep=5pt}}{} +% \begin{lstsample}{\lstset{frame=l,framesep=0pt,numberstyle=\tiny,stepnumber=2,^^A +% numbersep=5pt}}{} % Some text before % \begin{lstlisting}[xleftmargin=15pt] % for i:=maxint to 0 do @@ -1445,7 +1471,7 @@ % and make similar definitions for constant or function names. Then % `|indexstyle=[1]\indexkeywords|' might meet your purpose. This becomes % easier if you want to create multiple indexes with the -% \href{http://www.ctan.org/tex-archive/macros/latex/contrib/camel} +% \href{http://mirror.ctan.org/macros/latex/contrib/camel} % {\packagename{index}} package. % If you have defined appropriate new indexes, it is possible to write % `|indexstyle=\index[keywords]|', for example. @@ -1864,7 +1890,8 @@ % \lstthanks{Kai~Below}{below@tu-harburg.de}, % \lstthanks{Matthias~Bethke}{-}, % \lstthanks{Javier~Bezos}{javier.bezos@bancoval.es}, -% \lstthanks{Olaf~Trygve~Berglihn}{olafb@pvv.org}, ^^A {1999/11/29}{3-char comment delimiter don't work (Python)} +% \lstthanks{Olaf~Trygve~Berglihn}{olafb@pvv.org}, +% ^^A {1999/11/29}{3-char comment delimiter don't work (Python)} % \lstthanks{Geraint~Paul~Bevan}{geraint@users.sf.net}, % \lstthanks{Peter~Biechele}{peter.biechele@physik.uni-freiburg.de}, % \lstthanks{Beat~Birkhofer}{beat@birkhofer.ch}, @@ -1946,7 +1973,8 @@ % \lstthanks{Olivier~Lecarme}{ol@i3s.unice.fr}, % \lstthanks{Thomas~Leduc}{Thomas.Leduc@lsv.ens-cachan.fr}, % \lstthanks{Dr.~Peter~Leibner}{Peter.Leibner@sta.siemens.de}, -% \lstthanks{Thomas~Leonhardt}{leonhardt@informatik.tu-darmstadt.de} (big thankyou), ^^A beta tester +% \lstthanks{Thomas~Leonhardt}{leonhardt@informatik.tu-darmstadt.de} +% (big thankyou), ^^A beta tester % \lstthanks{Magnus~Lewis-Smith}{Magnus.Lewis-Smith@pace.co.uk}, % \lstthanks{Knut~Lickert}{knut.lickert@gmx.de}, % \lstthanks{Benjamin~Lings}{-}, @@ -2108,143 +2136,180 @@ % \subsection{Typesetting listings}\label{rTypesettingListings} % % \begin{syntax} -% \item[0.19] \rcmdname\lstset\marg{key=value list} +% \item[0.19] \rcmdname\lstset\marg{key=value list} % -% sets the values of the specified keys, see also section -% \ref{uTheKey=ValueInterface}. -% The parameters keep their values up to the end of the current group. -% In contrast, all optional \meta{key=value list}s below modify the -% parameters for single listings only. +% sets the values of the specified keys, see also section +% \ref{uTheKey=ValueInterface}. The parameters keep their values up to +% the end of the current group. In contrast, all optional +% \meta{key=value list}s below modify the parameters for single +% listings only. % -% \item[0.18] \rcmdname\lstinline\oarg{key=value list}\meta{character}\meta{source code}\meta{same character} +% \item[0.18] +% \rcmdname\lstinline\oarg{key=value list}\meta{character}^^A +% \meta{source code}\meta{same character} % -% works like |\verb| but respects the active language and style. These -% listings use flexible columns unless requested differently in the -% optional argument, and do not support frames or background colors. -% You can write `|\lstinline!var i:integer;!|' and get -% `\lstinline!var i:integer;!'. +% works like |\verb| but respects the active language and style. +% These listings use flexible columns unless requested differently +% in the optional argument, and do not support frames or background +% colors. You can write `|\lstinline!var i:integer;!|' and get +% `\lstinline!var i:integer;!'. % -% Since the command first looks ahead for an optional argument, you must -% provide at least an empty one if you want to use |[| as -% \meta{character}. +% Since the command first looks ahead for an optional argument, you +% must provide at least an empty one if you want to use |[| as +% \meta{character}. % -% \dag\ An experimental implementation has been done to support the -% syntax |\lstinline|\oarg{key=value list}\marg{source code}. Try it if -% you want and report success and failure. A known limitation is that -% inside another argument the last source code token must not be an -% explicit space token---and, of course, using a listing inside another -% argument is itself experimental, see section -% \ref{rListingsInsideArguments}. +% \dag\ An experimental implementation has been done to support the +% syntax |\lstinline|\oarg{key=value list}\marg{source code}. Try it +% if you want and report success and failure. A known limitation is +% that inside another argument the last source code token must not +% be an explicit space token---and, of course, using a listing inside +% another argument is itself experimental, see section +% \ref{rListingsInsideArguments}. % -% Another limitation is that this feature can't be used in cells of a -% |tabular|-environment. See section \ref{uListingsArguments} for a -% workaround. +% Another limitation is that this feature can't be used in cells of a +% |tabular|-environment. See section \ref{uListingsArguments} for a +% workaround. % -% See also section \ref{rShortInline} for commands to create short analogs -% for the |\lstinline| command. +% See also section \ref{rShortInline} for commands to create short +% analogs for the |\lstinline| command. % -% \item[0.15] |\begin{|\texttt{\rstyle lstlisting}|}|\oarg{key=value list} +% \item[0.15] |\begin{|\texttt{\rstyle lstlisting}|}|\oarg{key=value +% list} % -% \leavevmode\hspace*{-\leftmargini}|\end{|\texttt{\rstyle lstlisting}|}| +% \leavevmode\hspace*{-\leftmargini}|\end{|\texttt{\rstyle +% lstlisting}|}| % % typesets the code in between as a displayed listing. % -% In contrast to the environment of the \packagename{verbatim} package, -% \LaTeX\ code on the same line and after the end of environment is -% typeset respectively executed. +% In contrast to the environment of the \packagename{verbatim} +% package, \LaTeX\ code on the same line and after the end of +% environment is typeset respectively executed. % -% \item[0.1] \rcmdname\lstinputlisting\oarg{key=value list}\marg{file name} +% \item[0.1] \rcmdname\lstinputlisting\oarg{key=value list}\marg{file +% name} % % typesets the stand alone source code file as a displayed listing. +% \end{syntax} +% +% +% \subsection{Options} +% +% The following sections describe all the keys that can be used to +% influence the appearance of the listing. +% +% +% \subsubsection{Searching for files} +% +% \begin{syntax} +% \item[1.8, {}] \rkeyname{inputpath}|=|\meta{path} +% +% defines the path, where the file given by \meta{file name} resides. +% +% \rkeyname{inputpath} overrules the |TEXINPUTS| environment variable, +% which means that a file residing on one of the paths given by +% |TEXINPUTS| isn't found anymore, if \meta{path} isn't part of +% |TEXINPUTS|. +% +% \rkeyname{inputpath} set as option of \rcmdname\lstinputlisting{} +% overrules the value set by \rcmdname\lstset. % \end{syntax} % % -% \subsection{Space and placement} +% \subsubsection{Space and placement} % % \begin{syntax} -% \item[0.20,floatplacement] \rkeyname{float}|=|[|*|]\meta{subset of \textup{\texttt{tbph}}}\syntaxor\rkeyname{float} +% \item[0.20,floatplacement] \rkeyname{float}|=|[|*|]\meta{subset of +% \textup{\texttt{tbph}}}\syntaxor\rkeyname{float} % -% makes sense on individual displayed listings only and lets them float. -% The argument controls where \LaTeX\ is \emph{allowed} to put the float: -% at the top or bottom of the current/next page, on a separate page, or -% here where the listing is. +% makes sense on individual displayed listings only and lets them +% float. The argument controls where \LaTeX\ is \emph{allowed} to put +% the float: at the top or bottom of the current/next page, on a +% separate page, or here where the listing is. % -% The optional star can be used to get a double-column float in a -% two-column document. +% The optional star can be used to get a double-column float in a +% two-column document. % -% \item[0.21,tbp] \rkeyname{floatplacement}|=|\meta{place specifiers} +% \item[0.21,tbp] \rkeyname{floatplacement}|=|\meta{place specifiers} % -% is used as place specifier if \keyname{float} is used without value. +% is used as place specifier if \keyname{float} is used without value. % -% \item[0.21,\medskipamount] \rkeyname{aboveskip}|=|\meta{dimension} -% \item[0.21,\medskipamount] \rkeyname{belowskip}|=|\meta{dimension} +% \item[0.21,\medskipamount] \rkeyname{aboveskip}|=|\meta{dimension} +% \item[0.21,\medskipamount] \rkeyname{belowskip}|=|\meta{dimension} % -% define the space above and below displayed listings. +% define the space above and below displayed listings. % -% \item[0.17,0pt,\dag] \rkeyname{lineskip}|=|\meta{dimension} +% \item[0.17,0pt,\dag] \rkeyname{lineskip}|=|\meta{dimension} % -% specifies additional space between lines in listings. +% specifies additional space between lines in listings. % -% \item[0.18,c,\dag] \rkeyname{boxpos}|=|\meta{\alternative{b,c,t}} +% \item[0.18,c,\dag] \rkeyname{boxpos}|=|\meta{\alternative{b,c,t}} % -% Sometimes the \packagename{listings} package puts a |\hbox| around a -% listing---or it couldn't be printed or even processed correctly. -% The key determines the vertical alignment to the surrounding material: -% bottom baseline, centered or top baseline. +% Sometimes the \packagename{listings} package puts a |\hbox| around a +% listing---or it couldn't be printed or even processed correctly. The +% key determines the vertical alignment to the surrounding material: +% bottom baseline, centered or top baseline. % \end{syntax} % % -% \subsection{The printed range} +% \subsubsection{The printed range} % % \begin{syntax} -% \item[0.12,true] \rkeyname{print}|=|\meta{\alternative{true,false}}\syntaxor\rkeyname{print} +% \item[0.12,true] +% \rkeyname{print}|=|\meta{\alternative{true,false}}\syntaxor\rkeyname{print} % -% controls whether an individual displayed listing is typeset. Even if -% set false, the respective caption is printed and the label is defined. +% controls whether an individual displayed listing is typeset. Even if +% set false, the respective caption is printed and the label is +% defined. % -% Note: If the package is loaded without the \texttt{draft} option, you -% can use this key together with |\lstset|. In the other case the key -% can be used to typeset particular listings despite using the -% \texttt{draft} option. +% Note: If the package is loaded without the \texttt{draft} option, you +% can use this key together with |\lstset|. In the other case the key +% can be used to typeset particular listings despite using the +% \texttt{draft} option. % -% \item[0.1,1] \rkeyname{firstline}|=|\meta{number} -% \item[0.1,9999999] \rkeyname{lastline}|=|\meta{number} +% \item[0.1,1] \rkeyname{firstline}|=|\meta{number} +% \item[0.1,9999999] \rkeyname{lastline}|=|\meta{number} % -% can be used on individual listings only. They determine the physical -% input lines used to print displayed listings. +% can be used on individual listings only. They determine the physical +% input lines used to print displayed listings. % -% \item[1.2] \rkeyname{linerange}|={|\meta{first1}\texttt-\meta{last1}\texttt,\meta{first2}\texttt-\meta{last2}\texttt, and so on|}|\label{uoption:linerange} +% \item[1.2] +% \rkeyname{linerange}|={|\meta{first1}\texttt-\meta{last1}\texttt,^^A +% \meta{first2}\texttt-\meta{last2}\texttt, and so +% on|}|\label{uoption:linerange} % -% can be used on individual listings only. The given line ranges -% of the listing are displayed. The intervals must be sorted and must -% not intersect. +% can be used on individual listings only. The given line ranges of the +% listing are displayed. The intervals must be sorted and must not +% intersect. % -% \item[0.20,false] \rkeyname{showlines}|=|\meta{\alternative{true,false}}\syntaxor\rkeyname{showlines} +% \item[0.20,false] +% \rkeyname{showlines}|=|\meta{\alternative{true,false}}\syntaxor\rkeyname{showlines} % -% If true, the package prints empty lines at the end of listings. -% Otherwise these lines are dropped (but they count for line numbering). +% If true, the package prints empty lines at the end of listings. +% Otherwise these lines are dropped (but they count for line +% numbering). % -% \item[1.0] \rkeyname{emptylines}|=|[|*|]\meta{number} +% \item[1.0] \rkeyname{emptylines}|=|[|*|]\meta{number} % -% sets the maximum of empty lines allowed. If there is a block of more -% than \meta{number} empty lines, only \meta{number} ones are printed. -% Without the optional star, line numbers can be disturbed when blank -% lines are omitted; with the star, the lines keep their original -% numbers. +% sets the maximum of empty lines allowed. If there is a block of more +% than \meta{number} empty lines, only \meta{number} ones are printed. +% Without the optional star, line numbers can be disturbed when blank +% lines are omitted; with the star, the lines keep their original +% numbers. % -% \item[0.19,0] \rkeyname{gobble}|=|\meta{number} +% \item[0.19,0] \rkeyname{gobble}|=|\meta{number} % -% gobbles \meta{number} characters at the beginning of each -% \emph{environment} code line. This key has no effect on \cs{lstinline} -% or \cs{lstinputlisting}. +% gobbles \meta{number} characters at the beginning of each +% \emph{environment} code line. This key has no effect on +% \cs{lstinline} or \cs{lstinputlisting}. % -% Tabulators expand to \ikeyname{tabsize} spaces before they are gobbled. -% Code lines with fewer than \ikeyname{gobble} characters are considered -% empty. Never indent the end of environment by more characters. +% Tabulators expand to \ikeyname{tabsize} spaces before they are +% gobbled. Code lines with fewer than \ikeyname{gobble} characters are +% considered empty. Never indent the end of environment by more +% characters. % \end{syntax} % % -% \subsection{Languages and styles}\label{rLanguagesAndStyles} +% \subsubsection{Languages and styles}\label{rLanguagesAndStyles} % % Please note that the arguments \meta{language}, \meta{dialect}, and % \meta{style name} are case insensitive and that spaces have no effect. @@ -2290,71 +2355,80 @@ % % Finally, here's a small list of language-specific keys. % \begin{syntax} -% \item[0.19,false,optional] \rkeyname{printpod}|=|\meta{\alternative{true,false}} +% \item[0.19,false,optional] +% \rkeyname{printpod}|=|\meta{\alternative{true,false}} % -% prints or drops PODs in Perl. +% prints or drops PODs in Perl. % -% \item[0.20,true,{renamed,optional}] \rkeyname{usekeywordsintag}|=|\meta{\alternative{true,false}}\label{uoption:usekeywordsintag} +% \item[0.20,true,{renamed,optional}] +% \rkeyname{usekeywordsintag}|=|\meta{\alternative{true,false}}^^A +% \label{uoption:usekeywordsintag} % -% The package either use the first order keywords in tags or prints all -% identifiers inside |<>| in keyword style. +% The package either use the first order keywords in tags or prints all +% identifiers inside |<>| in keyword style. % -% \item[1.1,{{}},optional] \rkeyname{tagstyle}|=|\meta{style}\label{uoption:tagstyle} +% \item[1.1,{{}},optional] +% \rkeyname{tagstyle}|=|\meta{style}\label{uoption:tagstyle} % -% determines the style in which tags and their content is printed. +% determines the style in which tags and their content is printed. % -% \item[1.1,false,optional] \rkeyname{markfirstintag}|=|\meta{style}\label{uoption:markfirstintag} +% \item[1.1,false,optional] +% \rkeyname{markfirstintag}|=|\meta{style}\label{uoption:markfirstintag} % -% prints the first name in tags with keyword style. +% prints the first name in tags with keyword style. % -% \item[0.20,true,optional] \rkeyname{makemacrouse}|=|\meta{\alternative{true,false}} +% \item[0.20,true,optional] +% \rkeyname{makemacrouse}|=|\meta{\alternative{true,false}} % -% Make specific: Macro use of identifiers, which are defined as first -% order keywords, also prints the surrounding |$(| and |)| in keyword -% style. e.g.~you could get -% \textbf{\textdollar(}\textbf{strip} \textdollar(BIBS)\textbf{)}. -% If deactivated you get -% \textdollar(\textbf{strip} \textdollar(BIBS)). +% Make specific: Macro use of identifiers, which are defined as first +% order keywords, also prints the surrounding +% |$(| and |)| in keyword style. e.g.~you could get +% \textbf{\textdollar(}\textbf{strip} \textdollar(BIBS)\textbf{)}. If +% deactivated you get \textdollar(\textbf{strip} \textdollar(BIBS)). % \end{syntax} % % -% \subsection{Figure out the appearance}\label{rFigureOutTheAppearance} +% \subsubsection{Figure out the appearance}\label{rFigureOutTheAppearance} % % \begin{syntax} -% \item[0.18,{{}}] \rkeyname{basicstyle}|=|\meta{basic style} +% \item[0.18,{{}}] \rkeyname{basicstyle}|=|\meta{basic style} % -% is selected at the beginning of each listing. You could use -% |\footnotesize|, |\small|, |\itshape|, |\ttfamily|, or something like -% that. The last token of \meta{basic style} must not read any following -% characters. +% is selected at the beginning of each listing. You could use +% |\footnotesize|, |\small|, |\itshape|, |\ttfamily|, or something like +% that. The last token of \meta{basic style} must not read any +% following characters. % -% \item[0.18,{{}}] \rkeyname{identifierstyle}|=|\meta{style} -% \item[0.11,\itshape] \rkeyname{commentstyle}|=|\meta{style} -% \item[0.12,{{}}] \rkeyname{stringstyle}|=|\meta{style} +% \item[0.18,{{}}] \rkeyname{identifierstyle}|=|\meta{style} +% \item[0.11,\itshape] \rkeyname{commentstyle}|=|\meta{style} +% \item[0.12,{{}}] \rkeyname{stringstyle}|=|\meta{style} % -% determines the style for non-keywords, comments, and strings. The -% \emph{last} token can be an one-parameter command like |\textbf| or -% |\underbar|. +% determines the style for non-keywords, comments, and strings. The +% \emph{last} token can be an one-parameter command like |\textbf| or +% |\underbar|. % -% \item[0.11,\bfseries,addon] \rkeyname{keywordstyle}|=|\oarg{number}[\textasteriskcentered]\meta{style}\label{roption:keywordstyle} +% \item[0.11,\bfseries,addon] +% \rkeyname{keywordstyle}|=|\oarg{number}[\textasteriskcentered]^^A +% \meta{style}\label{roption:keywordstyle} % -% is used to print keywords. The optional \meta{number} argument is the -% class number to which the style should be applied. +% is used to print keywords. The optional \meta{number} argument is +% the class number to which the style should be applied. % -% Add-on: If you use the optional star after the (optional) class number, the -% keywords are printed uppercase\,---\,even if a language is case -% sensitive and defines lowercase keywords only. Maybe there should also be an -% option for lowercase keywords \ldots +% Add-on: If you use the optional star after the (optional) class +% number, the keywords are printed uppercase\,---\,even if a language +% is case sensitive and defines lowercase keywords only. Maybe there +% should also be an option for lowercase keywords \ldots % -% \item[0.19,keywordstyle,deprecated] \rkeyname{ndkeywordstyle}|=|\meta{style} +% \item[0.19,keywordstyle,deprecated] +% \rkeyname{ndkeywordstyle}|=|\meta{style} % -% is equivalent to |keywordstyle=2|\meta{style}. +% is equivalent to |keywordstyle=2|\meta{style}. % -% \item[1.0,0] \rkeyname{classoffset}|=|\meta{number} +% \item[1.0,0] \rkeyname{classoffset}|=|\meta{number} % -% is added to all class numbers before the styles, keywords, identifiers, -% etc.~are assigned. The example below defines the keywords directly; -% you could do it indirectly by selecting two different languages. +% is added to all class numbers before the styles, keywords, +% identifiers, etc.~are assigned. The example below defines the +% keywords directly; you could do it indirectly by selecting two +% different languages. % \end{syntax} %\ifcolor % \begin{lstxsample} @@ -2381,164 +2455,188 @@ % \end{lstsample} % % \begin{syntax} -% \item[0.20,keywordstyle,{addon,bug,optional}] \rkeyname{texcsstyle}|=|[|*|]\oarg{class number}\meta{style}\label{roption:texcsstyle} -% \item[0.20,keywordstyle,optional] \rkeyname{directivestyle}|=|\meta{style} -% -% determine the style of \TeX\ control sequences and directives. -% Note that these keys are present only if you've chosen an appropriate -% language. -% -% The optional star of |texcsstyle| also highlights the backslash in -% front of the control sequence name. Note that this option is set for -% all |texcs| lists. -% -% Bug: \texttt{texcs\ldots} interferes with other keyword lists. If, for -% example, \texttt{emph} contains the word \texttt{foo}, then the control -% sequence |\foo| will show up in \texttt{emphstyle}. -% -% \item[0.21] \rkeyname{emph}|=|\oarg{number}\marg{identifier list} -% \item[0.21] \rkeyname{moreemph}|=|\oarg{number}\marg{identifier list} -% \item[0.21] \rkeyname{deleteemph}|=|\oarg{number}\marg{identifier list} -% \item[0.21] \rkeyname{emphstyle}|=|\oarg{number}\marg{style} -% -% respectively define, add or remove the \meta{identifier list} from -% `emphasize class \meta{number}', or define the style for that class. -% If you don't give an optional argument, the package assumes -% \meta{number}$\,=1$. -% -% These keys are described more detailed in section -% \ref{uEmphasizeIdentifiers}. -% -% \item[1.0] \rkeyname{delim}|=|[\texttt*[\texttt*]]\texttt[\meta{type}\texttt][\texttt[\meta{style}\texttt]]\meta{delimiter\textup(s\textup)} -% \item[1.0] \rkeyname{moredelim}|=|[\texttt*[\texttt*]]\texttt[\meta{type}\texttt][\texttt[\meta{style}\texttt]]\meta{delimiter\textup(s\textup)} -% \item[1.0] \rkeyname{deletedelim}|=|[\texttt*[\texttt*]]\texttt[\meta{type}\texttt]\meta{delimiter\textup(s\textup)} -% -% define, add, or remove user supplied delimiters. (Note that this does -% not affect strings or comments.) -% -% In the first two cases \meta{style} is used to print the delimited -% code (and the delimiters). Here, \meta{style} could be something like -% |\bfseries| or |\itshape|, or it could refer to other styles via -% \texttt{keywordstyle}, \texttt{keywordstyle2}, \texttt{emphstyle}, -% etc. -% -% Supported types are \texttt{l} and \texttt{s}, see the comment keys in -% section \ref{uLanguageDefinitions} for an explanation. If you use the -% prefix \texttt i, i.e.~\texttt{il} or \texttt{is}, the delimiters are -% not printed, which is some kind of invisibility. -% -% If you use one optional star, the package will detect keywords, -% comments, and strings inside the delimited code. With both optional -% stars, aditionally the style is applied cumulatively; see section -% \ref{uDelimiters}. +% \item[0.20,keywordstyle,{addon,bug,optional}] +% \rkeyname{texcsstyle}|=|[|*|]\oarg{class +% number}\meta{style}\label{roption:texcsstyle} +% \item[0.20,keywordstyle,optional] +% \rkeyname{directivestyle}|=|\meta{style} +% +% determine the style of \TeX\ control sequences and directives. Note +% that these keys are present only if you've chosen an appropriate +% language. +% +% The optional star of |texcsstyle| also highlights the backslash in +% front of the control sequence name. Note that this option is set for +% all |texcs| lists. +% +% Bug: \texttt{texcs\ldots} interferes with other keyword lists. If, +% for example, \texttt{emph} contains the word \texttt{foo}, then the +% control sequence |\foo| will show up in \texttt{emphstyle}. +% +% \item[0.21] \rkeyname{emph}|=|\oarg{number}\marg{identifier list} +% \item[0.21] \rkeyname{moreemph}|=|\oarg{number}\marg{identifier list} +% \item[0.21] \rkeyname{deleteemph}|=|\oarg{number}\marg{identifier list} +% \item[0.21] \rkeyname{emphstyle}|=|\oarg{number}\marg{style} +% +% respectively define, add or remove the \meta{identifier list} from +% `emphasize class \meta{number}', or define the style for that class. +% If you don't give an optional argument, the package assumes +% \meta{number}$\,=1$. +% +% These keys are described more detailed in section +% \ref{uEmphasizeIdentifiers}. +% +% \item[1.0] +% \rkeyname{delim}|=|[\texttt*[\texttt*]]\texttt[\meta{type}\texttt]^^A +% [\texttt[\meta{style}\texttt]]\meta{delimiter\textup(s\textup)} +% \item[1.0] +% \rkeyname{moredelim}|=|[\texttt*[\texttt*]]\texttt[\meta{type}\texttt]^^A +% [\texttt[\meta{style}\texttt]]\meta{delimiter\textup(s\textup)} +% \item[1.0] +% \rkeyname{deletedelim}|=|[\texttt*[\texttt*]]\texttt[\meta{type}\texttt]^^A +% \meta{delimiter\textup(s\textup)} +% +% define, add, or remove user supplied delimiters. (Note that this +% does not affect strings or comments.) +% +% In the first two cases \meta{style} is used to print the delimited +% code (and the delimiters). Here, \meta{style} could be something like +% |\bfseries| or |\itshape|, or it could refer to other styles via +% \texttt{keywordstyle}, \texttt{keywordstyle2}, \texttt{emphstyle}, +% etc. +% +% Supported types are \texttt{l} and \texttt{s}, see the comment keys +% in section \ref{uLanguageDefinitions} for an explanation. If you use +% the prefix \texttt i, i.e.~\texttt{il} or \texttt{is}, the delimiters +% are not printed, which is some kind of invisibility. +% +% If you use one optional star, the package will detect keywords, +% comments, and strings inside the delimited code. With both optional +% stars, aditionally the style is applied cumulatively; see section +% \ref{uDelimiters}. % \end{syntax} % % -% \subsection{Getting all characters right} +% \subsubsection{Getting all characters right} % % \begin{syntax} -% \item[0.18,true] \rkeyname{extendedchars}|=|\meta{\alternative{true,false}}\syntaxor\rkeyname{extendedchars} +% \item[0.18,true] +% \rkeyname{extendedchars}|=|\meta{\alternative{true,false}}^^A +% \syntaxor\rkeyname{extendedchars} % -% allows or prohibits extended characters in listings, that means -% (national) characters of codes 128--255. If you use extended -% characters, you should load \packagename{fontenc} and/or -% \packagename{inputenc}, for example. +% allows or prohibits extended characters in listings, that means +% (national) characters of codes 128--255. If you use extended +% characters, you should load \packagename{fontenc} and/or +% \packagename{inputenc}, for example. % -% \item[1.0,{{}}] \rkeyname{inputencoding}|=|\meta{encoding} +% \item[1.0,{{}}] \rkeyname{inputencoding}|=|\meta{encoding} % -% determines the input encoding. The usage of this key requires the -% \packagename{inputenc} package; nothing happens if it's not loaded. +% determines the input encoding. The usage of this key requires the +% \packagename{inputenc} package; nothing happens if it's not loaded. % -% \item[1.1,false] \rkeyname{upquote}|=|\meta{\alternative{true,false}}\label{uoption:upquote} +% \item[1.1,false] +% \rkeyname{upquote}|=|\meta{\alternative{true,false}}\label{uoption:upquote} % -% determines whether the left and right quote are printed |`'| or -% \texttt{\textasciigrave\textquotesingle}. -% This key requires the \packagename{textcomp} package if true. +% determines whether the left and right quote are printed |`'| or +% \texttt{\textasciigrave\textquotesingle}. This key requires the +% \packagename{textcomp} package if true. % -% \item[0.12,8] \rkeyname{tabsize}|=|\meta{number} +% \item[0.12,8] \rkeyname{tabsize}|=|\meta{number} % -% sets tabulator stops at columns $\meta{number}+1$, $2\cdot\meta{number}+1$, $3\cdot\meta{number}+1$, and so on. -% Each tabulator in a listing moves the current column to the next -% tabulator stop. +% sets tabulator stops at columns +% $\meta{number}+1$, $2\cdot\meta{number}+1$, +% $3\cdot\meta{number}+1$, and so on. Each tabulator in a listing +% moves the current column to the next tabulator stop. % -% \item[0.20,false] \rkeyname{showtabs}|=|\meta{\alternative{true,false}} +% \item[0.20,false] \rkeyname{showtabs}|=|\meta{\alternative{true,false}} % -% make tabulators visible or invisible. A visible tabulator looks like -% \lstinline[showtabs]! !, but that can be changed. If you choose -% invisible tabulators but visible spaces, tabulators are converted to -% an appropriate number of spaces. +% make tabulators visible or invisible. A visible tabulator looks like +% \lstinline[showtabs]! !, but that can be changed. If you choose +% invisible tabulators but visible spaces, tabulators are converted to +% an appropriate number of spaces. % -% \item[0.20] \rkeyname{tab}|=|\meta{tokens} +% \item[0.20] \rkeyname{tab}|=|\meta{tokens} % -% \meta{tokens} is used to print a visible tabulator. You might want to use |$\to$|, |$\mapsto$|, |$\dashv$| or something like that instead of the strange default definition. +% \meta{tokens} is used to print a visible tabulator. You might want to +% use |$\to$|, |$\mapsto$|, +% |$\dashv$| or something like that instead of the strange default +% definition. % -% \item[0.20,false] \rkeyname{showspaces}|=|\meta{\alternative{true,false}} +% \item[0.20,false] +% \rkeyname{showspaces}|=|\meta{\alternative{true,false}} % -% lets all blank spaces appear {\textvisiblespace} or as blank spaces. +% lets all blank spaces appear {\textvisiblespace} or as blank spaces. % -% \item[0.12,true] \rkeyname{showstringspaces}|=|\meta{\alternative{true,false}} +% \item[0.12,true] +% \rkeyname{showstringspaces}|=|\meta{\alternative{true,false}} % -% lets blank spaces in strings appear {\textvisiblespace} or as blank -% spaces. +% lets blank spaces in strings appear {\textvisiblespace} or as blank +% spaces. % -% \item[0.19,\bigbreak] \rkeyname{formfeed}|=|\meta{tokens} +% \item[0.19,\bigbreak] \rkeyname{formfeed}|=|\meta{tokens} % -% Whenever a listing contains a form feed, \meta{tokens} is executed. +% Whenever a listing contains a form feed, \meta{tokens} is executed. % \end{syntax} % % -% \subsection{Line numbers}\label{rLineNumbers} +% \subsubsection{Line numbers}\label{rLineNumbers} % % \begin{syntax} -% \item[1.0,none] \rkeyname{numbers}|=|\meta{\alternative{none,left,right}} +% \item[1.0,none] +% \rkeyname{numbers}|=|\meta{\alternative{none,left,right}} % -% makes the package either print no line numbers, or put them on the -% left or the right side of a listing. +% makes the package either print no line numbers, or put them on the +% left or the right side of a listing. % -% \item[0.16,1] \rkeyname{stepnumber}|=|\meta{number} +% \item[0.16,1] \rkeyname{stepnumber}|=|\meta{number} % -% All lines with ``line number $\equiv 0$ modulo \meta{number}'' get a -% line number. -% If you turn line numbers on and off with \keyname{numbers}, the -% parameter \keyname{stepnumber} will keep its value. Alternatively you -% can turn them off via |stepnumber=0| and on with a nonzero number, and -% keep the value of \keyname{numbers}. +% All lines with ``line number $\equiv +% 0$ modulo \meta{number}'' get a line number. If you turn line +% numbers on and off with \keyname{numbers}, the parameter +% \keyname{stepnumber} will keep its value. Alternatively you can turn +% them off via |stepnumber=0| and on with a nonzero number, and keep +% the value of \keyname{numbers}. % -% \item[1.1,false] \rkeyname{numberfirstline}|=|\meta{\alternative{true,false}}\label{uoption:numberfirstline} +% \item[1.1,false] +% \rkeyname{numberfirstline}|=|\meta{\alternative{true,false}}^^A +% \label{uoption:numberfirstline} % -% The first line of each listing gets numbered (if numbers are on at all) -% even if the line number is not divisible by \keyname{stepnumber}. +% The first line of each listing gets numbered (if numbers are on at +% all) even if the line number is not divisible by +% \keyname{stepnumber}. % -% \item[0.16,{{}}] \rkeyname{numberstyle}|=|\meta{style} +% \item[0.16,{{}}] \rkeyname{numberstyle}|=|\meta{style} % -% determines the font and size of the numbers. +% determines the font and size of the numbers. % -% \item[0.19,10pt] \rkeyname{numbersep}|=|\meta{dimension} +% \item[0.19,10pt] \rkeyname{numbersep}|=|\meta{dimension} % -% is the distance between number and listing. +% is the distance between number and listing. % -% \item[1.0,true] \rkeyname{numberblanklines}|=|\meta{\alternative{true,false}} +% \item[1.0,true] +% \rkeyname{numberblanklines}|=|\meta{\alternative{true,false}} % -% If this is set to false, blank lines get no printed line number. +% If this is set to false, blank lines get no printed line number. % -% \item[0.20,auto] \rkeyname{firstnumber}|=|\meta{\alternative{auto,last,\normalfont\meta{number}}} +% \item[0.20,auto] +% \rkeyname{firstnumber}|=|\meta{\alternative{auto,last,\normalfont\meta{number}}} % -% \texttt{auto} lets the package choose the first number: a new listing -% starts with number one, a named listing continues the most recent -% same-named listing (see below), and a stand alone file begins with -% the number corresponding to the first input line. +% \texttt{auto} lets the package choose the first number: a new listing +% starts with number one, a named listing continues the most recent +% same-named listing (see below), and a stand alone file begins with +% the number corresponding to the first input line. % -% \texttt{last} continues the numbering of the most recent listing and -% \meta{number} sets it to the number. +% \texttt{last} continues the numbering of the most recent listing and +% \meta{number} sets it to the number. % -% \item[1.0] \rkeyname{name}|=|\meta{name} +% \item[1.0] \rkeyname{name}|=|\meta{name} % -% names a listing. Displayed environment-listings with the same name -% share a line counter if |firstnumber=auto| is in effect. +% names a listing. Displayed environment-listings with the same name +% share a line counter if |firstnumber=auto| is in effect. % -% \item[0.20,\arabic{lstnumber},data] \rcmdname\thelstnumber +% \item[0.20,\arabic{lstnumber},data] \rcmdname\thelstnumber % -% prints the lines' numbers. +% prints the lines' numbers. % \end{syntax} % We show an example on how to redefine |\thelstnumber|. But if you test it, % you won't get the result shown on the left. @@ -2560,23 +2658,26 @@ % \end{lstsample} % % \begin{advise} -% \item -% The example shows a sequence $n,n+1,\ldots,n+7$ of 8 three-digit figures such that the sequence contains each digit $0,1,\ldots,9$. -% But 8 is not minimal with that property. -% Find the minimal number and prove that it is minimal. -% How many minimal sequences do exist? -% -% Now look at the generalized problem: -% Let $k\in\{1,\ldots,10\}$ be given. -% Find the minimal number $m\in\{1,\ldots,10\}$ such that there is a sequence $n,{n+1},\ldots,\allowbreak{n+m-1}$ of $m$ $k$-digit figures which contains each digit $\{0,\ldots,9\}$. -% Prove that the number is minimal. -% How many minimal sequences do exist? -% -% If you solve this problem with a computer, write a \TeX\ program! +% \item The example shows a sequence +% $n,n+1,\ldots,n+7$ of 8 three-digit figures such that the sequence +% contains each digit +% $0,1,\ldots,9$. But 8 is not minimal with that property. Find the +% minimal number and prove that it is minimal. How many minimal +% sequences do exist? +% +% Now look at the generalized problem: Let +% $k\in\{1,\ldots,10\}$ be given. Find the minimal number +% $m\in\{1,\ldots,10\}$ such that there is a sequence +% $n,{n+1},\ldots,\allowbreak{n+m-1}$ of $m$ +% $k$-digit figures which contains each digit +% $\{0,\ldots,9\}$. Prove that the number is minimal. How many +% minimal sequences do exist? +% +% If you solve this problem with a computer, write a \TeX\ program! % \end{advise} % % -% \subsection{Captions} +% \subsubsection{Captions} % % In despite of \LaTeX\ standard behaviour, captions and floats are independent % from each other here; you can use captions with non-floating listings. @@ -2642,52 +2743,59 @@ % \end{syntax} % % -% \subsection{Margins and line shape}\label{rMarginsAndLineShape} +% \subsubsection{Margins and line shape}\label{rMarginsAndLineShape} % % \begin{syntax} -% \item[0.21,\linewidth] \rkeyname{linewidth}|=|\meta{dimension} +% \item[0.21,\linewidth] \rkeyname{linewidth}|=|\meta{dimension} % -% defines the base line width for listings. The following three keys are -% taken into account additionally. +% defines the base line width for listings. The following three keys +% are taken into account additionally. % -% \item[0.19,0pt] \rkeyname{xleftmargin}|=|\meta{dimension} -% \item[1.0,0pt] \rkeyname{xrightmargin}|=|\meta{dimension} +% \item[0.19,0pt] \rkeyname{xleftmargin}|=|\meta{dimension} +% \item[1.0,0pt] \rkeyname{xrightmargin}|=|\meta{dimension} % -% The dimensions are used as extra margins on the left and right. Line -% numbers and frames are both moved accordingly. +% The dimensions are used as extra margins on the left and right. Line +% numbers and frames are both moved accordingly. % -% \item[0.19,false] \rkeyname{resetmargins}|=|\meta{\alternative{true,false}} +% \item[0.19,false] +% \rkeyname{resetmargins}|=|\meta{\alternative{true,false}} % -% If true, indention from list environments like \texttt{enumerate} or -% \texttt{itemize} is reset, i.e.~not used. +% If true, indention from list environments like \texttt{enumerate} or +% \texttt{itemize} is reset, i.e.~not used. % -% \item[0.20,false] \rkeyname{breaklines}|=|\meta{\alternative{true,false}}\syntaxor\rkeyname{breaklines} +% \item[0.20,false] +% \rkeyname{breaklines}|=|\meta{\alternative{true,false}}\syntaxor\rkeyname{breaklines} % -% activates or deactivates automatic line breaking of long lines. +% activates or deactivates automatic line breaking of long lines. % -% \item[1.2,false] \rkeyname{breakatwhitespace}|=|\meta{\alternative{true,false}}\syntaxor\rkeyname{breakatwhitespace}\label{uoption:breakatwhitespace} +% \item[1.2,false] +% \rkeyname{breakatwhitespace}|=|\meta{\alternative{true,false}}^^A +% \syntaxor\rkeyname{breakatwhitespace}\label{uoption:breakatwhitespace} % -% If true, it allows line breaks only at white space. +% If true, it allows line breaks only at white space. % -% \item[0.20,{{}}] \rkeyname{prebreak}|=|\meta{tokens} -% \item[0.20,{{}}] \rkeyname{postbreak}|=|\meta{tokens} +% \item[0.20,{{}}] \rkeyname{prebreak}|=|\meta{tokens} +% \item[0.20,{{}}] \rkeyname{postbreak}|=|\meta{tokens} % -% \meta{tokens} appear at the end of the current line respectively at the beginning of the next (broken part of the) line. +% \meta{tokens} appear at the end of the current line respectively at +% the beginning of the next (broken part of the) line. % -% You must not use dynamic space (in particular spaces) since internally we use |\discretionary|. -% However |\space| is redefined to be used inside \meta{tokens}. +% You must not use dynamic space (in particular spaces) since +% internally we use |\discretionary|. However |\space| is redefined to +% be used inside \meta{tokens}. % -% \item[0.20,20pt] \rkeyname{breakindent}|=|\meta{dimension} +% \item[0.20,20pt] \rkeyname{breakindent}|=|\meta{dimension} % -% is the indention of the second, third, \ldots\ line of broken lines. +% is the indention of the second, third, \ldots\ line of broken lines. % -% \item[0.20,true] \rkeyname{breakautoindent}|=|\meta{\alternative{true,false}}\syntaxor\rkeyname{breakautoindent} +% \item[0.20,true] +% \rkeyname{breakautoindent}|=|\meta{\alternative{true,false}}^^A +% \syntaxor\rkeyname{breakautoindent} % -% activates or deactivates automatic indention of broken lines. This -% indention is used additionally to \ikeyname{breakindent}, see the -% example below. -% Visible spaces or visible tabulators might set this auto -% indention to zero. +% activates or deactivates automatic indention of broken lines. This +% indention is used additionally to \ikeyname{breakindent}, see the +% example below. Visible spaces or visible tabulators might set this +% auto indention to zero. % \end{syntax} % In the following example we use tabulators to create long lines, but the % verbatim part uses |tabsize=1|. @@ -2707,65 +2815,69 @@ % \end{lstsample} % % -% \subsection{Frames}\label{rFrames} +% \subsubsection{Frames}\label{rFrames} % % \begin{syntax} -% \item[1.0,none] \rkeyname{frame}|=|\meta{\alternative{none,leftline,topline,bottomline,lines,single,shadowbox}} +% \item[1.0,none] +% \rkeyname{frame}|=|\meta{\alternative{none,leftline,topline,bottomline,^^A +% lines,single,shadowbox}} % -% draws either no frame, a single line on the left, at the top, at the -% bottom, at the top and bottom, a whole single frame, or a shadowbox. +% draws either no frame, a single line on the left, at the top, at the +% bottom, at the top and bottom, a whole single frame, or a shadowbox. % -% Note that \packagename{fancyvrb} supports the same frame types except -% \texttt{shadowbox}. The shadow color is \keyname{rulesepcolor}, see -% below. +% Note that \packagename{fancyvrb} supports the same frame types except +% \texttt{shadowbox}. The shadow color is \keyname{rulesepcolor}, see +% below. % -% \item[0.19,{{}}] \rkeyname{frame}|=|\meta{subset of \textup{\texttt{trblTRBL}}} +% \item[0.19,{{}}] \rkeyname{frame}|=|\meta{subset of +% \textup{\texttt{trblTRBL}}} % -% The characters \texttt{trblTRBL} designate lines at the top and -% bottom of a listing and to lines on the right and left. Upper case -% characters are used to draw double rules. So |frame=tlrb| draws a -% single frame and |frame=TL| double lines at the top and on the left. +% The characters \texttt{trblTRBL} designate lines at the top and +% bottom of a listing and to lines on the right and left. Upper case +% characters are used to draw double rules. So |frame=tlrb| draws a +% single frame and |frame=TL| double lines at the top and on the left. % -% Note that frames usually reside outside the listing's space. +% Note that frames usually reside outside the listing's space. % -% \item[0.20,ffff] \rkeyname{frameround}|=|\meta{\alternative{t,f}}\meta{\alternative{t,f}}\meta{\alternative{t,f}}\meta{\alternative{t,f}} +% \item[0.20,ffff] +% \rkeyname{frameround}|=|\meta{\alternative{t,f}}\meta{\alternative{t,f}}^^A +% \meta{\alternative{t,f}}\meta{\alternative{t,f}} % -% The four letters designate the top right, bottom right, bottom -% left and top left corner. In this order. \texttt{t} makes the -% according corner round. If you use round corners, the rule width is -% controlled via |\thinlines| and |\thicklines|. +% The four letters designate the top right, bottom right, bottom left +% and top left corner. In this order. \texttt{t} makes the according +% corner round. If you use round corners, the rule width is controlled +% via |\thinlines| and |\thicklines|. % -% Note: The size of the quarter circles depends on \keyname{framesep} -% and is independent of the extra margins of a frame. The size is -% possibly adjusted to fit \LaTeX's circle sizes. +% Note: The size of the quarter circles depends on \keyname{framesep} +% and is independent of the extra margins of a frame. The size is +% possibly adjusted to fit \LaTeX's circle sizes. % -% \item[0.19,3pt] \rkeyname{framesep}|=|\meta{dimension} -% \item[0.19,2pt] \rkeyname{rulesep}|=|\meta{dimension} +% \item[0.19,3pt] \rkeyname{framesep}|=|\meta{dimension} +% \item[0.19,2pt] \rkeyname{rulesep}|=|\meta{dimension} % -% control the space between frame and listing and between double rules. +% control the space between frame and listing and between double rules. % -% \item[0.19,0.4pt] \rkeyname{framerule}|=|\meta{dimension} +% \item[0.19,0.4pt] \rkeyname{framerule}|=|\meta{dimension} % -% controls the width of the rules. +% controls the width of the rules. % -% \item[1.0,0pt] \rkeyname{framexleftmargin}|=|\meta{dimension} -% \item[1.0,0pt] \rkeyname{framexrightmargin}|=|\meta{dimension} -% \item[1.0,0pt] \rkeyname{framextopmargin}|=|\meta{dimension} -% \item[1.0,0pt] \rkeyname{framexbottommargin}|=|\meta{dimension} +% \item[1.0,0pt] \rkeyname{framexleftmargin}|=|\meta{dimension} +% \item[1.0,0pt] \rkeyname{framexrightmargin}|=|\meta{dimension} +% \item[1.0,0pt] \rkeyname{framextopmargin}|=|\meta{dimension} +% \item[1.0,0pt] \rkeyname{framexbottommargin}|=|\meta{dimension} % -% are the dimensions which are used additionally to \keyname{framesep} -% to make up the margin of a frame. +% are the dimensions which are used additionally to \keyname{framesep} +% to make up the margin of a frame. % -% \item[0.21] \rkeyname{backgroundcolor}|=|\meta{color command} -% \item[0.21] \rkeyname{rulecolor}|=|\meta{color command} -% \item[1.0] \rkeyname{fillcolor}|=|\meta{color command} -% \item[1.0] \rkeyname{rulesepcolor}|=|\meta{color command} +% \item[0.21] \rkeyname{backgroundcolor}|=|\meta{color command} +% \item[0.21] \rkeyname{rulecolor}|=|\meta{color command} +% \item[1.0] \rkeyname{fillcolor}|=|\meta{color command} +% \item[1.0] \rkeyname{rulesepcolor}|=|\meta{color command} % -% specify the colour of the background, the rules, the space between -% `text box' and first rule, and of the space between two rules, -% respectively. -% Note that the value requires a |\color| command, for example -% \keyname{rulecolor}|=\color{blue}|. +% specify the colour of the background, the rules, the space between +% `text box' and first rule, and of the space between two rules, +% respectively. Note that the value requires a |\color| command, for +% example \keyname{rulecolor}|=\color{blue}|. % \end{syntax} % \ikeyname{frame} does not work with |fancyvrb=true| or when the package % internally makes a |\hbox| around the listing! And there are certainly more @@ -2799,25 +2911,26 @@ % \end{lstlisting} % \end{lstsample} % \begin{syntax} -% \item[0.20,,\dag] \rkeyname{frameshape}|=|\marg{top shape}\marg{left shape}\marg{right shape}\marg{bottom shape} -% -% gives you full control over the drawn frame parts. -% The arguments are not case sensitive. -% -% Both \meta{left shape} and \meta{right shape} are `left-to-right' -% \alternative{y,n} character sequences (or empty). Each |y| lets the -% package draw a rule, otherwise the rule is blank. These vertical rules -% are drawn `left-to-right' according to the specified shapes. -% The example above uses |yny|. -% -% \meta{top shape} and \meta{bottom shape} are `left-rule-right' -% sequences (or empty). The first `left-rule-right' sequence is attached -% to the most inner rule, the second to the next, and so on. -% Each sequence has three characters: `rule' is either |y| or |n|; -% `left' and `right' are |y|, |n| or |r| (which makes a corner round). -% The example uses |RYRYNYYYY| for both shapes: -% |RYR| describes the most inner (top and bottom) frame shape, |YNY| -% the middle, and |YYY| the most outer. +% \item[0.20,,\dag] \rkeyname{frameshape}|=|\marg{top shape}\marg{left +% shape}\marg{right shape}\marg{bottom shape} +% +% gives you full control over the drawn frame parts. The arguments are +% not case sensitive. +% +% Both \meta{left shape} and \meta{right shape} are `left-to-right' +% \alternative{y,n} character sequences (or empty). Each |y| lets the +% package draw a rule, otherwise the rule is blank. These vertical +% rules are drawn `left-to-right' according to the specified shapes. +% The example above uses |yny|. +% +% \meta{top shape} and \meta{bottom shape} are `left-rule-right' +% sequences (or empty). The first `left-rule-right' sequence is +% attached to the most inner rule, the second to the next, and so on. +% Each sequence has three characters: `rule' is either |y| or |n|; +% `left' and `right' are |y|, |n| or |r| (which makes a corner round). +% The example uses |RYRYNYYYY| for both shapes: |RYR| describes the +% most inner (top and bottom) frame shape, |YNY| the middle, and |YYY| +% the most outer. % \end{syntax} % To summarize, the example above used % \begin{verbatim} @@ -2826,94 +2939,107 @@ % However you'll get in trouble if you use round corners when they are too big. % % -% \subsection{Indexing} +% \subsubsection{Indexing} % % \begin{syntax} -% \item[0.19] \rkeyname{index}|=|\oarg{number}\oarg{keyword classes}\marg{identifiers} -% \item[0.21] \rkeyname{moreindex}|=|\oarg{number}\oarg{keyword classes}\marg{identifiers} -% \item[0.21] \rkeyname{deleteindex}|=|\oarg{number}\oarg{keyword classes}\marg{identifiers} -% -% define, add and remove \meta{identifiers} and \meta{keyword classes} -% from the index class list \meta{number}. If you don't specify the -% optional number, the package assumes \meta{number} $=1$. -% -% Each appearance of the explicitly given identifiers and each appearance -% of the identifiers of the specified \meta{keyword classes} is indexed. -% For example, you could write |index=[1][keywords]| to index all -% keywords. Note that |[1]| is required here---otherwise we couldn't use -% the second optional argument. -% -% \item[0.19,\lstindexmacro] \rkeyname{indexstyle}|=|\oarg{number}\meta{tokens \textup(one-parameter command\textup)} -% -% \meta{tokens} actually indexes the identifiers for the list -% \meta{number}. In contrast to the style keys, \meta{tokens} -% \emph{must} read exactly one parameter, namely the identifier. -% Default definition is\icmdname{\lstindexmacro}\vspace*{-\itemsep} +% \item[0.19] \rkeyname{index}|=|\oarg{number}\oarg{keyword +% classes}\marg{identifiers} +% \item[0.21] \rkeyname{moreindex}|=|\oarg{number}\oarg{keyword +% classes}\marg{identifiers} +% \item[0.21] \rkeyname{deleteindex}|=|\oarg{number}\oarg{keyword +% classes}\marg{identifiers} +% +% define, add and remove \meta{identifiers} and \meta{keyword classes} +% from the index class list \meta{number}. If you don't specify the +% optional number, the package assumes \meta{number} $=1$. +% +% Each appearance of the explicitly given identifiers and each +% appearance of the identifiers of the specified \meta{keyword classes} +% is indexed. For example, you could write |index=[1][keywords]| to +% index all keywords. Note that |[1]| is required here---otherwise we +% couldn't use the second optional argument. +% +% \item[0.19,\lstindexmacro] +% \rkeyname{indexstyle}|=|\oarg{number}\meta{tokens +% \textup(one-parameter command\textup)} +% +% \meta{tokens} actually indexes the identifiers for the list +% \meta{number}. In contrast to the style keys, \meta{tokens} +% \emph{must} read exactly one parameter, namely the identifier. +% Default definition is\icmdname{\lstindexmacro}\vspace*{-\itemsep} % \begin{verbatim} % \newcommand\lstindexmacro[1]{\index{{\ttfamily#1}}}\end{verbatim} % \vspace*{-\itemsep}which you shouldn't modify. % Define your own indexing commands and use them as argument to this key. -% \end{syntax} +% \end{syntax} % Section \ref{uIndexing} describes this feature in detail. % % -% \subsection{Column alignment}\label{rColumnAlignment} +% \subsubsection{Column alignment}\label{rColumnAlignment} % % \begin{syntax} -% \item[1.0,{[c]fixed}] \rkeyname{columns}|=|\oarg{\alternative{c,l,r}}\meta{alignment} -% -% selects the column alignment. The \meta{alignment} can be |fixed|, -% |flexible|, |spaceflexible|, or |fullflexible|; see section -% \ref{uFixedAndFlexibleColumns} for details. -% -% The optional |c|, |l|, or |r| controls the horizontal orientation of -% smallest output units (keywords, identifiers, etc.). The arguments work -% as follows, where vertical bars visualize the effect: -% $\vert$\lstinline[columns={[c]fixed}]!listing!$\vert$, -% $\vert$\lstinline[columns={[l]fixed}]!listing!$\vert$, and -% $\vert$\lstinline[columns={[r]fixed}]!listing!$\vert$ -% in fixed column mode, -% $\vert$\lstinline[columns={[c]flexible}]!listing!$\vert$, -% $\vert$\lstinline[columns={[l]flexible}]!listing!$\vert$, and -% $\vert$\lstinline[columns={[r]flexible}]!listing!$\vert$ -% with flexible columns, and -% $\vert$\lstinline[columns={[c]fullflexible}]!listing!$\vert$, -% $\vert$\lstinline[columns={[l]fullflexible}]!listing!$\vert$, and -% $\vert$\lstinline[columns={[r]fullflexible}]!listing!$\vert$ -% with space-flexible or full flexible columns (which ignore the -% optional argument, since they do not add extra space around -% printable characters). -% -% \item[0.18,false] \rkeyname{flexiblecolumns}|=|\meta{\alternative{true,false}}\syntaxor\rkeyname{flexiblecolumns} -% -% selects the most recently selected flexible or fixed column format, -% refer to section \ref{uFixedAndFlexibleColumns}. -% -% \item[0.21,false,\dag] \rkeyname{keepspaces}|=|\meta{\alternative{true,false}} -% -% |keepspaces=true| tells the package not to drop spaces to fix column -% alignment and always converts tabulators to spaces. -% -% \item[0.16] \rkeyname{basewidth}|=|\meta{dimension}\syntaxor -% \item[0.18,{{0.6em,0.45em}}] \rkeyname{basewidth}|={|\meta{fixed}|,|\meta{flexible mode}|}| -% -% sets the width of a single character box for fixed and flexible column -% mode (both to the same value or individually). -% -% \item[0.20,false] \rkeyname{fontadjust}|=|\meta{\alternative{true,false}}\syntaxor\rkeyname{fontadjust} -% -% If true the package adjusts the base width every font selection. -% This makes sense only if \ikeyname{basewidth} is given in font specific -% units like `em' or `ex'---otherwise this boolean has no effect. -% -% After loading the package, it doesn't adjust the width every font -% selection: it looks at \ikeyname{basewidth} each listing and uses the -% value for the whole listing. This is possibly inadequate if the style -% keys in section \ref{rFigureOutTheAppearance} make heavy font size -% changes, see the example below. -% -% Note that this key might disturb the column alignment and might have an -% effect on the keywords' appearance! +% \item[1.0,{[c]fixed}] +% \rkeyname{columns}|=|\oarg{\alternative{c,l,r}}\meta{alignment} +% +% selects the column alignment. The \meta{alignment} can be |fixed|, +% |flexible|, |spaceflexible|, or |fullflexible|; see section +% \ref{uFixedAndFlexibleColumns} for details. +% +% The optional |c|, |l|, or |r| controls the horizontal orientation of +% smallest output units (keywords, identifiers, etc.). The arguments +% work as follows, where vertical bars visualize the effect: +% $\vert$\lstinline[columns={[c]fixed}]!listing!$\vert$, +% $\vert$\lstinline[columns={[l]fixed}]!listing!$\vert$, and +% $\vert$\lstinline[columns={[r]fixed}]!listing!$\vert$ in fixed column +% mode, +% $\vert$\lstinline[columns={[c]flexible}]!listing!$\vert$, +% $\vert$\lstinline[columns={[l]flexible}]!listing!$\vert$, and +% $\vert$\lstinline[columns={[r]flexible}]!listing!$\vert$ with +% flexible columns, and +% $\vert$\lstinline[columns={[c]fullflexible}]!listing!$\vert$, +% $\vert$\lstinline[columns={[l]fullflexible}]!listing!$\vert$, and +% $\vert$\lstinline[columns={[r]fullflexible}]!listing!$\vert$ with +% space-flexible or full flexible columns (which ignore the optional +% argument, since they do not add extra space around printable +% characters). +% +% \item[0.18,false] +% \rkeyname{flexiblecolumns}|=|\meta{\alternative{true,false}}^^A +% \syntaxor\rkeyname{flexiblecolumns} +% +% selects the most recently selected flexible or fixed column format, +% refer to section \ref{uFixedAndFlexibleColumns}. +% +% \item[0.21,false,\dag] +% \rkeyname{keepspaces}|=|\meta{\alternative{true,false}} +% +% |keepspaces=true| tells the package not to drop spaces to fix column +% alignment and always converts tabulators to spaces. +% +% \item[0.16] \rkeyname{basewidth}|=|\meta{dimension}\syntaxor +% \item[0.18,{{0.6em,0.45em}}] +% \rkeyname{basewidth}|={|\meta{fixed}|,|\meta{flexible mode}|}| +% +% sets the width of a single character box for fixed and flexible +% column mode (both to the same value or individually). +% +% \item[0.20,false] +% \rkeyname{fontadjust}|=|\meta{\alternative{true,false}}^^A +% \syntaxor\rkeyname{fontadjust} +% +% If true the package adjusts the base width every font selection. +% This makes sense only if \ikeyname{basewidth} is given in font +% specific units like `em' or `ex'---otherwise this boolean has no +% effect. +% +% After loading the package, it doesn't adjust the width every font +% selection: it looks at \ikeyname{basewidth} each listing and uses the +% value for the whole listing. This is possibly inadequate if the style +% keys in section \ref{rFigureOutTheAppearance} make heavy font size +% changes, see the example below. +% +% Note that this key might disturb the column alignment and might have +% an effect on the keywords' appearance! % \end{syntax} % \begin{lstsample}{\lstset{basicstyle=\normalsize}}{} % \lstset{commentstyle=\scriptsize} @@ -2938,7 +3064,7 @@ % \end{lstsample} % % -% \subsection{Escaping to \LaTeX}\label{rEscapingToLaTeX} +% \subsubsection{Escaping to \LaTeX}\label{rEscapingToLaTeX} % % \textbf{Note:} {\itshape Any escape to \LaTeX\ may disturb the column % alignment since the package can't control the spacing there.} @@ -2960,32 +3086,36 @@ % \end{lstsample} % % \begin{syntax} -% \item[0.19,false] \rkeyname{mathescape}|=|\meta{\alternative{true,false}} +% \item[0.19,false] +% \rkeyname{mathescape}|=|\meta{\alternative{true,false}} % -% activates or deactivates special behaviour of the dollar sign. -% If activated a dollar sign acts as \TeX's text math shift. +% activates or deactivates special behaviour of the dollar sign. If +% activated a dollar sign acts as \TeX's text math shift. % -% This key is useful if you want to typeset formulas in listings. +% This key is useful if you want to typeset formulas in listings. % -% \item[0.19,{{}}] \rkeyname{escapechar}|=|\meta{character}\syntaxor\rkeyname{escapechar}|={}| +% \item[0.19,{{}}] +% \rkeyname{escapechar}|=|\meta{character}\syntaxor\rkeyname{escapechar}|={}| % -% If not empty the given character escapes the user to \LaTeX: all code -% between two such characters is interpreted as \LaTeX\ code. Note that -% \TeX's special characters must be entered with a preceding backslash, -% e.g.~|escapechar=\%|. +% If not empty the given character escapes the user to \LaTeX: all code +% between two such characters is interpreted as \LaTeX\ code. Note that +% \TeX's special characters must be entered with a preceding backslash, +% e.g.~|escapechar=\%|. % -% \item[0.20,{{}}] \rkeyname{escapeinside}|=|\meta{character}\meta{character}\syntaxor\rkeyname{escapeinside}|={}| +% \item[0.20,{{}}] +% \rkeyname{escapeinside}|=|\meta{character}\meta{character}^^A +% \syntaxor\rkeyname{escapeinside}|={}| % -% Is a generalization of \ikeyname{escapechar}. If the value is not -% empty, the package escapes to \LaTeX\ between the first and second -% character. +% Is a generalization of \ikeyname{escapechar}. If the value is not +% empty, the package escapes to \LaTeX\ between the first and second +% character. % -% \item[0.20,{{}}] \rkeyname{escapebegin}|=|\meta{tokens} -% \item[0.20,{{}}] \rkeyname{escapeend}|=|\meta{tokens} +% \item[0.20,{{}}] \rkeyname{escapebegin}|=|\meta{tokens} +% \item[0.20,{{}}] \rkeyname{escapeend}|=|\meta{tokens} % -% The tokens are executed at the beginning respectively at the end of -% each escape, in particular for \ikeyname{texcl}. -% See section \ref{uNationalCharacters} for an application. +% The tokens are executed at the beginning respectively at the end of +% each escape, in particular for \ikeyname{texcl}. See section +% \ref{uNationalCharacters} for an application. % \end{syntax} % % \begin{lstsample}{\lstset{morecomment=[l]//}}{} @@ -3036,32 +3166,38 @@ % some remarkable features the \packagename{listings} package doesn't have. % (Some are possible, but you must find somebody who will implement them |;-)|. % \begin{syntax} -% \item[0.19] \rkeyname{fancyvrb}|=|\meta{\alternative{true,false}} -% -% activates or deactivates the interface. If active, verbatim code is -% read by \packagename{fancyvrb} but typeset by \packagename{listings}, -% i.e.~with emphasized keywords, strings, comments, and so on. -% Internally we use a very special definition of |\FancyVerbFormatLine|. -% -% This interface works with |Verbatim|, |BVerbatim| and |LVerbatim|. -% But you shouldn't use \packagename{fancyvrb}'s \keyname{defineactive}. -% (As far as I can see it doesn't matter since it does nothing at all, -% but for safety \ldots .) -% If \packagename{fancyvrb} and \packagename{listings} provide similar -% functionality, you should use \packagename{fancyvrb}'s. -% -% \item[1.1,{\overlay 1}] \rkeyname{fvcmdparams}|=|\meta{command$_1$}\meta{number$_1$}\ldots\label{uoption:fvcmdparams} -% \item[1.1] \rkeyname{morefvcmdparams}|=|\meta{command$_1$}\meta{number$_1$}\ldots\label{uoption:morefvcmdparams} -% -% If you use \packagename{fancyvrb}'s \keyname{commandchars}, you must -% tell the \packagename{listings} package how many arguments each command -% takes. If a command takes no arguments, there is nothing to do. -% -% The first (third, fifth, \ldots) parameter to the keys is the command -% and the second (fourth, sixth, \ldots) is the number of arguments -% that command takes. So, if you want to use |\textcolor{red}{keyword}| -% with the \packagename{fancyvrb}-\packagename{listings} interface, you -% should write |\lstset{morefvcmdparams=\textcolor 2}|. +% \item[0.19] \rkeyname{fancyvrb}|=|\meta{\alternative{true,false}} +% +% activates or deactivates the interface. If active, verbatim code is +% read by \packagename{fancyvrb} but typeset by \packagename{listings}, +% i.e.~with emphasized keywords, strings, comments, and so on. +% Internally we use a very special definition of +% |\FancyVerbFormatLine|. +% +% This interface works with |Verbatim|, |BVerbatim| and |LVerbatim|. +% But you shouldn't use \packagename{fancyvrb}'s +% \keyname{defineactive}. (As far as I can see it doesn't matter since +% it does nothing at all, but for safety \ldots .) If +% \packagename{fancyvrb} and \packagename{listings} provide similar +% functionality, you should use \packagename{fancyvrb}'s. +% +% \item[1.1,{\overlay 1}] +% \rkeyname{fvcmdparams}|=|\meta{command$_1$}\meta{number$_1$}^^A +% \ldots\label{uoption:fvcmdparams} +% \item[1.1] +% \rkeyname{morefvcmdparams}|=|\meta{command$_1$}\meta{number$_1$}^^A +% \ldots\label{uoption:morefvcmdparams} +% +% If you use \packagename{fancyvrb}'s \keyname{commandchars}, you must +% tell the \packagename{listings} package how many arguments each +% command takes. If a command takes no arguments, there is nothing to +% do. +% +% The first (third, fifth, \ldots) parameter to the keys is the command +% and the second (fourth, sixth, \ldots) is the number of arguments +% that command takes. So, if you want to use |\textcolor{red}{keyword}| +% with the \packagename{fancyvrb}-\packagename{listings} interface, you +% should write |\lstset{morefvcmdparams=\textcolor 2}|. % \end{syntax} % % \iffancyvrb @@ -3152,7 +3288,11 @@ % to language definitions. Otherwise you're probably unprepared for the full % syntax of |\lstdefinelanguage|. % \begin{syntax} -% \item[0.19] \rcmdname\lstdefinelanguage\syntaxnewline[\oarg{dialect}]\marg{language}\syntaxnewline[\oarg{base dialect}\marg{and base language}]\syntaxnewline\marg{key=value list}\syntaxnewline[\oarg{list of required aspects \textup(keywordcomments,texcs,etc.\textup)}] +% \item[0.19] \rcmdname\lstdefinelanguage\syntaxnewline[\oarg{dialect}]^^A +% \marg{language}\syntaxnewline[\oarg{base dialect}^^A +% \marg{and base language}]\syntaxnewline\marg{key=value list}^^A +% \syntaxnewline[\oarg{list of required aspects ^^A +% \textup(keywordcomments,texcs,etc.\textup)}] % % defines the (given dialect of the) programming language \meta{language}. % If the language definition is based on another definition, you must @@ -3203,90 +3343,103 @@ % {\upshape|\|, |{|, |}|, |%|, |#|} or {\upshape|&|} as (part of) an argument % to the keywords below, you must do it with a preceding backslash!} % \begin{syntax} -% \item[1.0,,{\dag bug}] \rkeyname{keywordsprefix}|=|\meta{prefix} -% -% All identifiers starting with \meta{prefix} will be printed as first -% order keywords. -% -% Bugs: Currently there are several limitations. -% (1) The prefix is always case sensitive. -% (2) Only one prefix can be defined at a time. -% (3) If used `standalone' outside a language definition, the key might -% work only after selecting a nonempty language (and switching back to -% the empty language if necessary). -% (4) The key does not respect the value of \keyname{classoffset} and -% has no optional class \meta{number} argument. -% -% \item[0.11] \rkeyname{keywords}|=|\oarg{number}\marg{list of keywords} -% \item[0.11] \rkeyname{morekeywords}|=|\oarg{number}\marg{list of keywords} -% \item[0.18] \rkeyname{deletekeywords}|=|\oarg{number}\marg{list of keywords} -% -% define, add to or remove the keywords from keyword list \meta{number}. -% The use of \keyname{keywords} is discouraged since it deletes all -% previously defined keywords in the list and is thus incompatible with -% the \keyname{alsolanguage} key. -% -% Please note the keys \ikeyname{alsoletter} and \ikeyname{alsodigit} -% below if you use unusual charaters in keywords. -% -% \item[0.19,,deprecated] \rkeyname{ndkeywords}|=|\marg{list of keywords} -% \item[0.19,,deprecated] \rkeyname{morendkeywords}|=|\marg{list of keywords} -% \item[0.19,,deprecated] \rkeyname{deletendkeywords}|=|\marg{list of keywords} -% -% define, add to or remove the keywords from keyword list 2; note that -% this is equivalent to |keywords=[2]|\ldots etc. -% The use of \keyname{ndkeywords} is strongly discouraged. -% -% \item[0.19,,{addon,optional}] \rkeyname{texcs}|=|\oarg{class number}\marg{list of control sequences \textup(without backslashes\textup)} -% \item[0.20,,{addon,optional}] \rkeyname{moretexcs}|=|\oarg{class number}\marg{list of control sequences \textup(without backslashes\textup)} -% \item[0.21,,{addon,optional}] \rkeyname{deletetexcs}|=|\oarg{class number}\marg{list of control sequences \textup(without backslashes\textup)} -% -% Ditto for control sequences in \TeX\ and \LaTeX. -% -% \item[0.18,,optional] \rkeyname{directives}|=|\marg{list of compiler directives} -% \item[0.21,,optional] \rkeyname{moredirectives}|=|\marg{list of compiler directives} -% \item[0.21,,optional] \rkeyname{deletedirectives}|=|\marg{list of compiler directives} -% -% defines compiler directives in C, \Cpp, Objective-C, and POV. -% -% \item[0.14] \rkeyname{sensitive}|=|\meta{\alternative{true,false}} -% -% makes the keywords, control sequences, and directives case sensitive -% and insensitive, respectively. This key affects the keywords, control -% sequences, and directives only when a listing is processed. In all -% other situations they are case sensitive, for example, -% |deletekeywords={save,Test}| removes `save' and `Test', but neither -% `SavE' nor `test'. -% -% \item[0.19] \rkeyname{alsoletter}|=|\marg{character sequence} -% \item[0.19] \rkeyname{alsodigit}|=|\marg{character sequence} -% \item[0.19] \rkeyname{alsoother}|=|\marg{character sequence} -% -% All identifiers (keywords, directives, and such) consist of a letter -% followed by alpha-numeric characters (letters and digits). -% For example, if you write -% |keywords={one-two,\#include}|, -% the minus sign must become a digit and the sharp a letter since the -% keywords can't be detected otherwise. -% -% Table \ref{rStdCharTable} show the standard configuration of the -% \packagename{listings} package. The three keys overwrite the default -% behaviour. Each character of the sequence becomes a letter, digit -% and other, respectively. -% -% \item[0.20] \rkeyname{otherkeywords}|=|\marg{keywords} -% -% Defines keywords that contain other characters, or start with digits. -% Each given `keyword' is printed in keyword style, but without changing -% the `letter', `digit' and `other' status of the characters. This key -% is designed to define keywords like |=>|, |->|, |-->|, |--|, |::|, and -% so on. If one keyword is a subsequence of another (like |--| and -% |-->|), you must specify the shorter first. -% -% \item[0.20,,{renamed,optional}] \rkeyname{tag}|=|\meta{character}\meta{character}\syntaxor\rkeyname{tag}|={}|\label{uoption:tag} -% -% The first order keywords are active only between the first and second -% character. This key is used for HTML. +% \item[1.0,,{\dag bug}] \rkeyname{keywordsprefix}|=|\meta{prefix} +% +% All identifiers starting with \meta{prefix} will be printed as first +% order keywords. +% +% Bugs: Currently there are several limitations. (1) The prefix is +% always case sensitive. (2) Only one prefix can be defined at a time. +% (3) If used `standalone' outside a language definition, the key might +% work only after selecting a nonempty language (and switching back to +% the empty language if necessary). (4) The key does not respect the +% value of \keyname{classoffset} and has no optional class +% \meta{number} argument. +% +% \item[0.11] \rkeyname{keywords}|=|\oarg{number}\marg{list of keywords} +% \item[0.11] \rkeyname{morekeywords}|=|\oarg{number}\marg{list of +% keywords} +% \item[0.18] \rkeyname{deletekeywords}|=|\oarg{number}\marg{list of +% keywords} +% +% define, add to or remove the keywords from keyword list +% \meta{number}. The use of \keyname{keywords} is discouraged since it +% deletes all previously defined keywords in the list and is thus +% incompatible with the \keyname{alsolanguage} key. +% +% Please note the keys \ikeyname{alsoletter} and \ikeyname{alsodigit} +% below if you use unusual charaters in keywords. +% +% \item[0.19,,deprecated] \rkeyname{ndkeywords}|=|\marg{list of keywords} +% \item[0.19,,deprecated] \rkeyname{morendkeywords}|=|\marg{list of +% keywords} +% \item[0.19,,deprecated] \rkeyname{deletendkeywords}|=|\marg{list of +% keywords} +% +% define, add to or remove the keywords from keyword list 2; note that +% this is equivalent to |keywords=[2]|\ldots etc. The use of +% \keyname{ndkeywords} is strongly discouraged. +% +% \item[0.19,,{addon,optional}] \rkeyname{texcs}|=|\oarg{class +% number}\marg{list of control sequences \textup(without +% backslashes\textup)} +% \item[0.20,,{addon,optional}] \rkeyname{moretexcs}|=|\oarg{class +% number}\marg{list of control sequences \textup(without +% backslashes\textup)} +% \item[0.21,,{addon,optional}] \rkeyname{deletetexcs}|=|\oarg{class +% number}\marg{list of control sequences \textup(without +% backslashes\textup)} +% +% Ditto for control sequences in \TeX\ and \LaTeX. +% +% \item[0.18,,optional] \rkeyname{directives}|=|\marg{list of compiler +% directives} +% \item[0.21,,optional] \rkeyname{moredirectives}|=|\marg{list of +% compiler directives} +% \item[0.21,,optional] \rkeyname{deletedirectives}|=|\marg{list of +% compiler directives} +% +% defines compiler directives in C, \Cpp, Objective-C, and POV. +% +% \item[0.14] \rkeyname{sensitive}|=|\meta{\alternative{true,false}} +% +% makes the keywords, control sequences, and directives case sensitive +% and insensitive, respectively. This key affects the keywords, control +% sequences, and directives only when a listing is processed. In all +% other situations they are case sensitive, for example, +% |deletekeywords={save,Test}| removes `save' and `Test', but neither +% `SavE' nor `test'. +% +% \item[0.19] \rkeyname{alsoletter}|=|\marg{character sequence} +% \item[0.19] \rkeyname{alsodigit}|=|\marg{character sequence} +% \item[0.19] \rkeyname{alsoother}|=|\marg{character sequence} +% +% All identifiers (keywords, directives, and such) consist of a letter +% followed by alpha-numeric characters (letters and digits). For +% example, if you write |keywords={one-two,\#include}|, the minus sign +% must become a digit and the sharp a letter since the keywords can't +% be detected otherwise. +% +% Table \ref{rStdCharTable} show the standard configuration of the +% \packagename{listings} package. The three keys overwrite the default +% behaviour. Each character of the sequence becomes a letter, digit and +% other, respectively. +% +% \item[0.20] \rkeyname{otherkeywords}|=|\marg{keywords} +% +% Defines keywords that contain other characters, or start with digits. +% Each given `keyword' is printed in keyword style, but without +% changing the `letter', `digit' and `other' status of the +% characters. This key is designed to define keywords like |=>|, |->|, +% |-->|, |--|, |::|, and so on. If one keyword is a subsequence of +% another (like |--| and |-->|), you must specify the shorter first. +% +% \item[0.20,,{renamed,optional}] +% \rkeyname{tag}|=|\meta{character}\meta{character}^^A +% \syntaxor\rkeyname{tag}|={}|\label{uoption:tag} +% +% The first order keywords are active only between the first and second +% character. This key is used for HTML. % \end{syntax} % % \begin{table}[tb] @@ -3299,7 +3452,8 @@ % & \texttt{@ \textdollar\ } |_|\\ % digit & \texttt{0 1 2 3 4 5 6 7 8 9}\\ % other & \texttt{!\ " \#\ \%\ \&\ ' ( ) * + , - .\ / :\ ; < = > ?}\\ -% & {\catcode`\|=12\texttt{[ \char92\ ] \textasciicircum\ \char123\ | \char125\ \textasciitilde}}\\ +% & {\catcode`\|=12\texttt{[ \char92\ ] \textasciicircum\ \char123\ +% | \char125\ \textasciitilde}}\\ % space & chr(32)\\ % tabulator & chr(9)\\ % form feed & chr(12)\\ @@ -3313,94 +3467,106 @@ % % \paragraph{Strings} % \begin{syntax} -% \item[0.12] \rkeyname{string}|=|\oarg{\alternative{b,d,m,bd,s}}\marg{delimiter \textup(character\textup)} -% \item[0.21] \rkeyname{morestring}|=|\oarg{\alternative{b,d,m,bd,s}}\marg{delimiter} -% \item[0.21] \rkeyname{deletestring}|=|\oarg{\alternative{b,d,m,bd,s}}\marg{delimiter} -% -% define, add to or delete the delimiter from the list of string -% delimiters. Starting and ending delimiters are the same, i.e.~in the -% source code the delimiters must match each other. -% -% The optional argument is the type and controls the how the delimiter -% itself is represented in a string or character literal: it is escaped by a -% |b|ackslash, |d|oubled (or both is allowed via |bd|). Alternately, the -% type can refer to an unusual form of delimiter: |s|tring delimiters (akin -% to the |s| comment type) or |m|atlab-style delimiters. The latter is a -% special type for Ada and Matlab and possibly other languages where the -% string delimiters are also used for other purposes. It is equivalent -% to |d|, except that a string does not start after a letter, a right -% parenthesis, a right bracket, or some other characters. +% \item[0.12] +% \rkeyname{string}|=|\oarg{\alternative{b,d,m,bd,s}}\marg{delimiter +% \textup(character\textup)} +% \item[0.21] +% \rkeyname{morestring}|=|\oarg{\alternative{b,d,m,bd,s}}\marg{delimiter} +% \item[0.21] +% \rkeyname{deletestring}|=|\oarg{\alternative{b,d,m,bd,s}}\marg{delimiter} +% +% define, add to or delete the delimiter from the list of string +% delimiters. Starting and ending delimiters are the same, i.e.~in the +% source code the delimiters must match each other. +% +% The optional argument is the type and controls the how the delimiter +% itself is represented in a string or character literal: it is escaped +% by a |b|ackslash, |d|oubled (or both is allowed via |bd|). +% Alternately, the type can refer to an unusual form of delimiter: +% |s|tring delimiters (akin to the |s| comment type) or |m|atlab-style +% delimiters. The latter is a special type for Ada and Matlab and +% possibly other languages where the string delimiters are also used +% for other purposes. It is equivalent to |d|, except that a string +% does not start after a letter, a right parenthesis, a right bracket, +% or some other characters. % \end{syntax} % % % \paragraph{Comments} % \begin{syntax} -% \item[0.13] \rkeyname{comment}|=|\oarg{type}\meta{delimiter\textup(s\textup)} -% \item[0.21] \rkeyname{morecomment}|=|\oarg{type}\meta{delimiter\textup(s\textup)} -% \item[0.21] \rkeyname{deletecomment}|=|\oarg{type}\meta{delimiter\textup(s\textup)} -% -% Ditto for comments, but some types require more than a single -% delimiter. The following overview uses \keyname{morecomment} as the -% example, but the examples apply to \keyname{comment} and \keyname{deletecomment} -% as well. -% -% \item[0.13] \keyname{morecomment}|=[l]|\meta{delimiter} -% -% The delimiter starts a comment line, which in general starts with the -% delimiter and ends at end of line. If the character sequence |//| -% should start a comment line (like in \Cpp, Comal 80 or Java), -% |morecomment=[l]//| is the correct declaration. For Matlab it -% would be |morecomment=[l]\%|---note the preceding backslash. -% -% \item[0.13] \keyname{morecomment}|=[s]|\marg{delimiter}\marg{delimiter} -% -% Here we have two delimiters. The second ends a comment starting with -% the first delimiter. If you require two such comments you can use this -% type twice. C, Java, PL/I, Prolog and SQL all define single comments -% via |morecomment=[s]{/*}{*/}|, and Algol does it with -% |morecomment=[s]{\#}{\#}|, which means that the sharp delimits both -% beginning and end of a single comment. -% -% \item[0.13] \keyname{morecomment}|=[n]|\marg{delimiter}\marg{delimiter} -% -% is similar to type |s|, but comments can be nested. Identical arguments -% are not allowed---think a while about it! -% Modula-2 and Oberon-2 use |morecomment=[n]{(*}{*)}|. -% -% \item[0.18] \keyname{morecomment}|=[f]|\meta{delimiter} -% \item[0.18] \keyname{morecomment}|=[f][commentstyle]|\oarg{n=preceding columns}\meta{delimiter} -% -% The delimiter starts a comment line if and only if it appears on a -% fixed column-number, namely if it is in column $n$ (zero based). -% -% \item[0.17,,optional] \rkeyname{keywordcomment}|=|\marg{keywords} -% \item[0.21,,optional] \rkeyname{morekeywordcomment}|=|\marg{keywords} -% \item[0.21,,optional] \rkeyname{deletekeywordcomment}|=|\marg{keywords} -% -% A keyword comment begins with a keyword and ends with the same keyword. -% Consider |keywordcomment={comment,co}|. Then -% `\textbf{comment}\allowbreak\ldots\textbf{comment}' and -% `\textbf{co}\ldots\textbf{co}' are comments. -% -% \item[0.17,,optional] \rkeyname{keywordcommentsemicolon}|=|\marg{keywords}\marg{keywords}\marg{keywords} -% -% The definition of a `keyword comment semicolon' requires three keyword -% lists, e.g.~|{end}{else,end}{comment}|. A semicolon always ends such a -% comment. Any keyword of the first argument begins a comment and any -% keyword of the second argument ends it (and a semicolon also); -% a comment starting with any keyword of the third argument is terminated -% with the next semicolon only. In the example all possible comments are -% `\textbf{end}\ldots\textbf{else}', `\textbf{end}\ldots\textbf{end}' -% (does not start a comment again) and `\textbf{comment}\ldots;' and -% `\textbf{end}\ldots;'. -% Maybe a curious definition, but Algol and Simula use such comments. -% -% Note: The keywords here need not to be a subset of the defined -% keywords. They won't appear in keyword style if they aren't. -% -% \item[0.17,,optional] \rkeyname{podcomment}|=|\meta{\alternative{true,false}} -% -% activates or deactivates PODs---Perl specific. +% \item[0.13] +% \rkeyname{comment}|=|\oarg{type}\meta{delimiter\textup(s\textup)} +% \item[0.21] +% \rkeyname{morecomment}|=|\oarg{type}\meta{delimiter\textup(s\textup)} +% \item[0.21] +% \rkeyname{deletecomment}|=|\oarg{type}\meta{delimiter\textup(s\textup)} +% +% Ditto for comments, but some types require more than a single +% delimiter. The following overview uses \keyname{morecomment} as the +% example, but the examples apply to \keyname{comment} and +% \keyname{deletecomment} as well. +% +% \item[0.13] \keyname{morecomment}|=[l]|\meta{delimiter} +% +% The delimiter starts a comment line, which in general starts with the +% delimiter and ends at end of line. If the character sequence |//| +% should start a comment line (like in \Cpp, Comal 80 or Java), +% |morecomment=[l]//| is the correct declaration. For Matlab it would +% be |morecomment=[l]\%|---note the preceding backslash. +% +% \item[0.13] \keyname{morecomment}|=[s]|\marg{delimiter}\marg{delimiter} +% +% Here we have two delimiters. The second ends a comment starting with +% the first delimiter. If you require two such comments you can use +% this type twice. C, Java, PL/I, Prolog and SQL all define single +% comments via |morecomment=[s]{/*}{*/}|, and Algol does it with +% |morecomment=[s]{\#}{\#}|, which means that the sharp delimits both +% beginning and end of a single comment. +% +% \item[0.13] \keyname{morecomment}|=[n]|\marg{delimiter}\marg{delimiter} +% +% is similar to type |s|, but comments can be nested. Identical +% arguments are not allowed---think a while about it! Modula-2 and +% Oberon-2 use |morecomment=[n]{(*}{*)}|. +% +% \item[0.18] \keyname{morecomment}|=[f]|\meta{delimiter} +% \item[0.18] \keyname{morecomment}|=[f][commentstyle]|\oarg{n=preceding +% columns}\meta{delimiter} +% +% The delimiter starts a comment line if and only if it appears on a +% fixed column-number, namely if it is in column $n$ (zero based). +% +% \item[0.17,,optional] \rkeyname{keywordcomment}|=|\marg{keywords} +% \item[0.21,,optional] \rkeyname{morekeywordcomment}|=|\marg{keywords} +% \item[0.21,,optional] \rkeyname{deletekeywordcomment}|=|\marg{keywords} +% +% A keyword comment begins with a keyword and ends with the same +% keyword. Consider |keywordcomment={comment,co}|. Then +% `\textbf{comment}\allowbreak\ldots\textbf{comment}' and +% `\textbf{co}\ldots\textbf{co}' are comments. +% +% \item[0.17,,optional] +% \rkeyname{keywordcommentsemicolon}|=|\marg{keywords}\marg{keywords}^^A +% \marg{keywords} +% +% The definition of a `keyword comment semicolon' requires three +% keyword lists, e.g.~|{end}{else,end}{comment}|. A semicolon always +% ends such a comment. Any keyword of the first argument begins a +% comment and any keyword of the second argument ends it (and a +% semicolon also); a comment starting with any keyword of the third +% argument is terminated with the next semicolon only. In the example +% all possible comments are `\textbf{end}\ldots\textbf{else}', +% `\textbf{end}\ldots\textbf{end}' (does not start a comment again) and +% `\textbf{comment}\ldots;' and `\textbf{end}\ldots;'. Maybe a curious +% definition, but Algol and Simula use such comments. +% +% Note: The keywords here need not to be a subset of the defined +% keywords. They won't appear in keyword style if they aren't. +% +% \item[0.17,,optional] +% \rkeyname{podcomment}|=|\meta{\alternative{true,false}} +% +% activates or deactivates PODs---Perl specific. % \end{syntax} % % @@ -3605,7 +3771,9 @@ % \subsection{Literate programming} % % We begin with an example and hide the crucial key=value list. -% \begin{lstsample}{\lstset{literate={:=}{{$\gets$}}1 {<=}{{$\leq$}}1 {>=}{{$\geq$}}1 {<>}{{$\neq$}}1}}{} +% \begin{lstsample}{% +% \lstset{literate={:=}{{$\gets$}}1 {<=}{{$\leq$}}1 {>=}{{$\geq$}}1 ^^A +% {<>}{{$\neq$}}1}}{} % \begin{lstlisting} % var i:integer; % @@ -3619,28 +3787,29 @@ % Now you might want to know how this has been done. Have a \emph{close} % look at the following key. % \begin{syntax} -% \item[0.20,,\dag] \rkeyname{literate}|=|[|*|]\meta{replacement item}\ldots\meta{replacement item} -% -% First note that there are no commas between the items. Each item -% consists of three arguments: -% \marg{replace}\marg{replacement text}\marg{length}. -% \meta{replace} is the original character sequence. -% Instead of printing these characters, we use \meta{replacement text}, -% which takes the width of \meta{length} characters in the output. -% -% Each `printing unit' in \meta{replacement text} \emph{must} be in braces -% unless it's a single character. For example, you must put braces -% around |$\leq$|. -% If you want to replace |<-1->| by |$\leftarrow1\rightarrow$|, the -% replacement item would be |{<-1->}{{$\leftarrow$}1{$\rightarrow$}}3|. -% Note the braces around the arrows. -% -% If one \meta{replace} is a subsequence of another \meta{replace}, you -% must define the shorter sequence first. For example, |{-}| must be defined -% before |{--}| and this before |{-->}|. -% -% The optional star indicates that literate replacements should not be -% made in strings, comments, and other delimited text. +% \item[0.20,,\dag] \rkeyname{literate}|=|[|*|]\meta{replacement +% item}\ldots\meta{replacement item} +% +% First note that there are no commas between the items. Each item +% consists of three arguments: \marg{replace}\marg{replacement +% text}\marg{length}. \meta{replace} is the original character +% sequence. Instead of printing these characters, we use +% \meta{replacement text}, which takes the width of \meta{length} +% characters in the output. +% +% Each `printing unit' in \meta{replacement text} \emph{must} be in +% braces unless it's a single character. For example, you must put +% braces around |$\leq$|. If you want to replace |<-1->| by +% |$\leftarrow1\rightarrow$|, the replacement item would be +% |{<-1->}{{$\leftarrow$}1{$\rightarrow$}}3|. Note the braces around +% the arrows. +% +% If one \meta{replace} is a subsequence of another \meta{replace}, you +% must define the shorter sequence first. For example, |{-}| must be +% defined before |{--}| and this before |{-->}|. +% +% The optional star indicates that literate replacements should not be +% made in strings, comments, and other delimited text. % \end{syntax} % In the example above, I've used % \begin{verbatim} @@ -3688,7 +3857,8 @@ % (possibly not the definitions but the results). A single `format item' has % the form % \begin{itemize}\item[] -% \meta{input chars}|=|\oarg{exceptional chars}\meta{pre}\oarg{\texttt{\string\string}}\meta{post} +% \meta{input chars}|=|\oarg{exceptional chars}\meta{pre}\oarg{^^A +% \texttt{\string\string}}\meta{post} % \end{itemize} % Whenever \meta{input chars} aren't followed by one of the \meta{exceptional % chars}, formatting is done according to the rest of the value. If |\string| @@ -4100,7 +4270,8 @@ % package. % % -% \subsubsection*{How to print national characters with $\Lambda$ and \packagename{listings}}\label{uNationalCharacters} +% \subsubsection*{How to print national characters with $\Lambda$ and +% \packagename{listings}}\label{uNationalCharacters} % % Apart from typing in national characters directly, you can use the `escape' % feature described in section \ref{rEscapingToLaTeX}. @@ -4144,7 +4315,7 @@ % % % \subsubsection*{How to get bold typewriter type keywords} -% Use the \href{http://www.ctan.org/tex-archive/fonts/luximono}{\packagename{LuxiMono}} package. +% Use the \href{http://mirror.ctan.org/fonts/luximono}{\packagename{LuxiMono}} package. % % \iffalse % Many people asked for bold typewriter fonts since they aren't included in @@ -4495,7 +4666,9 @@ % the listing is part of a tabular environment as found out by % \lsthelper{Nasser~M.~Abbasi}{2016/05/25}{possible bug in listings % package}. \lsthelper{David~Carlisle}{2016/05/25}{% -% http://tex.stackexchange.com/questions/311383/adding-frame-none-to-lstlisting-options-in-lstdefinestyle-gives-error-with-tabu} +% http://tex.stackexchange.com/questions/311383/^^A +% adding-frame-none-to-lstlisting-options-in-lstdefinestyle^^A +% -gives-error-with-tabu} % gave a hint how to avoid this problem and so the separator |&| is % replaced by |:|. % @@ -5081,94 +5254,94 @@ % syntax is shown on the left. On the right you'll find examples how the % package actually defines some keys. % \begin{syntax} -% \item[0.21] -% \cs{lst@InstallFamily} -% -% \marg{prefix}\syntaxfill \texttt k\\ -% \marg{name}\syntaxfill |{keywords}|\\ -% \marg{style name}\syntaxfill |{keywordstyle}|\\ -% \marg{style init}\syntaxfill |\bfseries|\\ -% \marg{default style name}\syntaxfill |{keywordstyle}|\\ -% \marg{working procedure}\syntaxfill |{}|\\ -% \meta{\alternative{l,o}}\syntaxfill |l|\\ -% \meta{\alternative{d,o}}\syntaxfill |d| -% -% installs either a keyword or `working' class of identifiers according -% to whether \meta{working procedure} is empty. -% -% The three keys \meta{name}, \keyname{more}\meta{name} and -% \keyname{delete}\meta{name}, and if not empty \meta{style name} are -% defined. The first order member of the latter one is initialized with -% \meta{style init} if not equivalent to |\relax|. If the user leaves a -% class style undefined, \meta{default style name} is used instead. -% Thus, make sure that this style is always defined. In the example, -% the first order keywordstyle is set to |\bfseries| and is the default -% for all other classes. -% -% If \meta{working procedure} is not empty, this code is executed when -% reaching such an (user defined) identifier. \meta{working procedure} -% takes exactly one argument, namely the class number to which the -% actual identifier belongs to. If the code uses variables and requires -% values from previous calls, you must define these variables -% |\global|ly. It's not sure whether working procedures are executed -% inside a (separate) group or not. -% -% \texttt l indicates a language key, i.e.~the lists are reset every -% language selection. \texttt o stands for `other' key. -% The keyword respectively working test is either installed at the -% \hookname{DetectKeyword} or \hookname{Output} hook according to -% \meta{\alternative{d,o}}. -% -% \item[0.20] -% \cs{lst@InstallKeywords} -% -% \marg{prefix}\syntaxfill \texttt{cs}\\ -% \marg{name}\syntaxfill |{texcs}|\\ -% \marg{style name}\syntaxfill |{texcsstyle}|\\ -% \marg{style init}\syntaxfill |\relax|\\ -% \marg{default style name}\syntaxfill |{keywordstyle}|\\ -% \marg{working procedure}\syntaxfill see below\\ -% \meta{\alternative{l,o}}\syntaxfill |l|\\ -% \meta{\alternative{d,o}}\syntaxfill |d| -% -% Same parameters, same functionality with one execption. The macro -% installs exactly one keyword class and not a whole family. Therefore -% the argument to \meta{working procedure} is constant (currently empty). -% -% The working procedure of the example reads as follows.\vspace*{-.5\baselineskip} +% \item[0.21] \cs{lst@InstallFamily} +% +% \marg{prefix}\syntaxfill \texttt k\\ +% \marg{name}\syntaxfill |{keywords}|\\ +% \marg{style name}\syntaxfill |{keywordstyle}|\\ +% \marg{style init}\syntaxfill |\bfseries|\\ +% \marg{default style name}\syntaxfill |{keywordstyle}|\\ +% \marg{working procedure}\syntaxfill |{}|\\ +% \meta{\alternative{l,o}}\syntaxfill |l|\\ +% \meta{\alternative{d,o}}\syntaxfill |d| +% +% installs either a keyword or `working' class of identifiers according +% to whether \meta{working procedure} is empty. +% +% The three keys \meta{name}, \keyname{more}\meta{name} and +% \keyname{delete}\meta{name}, and if not empty \meta{style name} are +% defined. The first order member of the latter one is initialized with +% \meta{style init} if not equivalent to |\relax|. If the user leaves a +% class style undefined, \meta{default style name} is used instead. +% Thus, make sure that this style is always defined. In the example, +% the first order keywordstyle is set to |\bfseries| and is the default +% for all other classes. +% +% If \meta{working procedure} is not empty, this code is executed when +% reaching such an (user defined) identifier. \meta{working procedure} +% takes exactly one argument, namely the class number to which the +% actual identifier belongs to. If the code uses variables and requires +% values from previous calls, you must define these variables +% |\global|ly. It's not sure whether working procedures are executed +% inside a (separate) group or not. +% +% \texttt l indicates a language key, i.e.~the lists are reset every +% language selection. \texttt o stands for `other' key. The keyword +% respectively working test is either installed at the +% \hookname{DetectKeyword} or \hookname{Output} hook according to +% \meta{\alternative{d,o}}. +% +% \item[0.20] \cs{lst@InstallKeywords} +% +% \marg{prefix}\syntaxfill \texttt{cs}\\ +% \marg{name}\syntaxfill |{texcs}|\\ +% \marg{style name}\syntaxfill |{texcsstyle}|\\ +% \marg{style init}\syntaxfill |\relax|\\ +% \marg{default style name}\syntaxfill |{keywordstyle}|\\ +% \marg{working procedure}\syntaxfill see below\\ +% \meta{\alternative{l,o}}\syntaxfill |l|\\ +% \meta{\alternative{d,o}}\syntaxfill |d| +% +% Same parameters, same functionality with one execption. The macro +% installs exactly one keyword class and not a whole family. Therefore +% the argument to \meta{working procedure} is constant (currently +% empty). +% +% The working procedure of the example reads as +% follows.\vspace*{-.5\baselineskip} % \begin{verbatim} % {\ifx\lst@lastother\lstum@backslash % \let\lst@thestyle\lst@texcsstyle % \fi}\end{verbatim} -%\vspace*{-.5\baselineskip} -% What does this procedure do? First of all it is called only if a -% keyword from the user supplied list (or language definition) is found. -% The procedure now checks for a preceding backslash and sets the output -% style accordingly. +% % \vspace*{-.5\baselineskip} +% What does this procedure do? First of all it is called only if a keyword +% from the user supplied list (or language definition) is found. The +% procedure now checks for a preceding backslash and sets the output style +% accordingly. % -%\iffalse +% \iffalse % \item[0.20] |\lst@InstallTest|\marg{prefix}\syntaxbreak -% |\lst@|\meta{name}|@list||\lst@|\meta{name}~|\lst@g|\meta{name}|@list||\lst@g|\meta{name}\syntaxbreak -% |\lst@g|\meta{name}|@sty|~\meta{\alternative{w,s}}\meta{\alternative{d,o}} -% -% installs a `working identifier' test or keyword style depending on -% \meta{\alternative{w,s}}. |\lst@g|\meta{name}|@sty| contains the -% working procedure or style macro. Note that the behaviour of the tests -% depends on the \texttt{savemem} option. -% The keyword respectively working test is either installed at the -% \hookname{DetectKeyword} or \hookname{Output} hook according to -% \meta{\alternative{d,o}}. -% -%^^A Either each call of this macro or each different \meta{prefix} inserts -%^^A another test (depending on the \texttt{savemem} option). -% -% |\lst@|\meta{name} contains the current identifier list and -% |\lst@|\meta{name}|@list| a `|\lst@|\meta{$n_i$}|\lst@g|\meta{$n_i$}' -% sequence of currently used classes. If no other classes are used, -% this equals |\lst@|\meta{name}|\lst@g|\meta{name}. The global versions -% |\lst@g|\ldots\ are used to keep track of the keywords. -% (This description needs improvement.) -%\fi +% |\lst@|\meta{name}|@list||\lst@|\meta{name}~|\lst@g|\meta{name}|@list|^^A +% |\lst@g|\meta{name}\syntaxbreak +% |\lst@g|\meta{name}|@sty|~\meta{\alternative{w,s}}\meta{\alternative{d,o}} +% +% installs a `working identifier' test or keyword style depending on +% \meta{\alternative{w,s}}. |\lst@g|\meta{name}|@sty| contains the +% working procedure or style macro. Note that the behaviour of the tests +% depends on the \texttt{savemem} option. The keyword respectively +% working test is either installed at the \hookname{DetectKeyword} or +% \hookname{Output} hook according to \meta{\alternative{d,o}}. +% +% ^^A Either each call of this macro or each different \meta{prefix} +% inserts ^^A another test (depending on the \texttt{savemem} option). +% +% |\lst@|\meta{name} contains the current identifier list and +% |\lst@|\meta{name}|@list| a `|\lst@|\meta{$n_i$}|\lst@g|\meta{$n_i$}' +% sequence of currently used classes. If no other classes are used, this +% equals |\lst@|\meta{name}|\lst@g|\meta{name}. The global versions +% |\lst@g|\ldots\ are used to keep track of the keywords. (This +% description needs improvement.) +% \fi % \end{syntax} % % @@ -5321,37 +5494,40 @@ % Note that the user supplied value covers the second and third line of % arguments. % \begin{syntax} -% \item[0.21,,changed] -% \cs{lst@Delim} -% -% \meta{default style macro}\syntaxfill \cs{lst@commentstyle}\\ \relax -% [\texttt*[\texttt*]]\texttt[\meta{type}\texttt][\texttt[\meta{style}\texttt][\texttt[\meta{type option}\texttt]]]\\ -% \meta{delimiter\textup(s\textup)}\cs{relax}\syntaxfill|#2|\cs{relax}\\ -% \marg{delimiter name}\syntaxfill|{Comment}|\\ -% \meta{delimiter types macro}\syntaxfill\texttt{\cs{lst@commenttypes}}\\ -% \alternative{\cs{@empty},\cs{@nil},\cs{relax}}\syntaxfill|#1|\\ -% \marg{begin- and end-delim macro}\syntaxfill|{|\cs{lst@BeginComment}\cs{lst@EndComment}|}|\\ -% \meta{extra prefix}\syntaxfill |i|\\ -% \meta{extra conversion}\syntaxfill |\@empty|\\ -% \marg{begin- and end-delim macro}\syntaxfill|{|\cs{lst@BeginIComment}\cs{lst@EndIComment}|}| -% -% Most arguments should be clear. We'll discuss the last four. Both -% \marg{begin- and end-delim macro} must contain exactly two control -% sequences, which are given to |\lst@|\meta{name}[|DM|]|@|\meta{type} -% to begin and end a delimiter. These are the arguments |#3| and |#4| in our -% first example of |\lst@StringDM@l|. Depending on whether the user chosen -% type starts with \meta{extra prefix}, the first two or the last control -% sequences are used. -% -% By default the package takes the delimiter(s), makes the characters active, -% and places them after |\lst@|\meta{name}[|DM|]|@|\meta{type}. If the user -% type starts with \meta{extra prefix}, \meta{extra conversion} might change -% the definition of |\lst@next| to choose a different conversion. The default -% is equivalent to |\lst@XConvert| with |\lst@false|. -% -% Note that \meta{type} never starts with \meta{extra prefix} since it is -% discarded. The functionality must be fully implemented by choosing a -% different \marg{begin- and end-delim macro} pair. +% \item[0.21,,changed] \cs{lst@Delim} +% +% \meta{default style macro}\syntaxfill \cs{lst@commentstyle}\\ \relax +% [\texttt*[\texttt*]]\texttt[\meta{type}\texttt][\texttt[\meta{style}^^A +% \texttt][\texttt[\meta{type option}\texttt]]]\\ +% \meta{delimiter\textup(s\textup)}\cs{relax}\syntaxfill|#2|\cs{relax}\\ +% \marg{delimiter name}\syntaxfill|{Comment}|\\ +% \meta{delimiter types macro}\syntaxfill\texttt{\cs{lst@commenttypes}}\\ +% \alternative{\cs{@empty},\cs{@nil},\cs{relax}}\syntaxfill|#1|\\ +% \marg{begin- and end-delim macro}\syntaxfill|{|\cs{lst@BeginComment}^^A +% \cs{lst@EndComment}|}|\\ +% \meta{extra prefix}\syntaxfill |i|\\ +% \meta{extra conversion}\syntaxfill |\@empty|\\ +% \marg{begin- and end-delim macro}\syntaxfill|{|\cs{lst@BeginIComment}^^A +% \cs{lst@EndIComment}|}| +% +% Most arguments should be clear. We'll discuss the last four. Both +% \marg{begin- and end-delim macro} must contain exactly two control +% sequences, which are given to |\lst@|\meta{name}[|DM|]|@|\meta{type} +% to begin and end a delimiter. These are the arguments |#3| and |#4| +% in our first example of |\lst@StringDM@l|. Depending on whether the +% user chosen type starts with \meta{extra prefix}, the first two or +% the last control sequences are used. +% +% By default the package takes the delimiter(s), makes the characters +% active, and places them after +% |\lst@|\meta{name}[|DM|]|@|\meta{type}. If the user type starts with +% \meta{extra prefix}, \meta{extra conversion} might change the +% definition of |\lst@next| to choose a different conversion. The +% default is equivalent to |\lst@XConvert| with |\lst@false|. +% +% Note that \meta{type} never starts with \meta{extra prefix} since it +% is discarded. The functionality must be fully implemented by choosing +% a different \marg{begin- and end-delim macro} pair. % \end{syntax} % You might need to know the syntaxes of the \meta{begin- and end-delim macro}s. % They are called as follows. @@ -5427,119 +5603,127 @@ % \subsection{General purpose macros}\label{dGeneralPurposeMacros} % % \begin{syntax} -% \item[0.19] |\lst@AddTo|\meta{macro}\marg{\TeX~material} +% \item[0.19] |\lst@AddTo|\meta{macro}\marg{\TeX~material} % -% adds \meta{\TeX~material} globally to the contents of \meta{macro}. +% adds \meta{\TeX~material} globally to the contents of \meta{macro}. % -% \item[0.20] |\lst@Extend|\meta{macro}\marg{\TeX~material} +% \item[0.20] |\lst@Extend|\meta{macro}\marg{\TeX~material} % -% calls |\lst@AddTo| after the first token of \meta{\TeX~material} is -% |\expand|ed|after|. For example, |\lst@Extend \a \b| merges the -% contents of the two macros and stores it globally in |\a|. +% calls |\lst@AddTo| after the first token of \meta{\TeX~material} is +% |\expand|ed|after|. For example, |\lst@Extend \a \b| merges the +% contents of the two macros and stores it globally in |\a|. % -% \item[0.19] |\lst@lAddTo|\meta{macro}\marg{\TeX~material} -% \item[0.20] |\lst@lExtend|\meta{macro}\marg{\TeX~material} +% \item[0.19] |\lst@lAddTo|\meta{macro}\marg{\TeX~material} +% \item[0.20] |\lst@lExtend|\meta{macro}\marg{\TeX~material} % -% are local versions of |\lst@AddTo| and |\lst@Extend|. +% are local versions of |\lst@AddTo| and |\lst@Extend|. % -% \item[0.18] |\lst@DeleteKeysIn|\meta{macro}\meta{macro \textup(keys to remove\textup)} +% \item[0.18] |\lst@DeleteKeysIn|\meta{macro}\meta{macro \textup(keys to +% remove\textup)} % -% Both macros contain a comma separated list of keys (or keywords). All -% keys appearing in the second macro are removed (locally) from the first. +% Both macros contain a comma separated list of keys (or keywords). All +% keys appearing in the second macro are removed (locally) from the +% first. % -% \item[0.19] |\lst@ReplaceIn|\meta{macro}\meta{macro \textup(containing replacement list\textup)} -% \item[0.20] |\lst@ReplaceInArg|\meta{macro}\marg{replacement list} +% \item[0.19] |\lst@ReplaceIn|\meta{macro}\meta{macro \textup(containing +% replacement list\textup)} +% \item[0.20] |\lst@ReplaceInArg|\meta{macro}\marg{replacement list} % -% The replacement list has the form $a_1b_1$\ldots$a_nb_n$, where each -% $a_i$ and $b_i$ is a character sequence (enclosed in braces if -% necessary) and may contain macros, but the first token of $b_i$ must -% not be equivalent to |\@empty|. Each sequence $a_i$ inside the first -% macro is (locally) replaced by $b_i$. -% The suffix |Arg| refers to the \emph{braced} second argument instead of -% a (nonbraced) macro. It's a hint that we get the `real' argument and -% not a `pointer' to the argument. +% The replacement list has the form +% $a_1b_1$\ldots$a_nb_n$, where each $a_i$ and +% $b_i$ is a character sequence (enclosed in braces if necessary) and +% may contain macros, but the first token of +% $b_i$ must not be equivalent to |\@empty|. Each sequence +% $a_i$ inside the first macro is (locally) replaced by +% $b_i$. The suffix |Arg| refers to the \emph{braced} second argument +% instead of a (nonbraced) macro. It's a hint that we get the `real' +% argument and not a `pointer' to the argument. % -% \item[0.20] |\lst@IfSubstring|\marg{character sequence}\meta{macro}\marg{then}\marg{else} +% \item[0.20] |\lst@IfSubstring|\marg{character +% sequence}\meta{macro}\marg{then}\marg{else} % -% \meta{then} is executed if \meta{character sequence} is a substring of -% the contents of \meta{macro}. Otherwise \meta{else} is called. +% \meta{then} is executed if \meta{character sequence} is a substring +% of the contents of \meta{macro}. Otherwise \meta{else} is called. % -% \item[0.12] |\lst@IfOneOf|\meta{character sequence}|\relax|\meta{macro}\marg{then}\marg{else} +% \item[0.12] |\lst@IfOneOf|\meta{character +% sequence}|\relax|\meta{macro}\marg{then}\marg{else} % -% |\relax| terminates the first parameter here since it is faster than -% enclosing it in braces. \meta{macro} contains a comma separated list -% of identifiers. If the character sequence is one of these indentifiers, -% \meta{then} is executed, and otherwise \meta{else}. +% |\relax| terminates the first parameter here since it is faster than +% enclosing it in braces. \meta{macro} contains a comma separated list +% of identifiers. If the character sequence is one of these +% indentifiers, \meta{then} is executed, and otherwise \meta{else}. % -% \item[0.21] |\lst@Swap|\marg{tok1}\marg{tok2} +% \item[0.21] |\lst@Swap|\marg{tok1}\marg{tok2} % -% changes places of the following two tokens or arguments \emph{without} -% inserting braces. For example, |\lst@Swap{abc}{def}| expands to -% |defabc|. +% changes places of the following two tokens or arguments +% \emph{without} inserting braces. For example, |\lst@Swap{abc}{def}| +% expands to |defabc|. % -% \item[0.18] |\lst@IfNextChars|\meta{macro}\marg{then}\marg{else} -% \item[0.19] |\lst@IfNextCharsArg|\marg{character sequence}\marg{then}\marg{else} +% \item[0.18] |\lst@IfNextChars|\meta{macro}\marg{then}\marg{else} +% \item[0.19] |\lst@IfNextCharsArg|\marg{character +% sequence}\marg{then}\marg{else} % -% Both macros execute either \meta{then} or \meta{else} according to -% whether the given character sequence respectively the contents of the -% given macro is found (after the three arguments). Note an important -% difference between these macros and \LaTeX's |\@ifnextchar|: -% We remove the characters behind the arguments until it is possible to -% decide which part must be executed. However, we save these characters -% in the macro |\lst@eaten|, so they can be inserted using \meta{then} or -% \meta{else}. +% Both macros execute either \meta{then} or \meta{else} according to +% whether the given character sequence respectively the contents of the +% given macro is found (after the three arguments). Note an important +% difference between these macros and \LaTeX's |\@ifnextchar|: We +% remove the characters behind the arguments until it is possible to +% decide which part must be executed. However, we save these characters +% in the macro |\lst@eaten|, so they can be inserted using \meta{then} +% or \meta{else}. % -% \item[0.19] |\lst@IfNextCharActive|\marg{then}\marg{else} +% \item[0.19] |\lst@IfNextCharActive|\marg{then}\marg{else} % -% executes \meta{then} if next character is active, and \meta{else} -% otherwise. +% executes \meta{then} if next character is active, and \meta{else} +% otherwise. % -% \item[0.20] |\lst@DefActive|\meta{macro}\marg{character sequence} +% \item[0.20] |\lst@DefActive|\meta{macro}\marg{character sequence} % -% stores the character sequence in \meta{macro}, but all characters -% become active. The string \emph{must not} contain a begin group, end -% group or escape character (|{}\|); it may contain a left brace, right -% brace or backslash with other meaning (= catcode). This command -% would be quite surplus if \meta{character sequence} is not already read -% by \TeX\ since such catcodes can be changed easily. It is explicitly -% allowed that the charcaters have been read, e.g.~in -% |\def\test{\lst@DefActive\temp{ABC}}|! +% stores the character sequence in \meta{macro}, but all characters +% become active. The string \emph{must not} contain a begin group, end +% group or escape character (|{}\|); it may contain a left brace, right +% brace or backslash with other meaning (= catcode). This command would +% be quite surplus if \meta{character sequence} is not already read by +% \TeX\ since such catcodes can be changed easily. It is explicitly +% allowed that the charcaters have been read, e.g.~in +% |\def\test{\lst@DefActive\temp{ABC}}|! % -% Note that this macro changes |\lccode|s 0--9 without restoring them. +% Note that this macro changes |\lccode|s 0--9 without restoring them. % -% \item[0.20] |\lst@DefOther|\meta{macro}\marg{character sequence} +% \item[0.20] |\lst@DefOther|\meta{macro}\marg{character sequence} % -% stores \meta{character sequence} in \meta{macro}, but all characters -% have catcode 12. Moreover all spaces are removed and control sequences -% are converted to their name without preceding backslash. For example, -% |\{ Chip \}| leads to |{Chip}| where all catcodes are 12---internally -% the primitive |\meaning| is used. +% stores \meta{character sequence} in \meta{macro}, but all characters +% have catcode 12. Moreover all spaces are removed and control +% sequences are converted to their name without preceding +% backslash. For example, |\{ Chip \}| leads to |{Chip}| where all +% catcodes are 12---internally the primitive |\meaning| is used. % -% \iffalse -% \item[0.19] |\lst@MakeActive|\marg{character sequence} +% \iffalse +% \item[0.19] |\lst@MakeActive|\marg{character sequence} % -% stores the character sequence in |\lst@arg| and has the same -% restrictions as |\lst@DefActive|. If fact, the latter definition uses -% this macro here. -% \fi +% stores the character sequence in |\lst@arg| and has the same +% restrictions as |\lst@DefActive|. If fact, the latter definition uses +% this macro here. \fi % \end{syntax} % % % \subsection{Character tables manipulated}\label{dCharacterTablesManipulated} % % \begin{syntax} -% \item[0.20] |\lst@SaveDef|\marg{character code}\meta{macro} +% \item[0.20] |\lst@SaveDef|\marg{character code}\meta{macro} % -% Saves the current definition of the specified character in -% \meta{macro}. You should always save a character definition before you -% redefine it! And use the saved version instead of writing directly -% |\lst@Process|\ldots---the character could already be redefined and -% thus not equivalent to its standard definition. +% Saves the current definition of the specified character in +% \meta{macro}. You should always save a character definition before +% you redefine it! And use the saved version instead of writing +% directly |\lst@Process|\ldots---the character could already be +% redefined and thus not equivalent to its standard definition. % -% \item[0.20] |\lst@DefSaveDef|\marg{character code}\meta{macro}\meta{parameter text}\marg{definition} -% \item[0.20] |\lst@LetSaveDef|\marg{character code}\meta{macro}\meta{token} +% \item[0.20] |\lst@DefSaveDef|\marg{character +% code}\meta{macro}\meta{parameter text}\marg{definition} +% \item[0.20] |\lst@LetSaveDef|\marg{character +% code}\meta{macro}\meta{token} % -% combine |\lst@SaveDef| and |\lst@Def| respectively |\lst@Let|. +% combine |\lst@SaveDef| and |\lst@Def| respectively |\lst@Let|. % \end{syntax} % Of course I shouldn't forget to mention \emph{where} to alter the character % table. Hook material at \hookname{SelectCharTable} makes permanent changes, @@ -5579,37 +5763,40 @@ % counter by one. % % \begin{syntax} -% \item[0.21] |\lst@CArg|\meta{active characters}|\relax|\meta{macro} +% \item[0.21] |\lst@CArg|\meta{active characters}|\relax|\meta{macro} % -% The string of active characters is split into \meta{1st}, \meta{2nd}, -% and \marg{rest}. If one doesn't exist, an empty argument is used. Then -% \meta{macro} is called with |{|\meta{1st}\meta{2nd}\marg{rest}|}| plus -% a yet undefined control sequence \meta{save 1st}. This macro is -% intended to hold the current definition of \meta{1st}, so \meta{1st} -% can be redefined without loosing information. +% The string of active characters is split into \meta{1st}, \meta{2nd}, +% and \marg{rest}. If one doesn't exist, an empty argument is +% used. Then \meta{macro} is called with +% |{|\meta{1st}\meta{2nd}\marg{rest}|}| plus a yet undefined control +% sequence \meta{save 1st}. This macro is intended to hold the current +% definition of \meta{1st}, so \meta{1st} can be redefined without +% loosing information. % -% \item[0.19] |\lst@CArgX|\meta{characters}|\relax|\meta{macro} +% \item[0.19] |\lst@CArgX|\meta{characters}|\relax|\meta{macro} % -% makes \meta{characters} active before calling |\lst@CArg|. +% makes \meta{characters} active before calling |\lst@CArg|. % -% \item[0.21] |\lst@CDef{|\meta{1st}\meta{2nd}\marg{rest}|}|\meta{save 1st}\marg{execute}\marg{pre}\marg{post} +% \item[0.21] |\lst@CDef{|\meta{1st}\meta{2nd}\marg{rest}|}|\meta{save +% 1st}\marg{execute}\marg{pre}\marg{post} % -% should be used in connection with |\lst@CArg| or |\lst@CArgX|, i.e.~as -% \meta{macro} there. \meta{1st}, \meta{2nd}, and \meta{rest} must be -% active characters and \meta{save 1st} must be an undefined control -% sequence. +% should be used in connection with |\lst@CArg| or |\lst@CArgX|, +% i.e.~as \meta{macro} there. \meta{1st}, \meta{2nd}, and \meta{rest} +% must be active characters and \meta{save 1st} must be an undefined +% control sequence. % -% Whenever the package reaches the character \meta{1st} (in a listing), -% \meta{execute} is executed. If the package detects the whole string -% \meta{1st}\meta{2nd}\meta{rest}, we additionally execute \meta{pre}, -% then the string, and finally \meta{post}. +% Whenever the package reaches the character \meta{1st} (in a listing), +% \meta{execute} is executed. If the package detects the whole string +% \meta{1st}\meta{2nd}\meta{rest}, we additionally execute \meta{pre}, +% then the string, and finally \meta{post}. % -% \item[0.21] |\lst@CDefX|\meta{1st}\meta{2nd}\marg{rest}\meta{save 1st}\marg{execute}\marg{pre}\marg{post} +% \item[0.21] |\lst@CDefX|\meta{1st}\meta{2nd}\marg{rest}\meta{save +% 1st}\marg{execute}\marg{pre}\marg{post} % -% Ditto except that we execute \meta{pre} and \meta{post} without the -% original string if we reach \meta{1st}\meta{2nd}\meta{rest}. -% This means that the string is replaced by \meta{pre}\meta{post} (with -% preceding \meta{execute}). +% Ditto except that we execute \meta{pre} and \meta{post} without the +% original string if we reach \meta{1st}\meta{2nd}\meta{rest}. This +% means that the string is replaced by \meta{pre}\meta{post} (with +% preceding \meta{execute}). % \end{syntax} % As the final example, here's the definition of |\lst@DefDelimB|. % \begin{verbatim} @@ -5629,7 +5816,7 @@ % \part{Implementation} % % -% \CheckSum{12368} +% \CheckSum{12377} %^^A %^^A Don't index TeX-primitives. %^^A @@ -5773,8 +5960,8 @@ % All files will have same date and version. % \begin{macrocode} %<*kernel|misc|doc> -\def\filedate{2018/09/02} -\def\fileversion{1.7} +\def\filedate{2019/02/27} +\def\fileversion{1.8b} %</kernel|misc|doc> % \end{macrocode} % What we need and who we are. @@ -5964,7 +6151,8 @@ % % \subsection{Substring tests}\label{iSubstringTests} % -% \lstset{language=TeX,gobble=4,xleftmargin=20pt,columns=[l]fullflexible,mathescape,keywordstyle=\ttfamily,texcsstyle=\bfseries} +% \lstset{language=TeX,gobble=4,xleftmargin=20pt,columns=[l]fullflexible,^^A +% mathescape,keywordstyle=\ttfamily,texcsstyle=\bfseries} % \let\texverb\lstinline % \lstnewenvironment{texcode}[1][]{\lstset{#1}}{} % \lstset{keywords={def,key}} @@ -6531,41 +6719,42 @@ % All these files can be loaded partially and on demand---except the kernel % which provides this functionality. % \begin{syntax} -% \item[0.21] |\lst@Require|\marg{name}\marg{prefix}\marg{feature list}\meta{alias}\meta{file list macro} +% \item[0.21] |\lst@Require|\marg{name}\marg{prefix}\marg{feature +% list}\meta{alias}\meta{file list macro} % -% tries to load all items of \meta{feature list} from the files -% listed in \meta{file list macro}. -% Each item has the form [\oarg{sub}]\meta{feature}. -% |\lst@if| equals |\iftrue| if and only if all items were loadable. +% tries to load all items of \meta{feature list} from the files listed +% in \meta{file list macro}. Each item has the form +% [\oarg{sub}]\meta{feature}. |\lst@if| equals |\iftrue| if and only +% if all items were loadable. % -% The macro \meta{alias} gets an item as argument and must define -% appropriate versions of |\lst@oalias| and |\lst@malias|. In fact -% the feature associated with these definitions is loaded. You can -% use \meta{alias}=|\lst@NoAlias| for no substitution. +% The macro \meta{alias} gets an item as argument and must define +% appropriate versions of |\lst@oalias| and |\lst@malias|. In fact the +% feature associated with these definitions is loaded. You can use +% \meta{alias}=|\lst@NoAlias| for no substitution. % -% \meta{prefix} identifies the type internally and \meta{name} is used -% for messages. +% \meta{prefix} identifies the type internally and \meta{name} is used +% for messages. % -% For example, |\lstloadaspects| uses the following arguments where |#1| -% is the list of aspects: |{aspects}|\allowbreak|a|\allowbreak -% |{#1}|\allowbreak|\lst@NoAlias|\allowbreak|\lstaspectfiles|. +% For example, |\lstloadaspects| uses the following arguments where +% |#1| is the list of aspects: |{aspects}|\allowbreak|a|\allowbreak +% |{#1}|\allowbreak|\lst@NoAlias|\allowbreak|\lstaspectfiles|. % -% \item[0.20] |\lst@DefDriver|\marg{name}\marg{prefix}\meta{interface macro}|\if|\alternative{true,false} +% \item[0.20] |\lst@DefDriver|\marg{name}\marg{prefix}\meta{interface +% macro}|\if|\alternative{true,false} % +% \item[0.21] +% |\lst@IfRequired|\oarg{sub}\marg{feature}\marg{then}\marg{else} % +% is used inside a driver file by the aspect, language, or whatever +% else defining commands. \meta{then} is executed if and only if +% \oarg{sub}\marg{feature} has been requested via |\lst@Require|. +% Otherwise \meta{else} is executed---which is also the case for +% subsequent calls with the same \oarg{sub}\marg{feature}. % -% \item[0.21] |\lst@IfRequired|\oarg{sub}\marg{feature}\marg{then}\marg{else} +% \meta{then} and \meta{else} may use |\lst@prefix| (read access only). % -% is used inside a driver file by the aspect, language, or whatever -% else defining commands. \meta{then} is executed if and only if -% \oarg{sub}\marg{feature} has been requested via |\lst@Require|. -% Otherwise \meta{else} is executed---which is also the case for -% subsequent calls with the same \oarg{sub}\marg{feature}. -% -% \meta{then} and \meta{else} may use |\lst@prefix| (read access only). -% -% |\lst@BeginAspect| in section \ref{iAspectCommands} and |\lst@DefDriver| -% serve as examples. +% |\lst@BeginAspect| in section \ref{iAspectCommands} and +% |\lst@DefDriver| serve as examples. % \end{syntax} % % \begin{macro}{\lst@Require} @@ -8410,19 +8599,23 @@ % where the first A is active and the second has catcode 12. We use the % following macros to build the character table. % \begin{syntax} -% \item[0.19] |\lst@CCPut|\meta{class macro}\meta{$c_1$}\ldots\meta{$c_k$}|\z@| -% -% extends the standard character table by the characters with codes -% \meta{$c_1$}\ldots\meta{$c_k$} making each character use -% \meta{class macro}. All these characters must be printable via -% |\char|\meta{$c_i$}. -% -% \item[0.20] |\lst@CCPutMacro|\meta{class$_1$}\meta{$c_1$}\meta{definition$_1$}\ldots|\@empty\z@\@empty| -% -% also extends the standard character table: the character \meta{$c_i$} -% will use \meta{class$_i$} and is printed via \meta{definition$_i$}. -% These definitions must be \meta{spec. token}s in the sense of section -% \ref{dCharacterTables}. +% \item[0.19] |\lst@CCPut|\meta{class +% macro}\meta{$c_1$}\ldots\meta{$c_k$}|\z@| +% +% extends the standard character table by the characters with codes +% \meta{$c_1$}\ldots\meta{$c_k$} making each character use \meta{class +% macro}. All these characters must be printable via +% |\char|\meta{$c_i$}. +% +% \item[0.20] +% |\lst@CCPutMacro|\meta{class$_1$}\meta{$c_1$}\meta{definition$_1$}^^A +% \ldots|\@empty\z@\@empty| +% +% also extends the standard character table: the character +% \meta{$c_i$} will use +% \meta{class$_i$} and is printed via +% \meta{definition$_i$}. These definitions must be \meta{spec. token}s +% in the sense of section \ref{dCharacterTables}. % \end{syntax} % % \begin{macro}{\lst@Def} @@ -12411,7 +12604,8 @@ % \lsthelper{Ivo~Pletikosi\'c}{2015/08/18}{listings + hyperref, lstmisc.sty} % reported another problem with the redefinition of |\thelstlisting|. % \lsthelper{Heiko~Oberdiek}{2001/11/08}% -% {http://tex.stackexchange.com/questions/261437/renewing-the-thelstlisting-command-when-hyperref-is-on} +% {http://tex.stackexchange.com/questions/261437/renewing-the-thelstlisting^^A +% -command-when-hyperref-is-on} % again provided a fix: |\thelstlisting| must be replaced by |\theHlstlisting|. % \begin{macrocode} \AtBeginDocument{% @@ -14659,16 +14853,30 @@ \def\lstinputlisting{% \begingroup \lst@setcatcodes \lst@inputlisting} \newcommand\lst@inputlisting[2][]{% - \endgroup - \def\lst@set{#1}% - \IfFileExists{\lst@inputpath#2}% - {\expandafter\lst@InputListing\expandafter{\lst@inputpath#2}}% - {\filename@parse{\lst@inputpath#2}% - \edef\reserved@a{\noexpand\lst@MissingFileError - {\filename@area\filename@base}% - {\ifx\filename@ext\relax tex\else\filename@ext\fi}}% - \reserved@a}% - \lst@doendpe \@newlistfalse \ignorespaces} + \endgroup +% \end{macrocode} +% |\lst@set| takes the local options, especially |inputpath=<path>| for +% formatting the input file. So |\lstset| must be updated to have the right +% value of |\lst@inputpath|. The whole procedure must be grouped to make +% the change local. +% \begin{macrocode} + \bgroup\def\lst@set{#1}% + \expandafter\lstset\expandafter{\lst@set}% + \IfFileExists{\lst@inputpath#2}% + {\lst@InputListing{\lst@inputpath#2}}% + {\filename@parse{\lst@inputpath#2}% + \edef\reserved@a{\noexpand\lst@MissingFileError + {\filename@area\filename@base}% + {\ifx\filename@ext\relax tex\else\filename@ext\fi}}% + \reserved@a +% \end{macrocode} +% We must provide a valid value for |\lst@doendpe| in the (error) case that there +% exists no file. +% \begin{macrocode} + \let\lst@doendpe\@empty}% + \egroup + \lst@doendpe \@newlistfalse \ignorespaces% +} % \end{macrocode} % We use |\lst@doendpe| to remove indention at the beginning of the next % line---except there is an empty line after |\lstinputlisting|. Bug was @@ -14922,7 +15130,7 @@ {\PackageError{Listings}{Environment `#1' already defined}\@eha \@gobbletwo}} \def\@tempa#1#2#3{% -\gdef\lstnewenvironment@##1##2##3##4##5{% + \gdef\lstnewenvironment@##1##2##3##4##5{% \begingroup % \end{macrocode} % A lonely `end environment' produces an error. @@ -15065,23 +15273,27 @@ % the user has given the name argument, set the keys, and deal with % continued line numbering. % \begin{macrocode} -\lstnewenvironment{lstlisting}[2][] - {% -% \end{macrocode} -% There is a problem with vertical space as pointed out by -% \lsthelper{Jean-Yves~Baudais}{2016/03/11}{some vertical space -% problem}. A similar problem arises with a listing beginning at -% the top of a |\paragraph| or at the beginning of an |example| -% environment. Jean-Yves provided a solution---|\let\if@nobreak\iffalse|---as has -% been discussed on |fr.comp.text.tex|. The problem vanishes also if there -% is a top rule at the beginning of the listing or if |leavevmode| -% introduces the listing, so -% \begin{macrocode} - \leavevmode% +\lstnewenvironment{lstlisting}[2][]{% \lst@TestEOLChar{#2}% \lstset{#1}% - \csname\@lst @SetFirstNumber\endcsname} - {\csname\@lst @SaveFirstNumber\endcsname} + \csname\@lst @SetFirstNumber\endcsname% + }{% +% \end{macrocode} +% There is a problem with vertical space below a listing as pointed out by +% \lsthelper{Jean-Yves~Baudais}{2016/03/11}{some vertical space problem}. A +% similar problem arises with a listing beginning at the top of a +% |\paragraph| or at the beginning of an |example| environment. Jean-Yves +% provided a solution---|\let\if@nobreak\iffalse|---as has been discussed +% on |fr.comp.text.tex|. The assumption, that the problem vanishes if there +% is a top rule at the beginning of the listing or if |\leavevmode| +% introduces the listing, was wrong as \lsthelper{Karl +% Berry}{karl@freefriends.org}{2018/10/26} and \lsthelper{Sven +% Schreiber}{svetosch@gmx.net}{2018/10/23} reported independently, so the +% proposed code goes into the second part of the environment definition +% \begin{macrocode} + \let\if@nobreak\iffalse% + \csname\@lst @SaveFirstNumber\endcsname% + } % \end{macrocode} % \begin{macrocode} %</kernel> |