summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/listings/listings.dtx
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2015-06-14 17:53:48 +0000
committerKarl Berry <karl@freefriends.org>2015-06-14 17:53:48 +0000
commit6a598465f500d8ac3a87b812b16358ba0835b1bf (patch)
tree01f1bbce0a210482743e08ff9c13cc145bde7056 /Master/texmf-dist/source/latex/listings/listings.dtx
parent02f01f7ec631cb85a67d59c9be5ab48e9d936d30 (diff)
listings (5jun15)
git-svn-id: svn://tug.org/texlive/trunk@37534 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.dtx187
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{%