diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/listings/listings.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/listings/listings.dtx | 187 |
1 files changed, 145 insertions, 42 deletions
diff --git a/Master/texmf-dist/source/latex/listings/listings.dtx b/Master/texmf-dist/source/latex/listings/listings.dtx index 4c715bef717..5b897a2968a 100644 --- a/Master/texmf-dist/source/latex/listings/listings.dtx +++ b/Master/texmf-dist/source/latex/listings/listings.dtx @@ -13,7 +13,7 @@ % or simply `the package'. lstdrvrs.dtx and the files generated from % that file are `drivers'. % -% The listings package is copyright 1996--2004 Carsten Heinz, and +% The listings package is copyright 1996--2004 Carsten Heinz, and % continued maintenance on the package is copyright 2006--2007 Brooks % Moses. From 2013 on copyright is Jobst Hoffmann, who is the maintainer % since july 2013. The drivers are copyright 1997/1998/1999/2000/2001/ @@ -30,7 +30,7 @@ % % The package has the LPPL maintenance status "maintained". % -% $Id: listings.dtx 149 2014-09-06 17:17:38Z j_hoffmann $ +% $Id: listings.dtx 201 2015-06-04 20:25:39Z j_hoffmann $ % % The Current Maintainer is Jobst Hoffmann <j.hoffmann(at)fh-aachen.de>. % @@ -43,6 +43,10 @@ \OnlyDescription \usepackage{lstdoc,textcomp} +\usepackage{mdframed} % frames for external files +\usepackage{moreverb} % writing external files +\usepackage{xcolor} % because of colouring the background + \makeindex \begin{document} @@ -115,7 +119,7 @@ % Hoffmann became the maintainer of the \packagename{listings} % package in 2013; see the Preface for details.}~ % % \textless\lstemail\textgreater} -% \date{2014/09/06\enspace\enspace Version 1.5e\ \box\abstractbox} +% \date{2015/06/04\enspace\enspace Version 1.6\ \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>} @@ -131,7 +135,7 @@ % \section*{Preface} % % \paragraph{Transition of package maintenance} -% The \TeX\ world lost contact with Carsten Heinz in late 2004, shortly after +% The \TeX\ world lost contact with Carsten Heinz in late 2004, shortly after % he released version 1.3b of the \packagename{listings} package. After many % attempts to reach him had failed, Hendri Adriaens took over maintenance of % the package in accordance with the LPPL's procedure for abandoned packages. @@ -139,7 +143,7 @@ % volunteered for the position while this procedure was going through. The % result is known as listings version 1.4. % -% This release, version 1.5, is a minor maintenance release since +% This release, version 1.5, is a minor maintenance release since % I accepted maintainership of the package. I would like to thank Stephan % Hennig who supported the Lua language definitions. He is the one who % asked for the integration of a new language and gave the impetus to me to @@ -203,7 +207,7 @@ % applies, you should spend more time on reading (good) books about % programming, (good) documentations, and (good) source code from other % people. Of course you should also make your own experiments. -% You will learn a lot. However, running the example through \LaTeX\ +% You will learn a lot. However, running the example through \LaTeX\ % shows whether the \packagename{listings} package is installed correctly. % \item The example doesn't work. % \advisespace @@ -993,7 +997,7 @@ % If you type in such characters directly as characters of codes 128--255 and % use them also in listings, let the package know it---or you'll get really % funny results. {\rstyle\ikeyname{extendedchars}}|=true| allows and -% |extendedchars=false| prohibits \packagename{listings} from handling +% |extendedchars=false| prohibits \packagename{listings} from handling % extended characters in listings. If you use them, you should load % \packagename{fontenc}, \packagename{inputenc} and/or % any other package which defines the characters. @@ -1008,7 +1012,7 @@ % on---specifically, any encoding which uses multiple bytes per character. % % Thus, if you use the a package that supports multibyte characters, such as -% the \packagename{CJK} or \packagename {ucs} packages for Chinese and +% the \packagename{CJK} or \packagename {ucs} packages for Chinese and % UTF-8 characters, you must avoid letting \packagename{listings} % process the extended characters. It is generally best to also specify % |extendedchars=false| to avoid having \packagename{listings} get entangled @@ -1123,7 +1127,7 @@ % For example, begin with `|framerule=10mm|'. If the rules are % misaligned by the same (small) amount as before, the problem does not % come from the rule width. So continue with the next parameter. Also, -% Adobe Acrobat sometimes has single-pixel rounding errors which can +% Adobe Acrobat sometimes has single-pixel rounding errors which can % cause small misalignments at the corners when PDF files are displayed % on screen; these are unfortunately normal. % \end{advise} @@ -1387,7 +1391,7 @@ % listings inside paragraphs, but you must force the package to do this by % enclosing the listing in |\hbox{| and |}|. % \begin{advise} -% \item Is it good form to use the \TeX-primitive `|\hbox|' in a \LaTeX\ +% \item Is it good form to use the \TeX-primitive `|\hbox|' in a \LaTeX\ % document? % \advisespace % No, it's not. But \LaTeX's `|\mbox|' does not work in this example: @@ -1535,8 +1539,8 @@ % and space-flexible formats try to fix the column alignment if a character % string needs less space than `reserved'. The normal flexible format will % insert make-up space to fix the alignment at spaces, before and after -% identifiers, and before and after sequences of other characters; the -% space-flexible format will only insert make-up space by stretching +% identifiers, and before and after sequences of other characters; the +% space-flexible format will only insert make-up space by stretching % existing spaces. In the flexible example above, the two MENs are vertically % aligned since some space has been inserted in the fourth line to fix the % alignment. In the full flexible format, the two MENs are not aligned. @@ -2127,7 +2131,12 @@ % 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}. +% 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{uListingsArguments} for a +% workaround. % % See also section \ref{rShortInline} for commands to create short analogs % for the |\lstinline| command. @@ -2487,7 +2496,7 @@ % \item[0.16,1] \rkeyname{stepnumber}|=|\meta{number} % % All lines with ``line number $\equiv 0$ modulo \meta{number}'' get a -% line number. +% 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 @@ -3675,7 +3684,7 @@ % interface, a powerful `format definition' parser, and lots of code lines % behind the scenes. Currently, format definitions aren't flexible enough % (possibly not the definitions but the results). A single `format item' has -% the form +% the form % \begin{itemize}\item[] % \meta{input chars}|=|\oarg{exceptional chars}\meta{pre}\oarg{\texttt{\string\string}}\meta{post} % \end{itemize} @@ -3900,6 +3909,68 @@ % \end{enumerate} % % +% \section{Bugs and workarounds}\label{uBugsWorkarounds} +% +% \subsection{Listings inside arguments}\label{uListingsArguments} +% +% At the moment it isn't possible to use \verb-\lstinline{...}- in a cell +% of a table\makeatletter\@ifundefined{r@uProcessingInline}{}{% +% (see section \ref{uProcessingInline} on page \pageref{uProcessingInline} +% for more information)},% +% \makeatother% +% but it is possible to define a wrapper macro +% which can be used instead of \verb-\lstinline{...}-: +% \begin{lstsample}[lstlisting]{}{} +% \newcommand\foo{\lstinline{t}} +% \newcommand\foobar[2][]{\lstinline[#1]{#2}} +% +% \begin{tabular}{ll} +% \foo & a variable\\ +% \foobar[language=java]{int u;} & a declaration +% \end{tabular} +% \end{lstsample} +% +% +% \subsection{Listings with a background colour and \LaTeX{} escaped +% formulas} +% \label{uListingsBackgroundColour} +% +% If there is any text escaped to \LaTeX{} with some coloured background +% and surrounding frames, then there are gaps in the background as well as +% in the lines making up the frame. +% \begin{lstsample}[lstlisting]{}{} +% \begin{lstlisting}[language=C, mathescape, +% backgroundcolor=\color{yellow!10}, frame=tlb] +% /* the following code computes $\displaystyle\sum_{i=1}^{n}i$ */ +% for (i = 1; i <= limit; i++) { +% sum += i; +% } +% \end{lstlisting} +% \end{lstsample} +% +% At the moment there is only one workaround: +% \begin{itemize} +% \item Write your code into an external file \meta{filename}. +% \item Input your code by |\lstinputlisting|\meta{filename} into your +% document and surround it with a frame generated by |\begin{mdframed}| +% \ldots{} |\end{mdframed}|. +% \end{itemize} +% \begin{lstsample}[lstlisting]{}{} +% \begin{verbatimwrite}{temp.c} +% /* the following code computes $\displaystyle\sum_{i=1}^{n}i$ */ +% for (i = 1; i <= limit; i++) { +% sum += i; +% } +% \end{verbatimwrite} +% \begin{mdframed}[backgroundcolor=yellow!10, rightline=false] +% \lstinputlisting[language=C,mathescape,frame={}]{./temp.c} +% \end{mdframed} +% \end{lstsample} +% For more information about the |verbatimwrite| environment have a look at +% \cite{Fairbairns:moreverb}, the |mdframed| environment is deeply discussed in +% \cite{DanielSchubert:mdframed}. +% +% % \section{How tos}\label{uHowTos} % % @@ -4030,7 +4101,7 @@ % \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}. +% feature described in section \ref{rEscapingToLaTeX}. % The keys \ikeyname{escapechar}, \ikeyname{escapeinside}, and \ikeyname{texcl} % allow partial usage of \LaTeX\ code. % @@ -4072,7 +4143,7 @@ % % \subsubsection*{How to get bold typewriter type keywords} % Use the \href{http://www.ctan.org/tex-archive/fonts/luximono}{\packagename{LuxiMono}} package. -% +% % \iffalse % Many people asked for bold typewriter fonts since they aren't included in % the \LaTeX\ standard distribution. Here now one answer on how to use them @@ -4140,7 +4211,18 @@ % \def\index@prologue{\part{Index}\markboth{Index}{Index}} % \makeatother %^^A \StopEventually{\lstcheckreference\setcounter{IndexColumns}{2}\PrintIndex} -% \StopEventually{\setcounter{IndexColumns}{2}\PrintIndex} +% \StopEventually{% +% \begin{thebibliography}{MDB01} +% +% \bibitem[Fai11]{Fairbairns:moreverb} +% Robin Fairbairns. +% \newblock{The \textsf{moreverb} package}, 2011. +% +% \bibitem[DS13]{DanielSchubert:mdframed} +% Marco Daniel and Elke Schubert. +% \newblock{The \textsf{mdframed} package}, 2013. +% \end{thebibliography} +% \setcounter{IndexColumns}{2}\PrintIndex} % % % \part{Developer's guide} @@ -5165,7 +5247,7 @@ % three characters. All characters of \meta{1st}\meta{2nd}\meta{rest} % must already be active (if not empty). % That's not a problem since the macro |\lst@CArgX| does this job. -% +% % \item[1.0] \cs{lst@DefDelimE} % % |{|\meta{1st}\meta{2nd}\marg{rest}|}|\\ @@ -5534,7 +5616,7 @@ % \part{Implementation} % % -% \CheckSum{12367} +% \CheckSum{12365} %^^A %^^A Don't index TeX-primitives. %^^A @@ -5675,8 +5757,8 @@ % \paragraph{Identification} % All files will have same date and version. % \begin{macrocode} -\def\filedate{2014/09/06} -\def\fileversion{1.5e} +\def\filedate{2015/06/04} +\def\fileversion{1.6} % \end{macrocode} % What we need and who we are. % \begin{macrocode} @@ -6142,7 +6224,7 @@ % % \begin{macro}{\lst@for} % A for-loop with expansion of the loop-variable. This was improved due to -% a suggestion by \lsthelper{Hendri~Adriaens}{2006/03/31}{speedup of +% a suggestion by \lsthelper{Hendri~Adriaens}{2006/03/31}{speedup of % \lst@for}. % \begin{macrocode} \def\lst@for#1\do#2{% @@ -6160,7 +6242,7 @@ % % \subsection{Catcode changes}\label{iCatcodeChanges} % -% A character gets its catcode right after reading it and \TeX\ has no +% A character gets its catcode right after reading it and \TeX\ has no % primitive command to change attached catcodes. However, we can replace these % characters by characters with same ASCII codes and different catcodes. % It's not the same but suffices since the result is the same. @@ -6453,7 +6535,7 @@ % % \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} % @@ -7268,7 +7350,7 @@ % \end{macro} % % \begin{macro}{\lst@CalcColumn} -% sets |\@tempcnta| to the current column. +% sets |\@tempcnta| to the current column. % Note that |\lst@pos| will be nonpositive. % \begin{macrocode} \def\lst@CalcColumn{% @@ -7610,7 +7692,7 @@ \lst@UseLostSpace \fi \else - \lst@ifnewline \lst@UseLostSpace\fi + \lst@ifnewline \lst@UseLostSpace\fi \fi}% \let\lst@leftinsert\@empty \let\lst@rightinsert\@empty} @@ -7621,7 +7703,7 @@ % % \begin{macro}{\lst@outputpos} % This macro sets the `output-box-positioning' parameter (the old key -% \keyname{outputpos}). We test for |l|, |c| and |r|. +% \keyname{outputpos}). We test for |l|, |c| and |r|. % The fixed formats use |\lst@lefthss| and |\lst@righthss|, whereas the % flexibles need |\lst@leftinsert| and |\lst@rightinsert|. % \begin{macrocode} @@ -8305,7 +8387,7 @@ % \subsubsection{The standard table} % % The standard character table is selected by |\lst@SelectStdCharTable|, which -% expands to a token sequence +% expands to a token sequence % \ldots|\def| |A{\lst@ProcessLetter| |A}|\ldots\space % where the first A is active and the second has catcode 12. We use the % following macros to build the character table. @@ -9316,7 +9398,7 @@ \expandafter\lst@next \fi} % \end{macrocode} -% Then we can check whether (the following) |\lst@|\meta{delimiter name}\ldots\ +% Then we can check whether (the following) |\lst@|\meta{delimiter name}\ldots\ % matches the delimiter class given by |\lst@delim|. % \begin{macrocode} \def\lst@Delim@delall@do#1#2\@empty#3#4#5{% @@ -10202,7 +10284,7 @@ % fourth right before ending it. We use the same mechanism as for \TeX\ comment % lines. The |\lst@ifdropinput| test has been added after a bug report by % \lsthelper{Michael~Weber}{2002/03/26}{escape on lines < firstline corrupts -% output}. The |\lst@newlines\z@| was added due to a bug report by +% output}. The |\lst@newlines\z@| was added due to a bug report by % \lsthelper{Frank~Atanassow}{2004/10/07}{space after mathescape is not % preserved}. % \begin{macrocode} @@ -11210,7 +11292,7 @@ % \end{macrocode} % To make the backslash belong to the control sequence, it is merged with % the following token. This option was suggested by \lsthelper{Morten~H\o gholm} -% {2004/07/16}{defining new (colored) texcs}. +% {2004/07/16}{defining new (colored) texcs}. % \lsthelper{Christian~Schneider}{-}{2006/09/08} pointed out that the original % implementation was broken when the identifier was preceded by an ``other'' % character. To fix this (and other bugs), we first output whatever is in the @@ -12502,7 +12584,7 @@ % \begin{macrocode} \lst@AddToHook{Init} {\lst@ifbreaklines - \hbadness\@M \pretolerance\@M + \hbadness\@M \pretolerance\@M \@rightskip\@flushglue \rightskip\@rightskip % \raggedright \leftskip\z@skip \parindent\z@ % \end{macrocode} @@ -13228,7 +13310,7 @@ % \begin{macro}{\lst@MakeSCT} % If `macro use' is on, the opening |$(| prints preceding characters, enters % the special mode and merges the two characters with the following output. -% +% % \begin{macrocode} \gdef\lst@MakeSCT{% \lst@ifmakemacrouse @@ -13303,7 +13385,7 @@ % from the |lstpatch.sty| file that Carsten left in version 1.3b for doing % line ranges with numbers and range markers. % -% First, the options that control the line-range handling. +% First, the options that control the line-range handling. % \begin{macrocode} \lst@Key{linerange}\relax{\lstKV@OptArg[]{#1}{% \def\lst@interrange{##1}\def\lst@linerange{##2,}}} @@ -14194,7 +14276,7 @@ % \end{macrocode} % For KOMA-script classes, we define it a la KOMA thanks to a bug report by % \lsthelper{Tino~Langer}{2003/11/01}{koma-script's listsleft option does not -% affect lol}. \lsthelper{Markus~Kohm}{2006/08/12}{koma-script support is +% affect lol}. \lsthelper{Markus~Kohm}{2006/08/12}{koma-script support is % broken} suggested a much-improved version of this, which also works with % the \packagename{float} package. The following few comments are from Markus. % @@ -14243,7 +14325,7 @@ % for the suggestion. % % Unfortunately, \packagename{float} defines this with |\newcommand|; thus, -% to avoid conflict, we have to redefine it after \packagename{float} is +% to avoid conflict, we have to redefine it after \packagename{float} is % loaded. |\AtBeginDocument| is the easiest way to do this. Again, thanks % to Markus for the advice. % \begin{macrocode} @@ -14261,7 +14343,7 @@ % % \subsection{Inline listings}\label{iInlineListings} % -% \subsubsection{Processing inline listings} +% \subsubsection{Processing inline listings}\label{uProcessingInline} % % \begin{macro}{\lstinline} % In addition to |\lsthk@PreSet|, we use |boxpos=b| and flexiblecolumns. @@ -14285,10 +14367,31 @@ % braces instead of characters surrounding the source code resulted in an % error if used in a tabular environment. He found that this error comes % from the master counter (cf. appendix D (Dirty Tricks), item 5. (Brace -% hacks), of the TeXbook (p. 385-386)). Adding the following line remedies -% the wrong behaviour. +% hacks), of the TeXbook (p. 385-386)). Adding the following line at this +% point +% \begin{verbatim} +% \ifnum`{=0}\fi% +% \end{verbatim} +% remedies the wrong behaviour. But \lstthanks{Qing Lee}{2014/06/28} pointed out, +% that this breaks code like the one showed in \ref{uListingsArguments} on +% \pageref{uListingsArguments} and proposed another +% solution which in turn broke the code needed by Luc: +% \begin{verbatim} +% % \renewcommand\lstinline[1][]{% +% % \leavevmode\bgroup % \hbox\bgroup --> \bgroup +% % \def\lst@boxpos{b}% +% % \lsthk@PreSet\lstset{flexiblecolumns,#1}% +% % \lsthk@TextStyle +% % \ifnum\iffalse{\fi`}=\z@\fi +% % \@ifnextchar\bgroup{% +% % \ifnum`{=\z@}\fi% +% % \afterassignment\lst@InlineG \let\@let@token}{% +% % \ifnum`{=\z@}\fi\lstinline@}} +% \end{verbatim} +% So finally the old code comes back and the people, who need a +% |\lstinline| with braces, should use the workaround from section +% \ref{uListingsArguments} on page \pageref{uListingsArguments}. % \begin{macrocode} - \ifnum`{=0}\fi% \afterassignment\lst@InlineG \let\@let@token}% \lstinline@} \def\lstinline@#1{% @@ -14486,7 +14589,7 @@ \xdef\dospecials{\dospecials}% % \end{macrocode} % Fixing |\@sanitize| is the same except that we need to re-define -% |\@makeother| which obviously needs to be done in a group. +% |\@makeother| which obviously needs to be done in a group. % \begin{macrocode} \begingroup \def\@makeother##1{% |