summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/listings-ext
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/listings-ext
Initial commit
Diffstat (limited to 'macros/latex/contrib/listings-ext')
-rw-r--r--macros/latex/contrib/listings-ext/README24
-rw-r--r--macros/latex/contrib/listings-ext/THIS_IS_VERSION_v671
-rw-r--r--macros/latex/contrib/listings-ext/listings-ext.dtx2150
-rw-r--r--macros/latex/contrib/listings-ext/listings-ext.ins123
-rw-r--r--macros/latex/contrib/listings-ext/listings-ext.pdfbin0 -> 126280 bytes
5 files changed, 2298 insertions, 0 deletions
diff --git a/macros/latex/contrib/listings-ext/README b/macros/latex/contrib/listings-ext/README
new file mode 100644
index 0000000000..189846ba55
--- /dev/null
+++ b/macros/latex/contrib/listings-ext/README
@@ -0,0 +1,24 @@
+#
+# $Revision: 60 $
+#
+The LaTeX package "listings-ext.dtx" contains some macros and a supporting
+Bash script, which can be used to automatically input parts of source code
+programs into a documentation.
+
+It consists of four files:
+ README - this file
+ listings-ext.dtx - the actual package with integrated documentation
+ listings-ext.ins - the installation script
+ listings-ext.pdf - the documentation
+
+For further information see the documentation in listings-ext.pdf.
+
+At this moment the english documentation is very erroneous, I'm not an English
+native speaker.
+
+Any hints as well as any proposal for further development are welcome at my
+email-address j.hoffmann@fh-aachen.de.
+
+This material is subject to the LaTeX Project Public License.
+See http://www.ctan.org/tex-archive/help/Catalogue/licenses.lppl.html
+for the details of that license.
diff --git a/macros/latex/contrib/listings-ext/THIS_IS_VERSION_v67 b/macros/latex/contrib/listings-ext/THIS_IS_VERSION_v67
new file mode 100644
index 0000000000..3965943e82
--- /dev/null
+++ b/macros/latex/contrib/listings-ext/THIS_IS_VERSION_v67
@@ -0,0 +1 @@
+VERSION v67 of 2010/06/29
diff --git a/macros/latex/contrib/listings-ext/listings-ext.dtx b/macros/latex/contrib/listings-ext/listings-ext.dtx
new file mode 100644
index 0000000000..1baeaa9b6a
--- /dev/null
+++ b/macros/latex/contrib/listings-ext/listings-ext.dtx
@@ -0,0 +1,2150 @@
+% \iffalse meta-comment
+%
+% Copyright (C) 2008-2010 Jobst Hoffmann, FH Aachen, Campus J\"ulich <j.hoffmann_(at)_fh-aachen.de>
+% -----------------------------------------------------------------------------------------
+%
+% This file may be distributed and/or modified under the
+% conditions of the LaTeX Project Public License, either version 1.2
+% 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.2 or later is part of all distributions of LaTeX
+% version 1999/12/01 or later.
+%
+% \fi
+%
+%
+% \changes{v67}{10/06/29}{removed some needless blanks}
+% \changes{v67}{10/06/29}{email adresses are obfuscated now}
+% \changes{v58}{10/05/18}{moved the docstrip guards into the corresponding macrocode environments}
+% \changes{v56}{10/03/09}{some small layout changes}
+% \changes{v37}{09/08/27}{changed the copyright message again}
+% \changes{v11}{09/04/15}{changed the Copyright message}
+% \changes{v16}{09/08/18}{replaced macroname rcs by svn}
+% \iffalse
+%<extension>\NeedsTeXFormat{LaTeX2e}[1995/12/01]
+%<extension>{%
+%<extension> \def\@svn@ $#1Date: #2-#3-#4 #5$$#6Revision: #7$ {%
+%<extension> \ProvidesPackage{listings-ext}[#2/#3/#4 v#7 an extension for the listings package (JHf)]}
+%<extension> \@svn@ $Date: 2010-06-29 18:38:12 +0200 (Di, 29 Jun 2010) $$Revision: 67 $ %
+%<extension>}
+% \fi
+% \CheckSum{363}
+% \changes{v41}{09/08/27}{removed typos again}
+% \def\docdate {10/06/29} ^^A not style'able!!
+%
+% \changes{v11}{09/04/15}{turned german documentation into an english one}
+%\iffalse
+%
+% Package `listings-ext' for use with LaTeX v2e
+% Copyright (C) 2008-2010 Jobst Hoffmann <j.hoffmann (at) fh-aachen.de>, all rights reserved.
+% -----------------------------------------------------------------
+%
+% This file may be distributed and/or modified under the
+% conditions of the LaTeX Project Public License, either version 1.2
+% 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.2 or later is part of all distributions of LaTeX
+% version 1999/12/01 or later.
+%
+% Address your error messages to:
+% Jobst Hoffmann
+% Fachhochschule Aachen, Campus J"ulich
+% Ginsterweg 1
+% 52428 J"ulich
+% Bundesrepublik Deutschland
+% Email: <j.hoffmann_(at)_fh-aachen.de>
+%
+%\fi
+%
+% \def\listingsextSty{{\sf listings-ext.sty}}
+% \def\listingsext{{\sf listings-ext}}
+%
+% \changes{v33}{09/08/23}{updated `DoNotIndex list}
+% \DoNotIndex{\ ,\!,\C,\[,\\,\],\^,\`,\{,\},\~,\<,\=, \", \|}
+% \DoNotIndex{\@ifundefined,\@ne, \@spaces, \author}
+% \DoNotIndex{\catcode, \copyright, \def, \docdate, \documentclass}
+% \DoNotIndex{\else,\endinput,\expandafter,\fi,\filedate,\fileversion}
+% \DoNotIndex{\gdef,\global,\ifnum,\ifx,\let,\long}
+% \DoNotIndex{\newcount,\newdimen,\newif,\next,\space,\string}
+% \DoNotIndex{\the,\xdef,\z@}
+% \DoNotIndex{\@@par, \@empty, \@hangfrom, \@reffalse, \@reftrue,}
+% \DoNotIndex{\advance, \Alph, \alph, \arabic, \arraystretch, \baselineskip}
+% \DoNotIndex{\begin}
+% \DoNotIndex{\bgroup, \bigskip, \box, \bullet, \cdot, \centering}
+% \DoNotIndex{\columnwidth, \csname, \day, \divide, \dotfill, \dp}
+% \DoNotIndex{\edef, \egroup, \empty, \end, \endcsname, \font, \footins, \foo}
+% \DoNotIndex{\frenchspacing, \hbadness, \hbox, \hfil, \hfill, \hline}
+% \DoNotIndex{\hrule, \hsize, \hskip, \hspace, \hss, \ht, \ifcase}
+% \DoNotIndex{\ifdim, \ifodd}
+% \DoNotIndex{\ifvmode, \ignorespaces, \input, \interlinepenalty, \item}
+% \DoNotIndex{\itemindent, \kern, \L, \large, \leaders, \list, \listparindent}
+% \DoNotIndex{\magstep}
+% \DoNotIndex{\magstephalf, \makelabel, \MakeShortVerb, \marginpar}
+% \DoNotIndex{\mark, \mbox, \month, \multicolumn, \newpage, \newcommand}
+% \DoNotIndex{\nobreak, \noexpand, \noindent}
+% \DoNotIndex{\normalsize, \null}
+% \DoNotIndex{\number, \onecolumn, \or, \overfullrule}
+% \DoNotIndex{\pagebreak, \pagestyle, \parbox, \penalty, \phantom, \protect}
+% \DoNotIndex{\quad}
+% \DoNotIndex{\raggedbottom, \raggedleft}
+% \DoNotIndex{\relax, \renewcommand, \reversemarginpar}
+% \DoNotIndex{\rightmargin, \rule, \setbox, \setcounter}
+% \DoNotIndex{\setlength, \settowidth, \shortstack, \strut, \svtnsfb, \switch}
+% \DoNotIndex{\thepage, \thispagestyle, \tiny, \today, \triangleright, \typeout}
+% \DoNotIndex{\underbar, \underline, \unskip, \uppercase, \usepackage}
+% \DoNotIndex{\vadjust, \vbadness, \vbox, \verb, \vfil, \vfill, \vrule, \vskip}
+% \DoNotIndex{\vspace, \vtop, \wd, \year}
+% \DoNotIndex{\bf, \tt, \par, \smallskip, \stepcounter}
+%
+% ^^A some extra entries to make wrong entries in the index invisible
+% \DoNotIndex{\-, \n, \t, \tbe, \tcase, \tdebug, \tgenerate, \tIf, \tif, \tinto}
+% \DoNotIndex{\tof, \tprocessed, \tshow, \twrite}
+%
+% ^^A \setlength{\IndexMin}{0.3\textheight}
+%
+% \changes{v56}{10/03/09}{corrected typo at `Fname}
+% \changes{v50}{10/02/15}{changed some documentation commands to starred version}
+% \changes{v37}{09/08/27}{reworked the documentation}
+% \changes{v35}{09/08/27}{some textual changes}%
+% \changes{v34}{09/08/24}{reworked the documentation}%
+% \changes{v34}{09/08/24}{added commands `Fname and `ext to unify the documentation}%
+% \changes{v34}{09/08/24}{changed the title again}%
+% \changes{v33}{09/08/23}{changed title}%
+% \changes{v23}{09/08/20}{enhanced the documentation}%
+% \changes{v23}{09/08/20}{rearranged the sections about Makefile, tests,
+% AUCTeX}%
+% \changes{v16}{09/08/18}{added macros to make the documentation
+% independent of non standard packages}%
+% \changes{v11}{09/04/15}{corrected some text}%
+% ^^A now some macros to simplify the writing of the documentation
+% \newcommand*\Lopt[1]{\textsf{#1}}%
+% \let\Lpack\Lopt%
+% \let\ext\Lopt%
+% \newcommand*{\Fname}[1]{\texttt{#1}}%
+% \newcommand*{\XEmacs}{\textsf{(X)Emacs}}%
+% \newcommand*{\SOURCEFRAME}{%
+% \psline(0,0)(0,7)
+% \psline(1.5,0)(1.5,7)
+% \rput[lc](0.75,0){\ldots}
+% \rput[lc](0.75,7){\ldots}
+% }
+% \newcommand*{\SOURCEA}[1]{%
+% \psline*[linecolor=LemonChiffon](0,0)(1.5,0)(1.5,2)(0,2)%
+% \if#1f%
+% \psline(0,0)(1.5,0)(1.5,2.0)(0,2.0)(0,0)%
+% \else\if#1g
+% \psline[linewidth=1mm, linecolor=Olive](1.5,2.05)(0,2.05)%
+% \psline[linewidth=1mm, linecolor=DarkOliveGreen](0,-0.05)(1.5,-0.05)%
+% \fi\fi%
+% }
+% \newcommand*{\SOURCEB}[1]{%
+% \psline*[linecolor=LightGreen](0,0)(1.5,0)(1.5,0.5)(0,0.5)%
+% \if#1f%
+% \psline(0,0)(1.5,0)(1.5,0.5)(0,0.5)(0,0)%
+% \else\if#1g
+% \psline[linewidth=1mm, linecolor=Olive](1.5,0.55)(0,0.55)%
+% \psline[linewidth=1mm, linecolor=DarkOliveGreen](0,-0.05)(1.5,-0.05)%
+% \fi\fi%
+% }
+% \newcommand*{\SOURCEC}[1]{%
+% \psline*[linecolor=LightCyan](0,0)(1.5,0)(1.5,1.25)(0,1.25)%
+% \if#1f%
+% \psline(0,0)(1.5,0)(1.5,1.25)(0,1.25)(0,0)%
+% \else\if#1g
+% \psline[linewidth=1mm, linecolor=Olive](0,-0.05)(1.5,-0.05)%
+% \psline[linewidth=1mm, linecolor=DarkOliveGreen](1.5,1.30)(0,1.30)%
+% \fi\fi%
+% }
+% ^^A to avoid underfull messages while formatting two/three columns
+% \hbadness=10000 \vbadness=10000%
+% \setcounter{secnumdepth}{2}%
+% \setcounter{tocdepth}{2}%
+%
+% \title{\listingsext\ --- A collection of \LaTeX{} commands and some
+% helper files to support the automatic integration of parts of source
+% files into a documentation\thanks{%
+% This file has version number \fileversion, last revised on \filedate{},
+% documentation dated \docdate.}%
+% }%
+% \author{Jobst Hoffmann\\
+% Fachhochschule Aachen, Campus J\"ulich\\
+% Ginsterweg 1\\
+% 52428 J\"ulich\\
+% Bundesrepublik Deutschland\\
+% email: j.hoffmann\_(at)\_fh-aachen.de}%
+% \date{printed on \today}
+%
+% ^^A\markboth{\LaTeX\ Stil-Option listings-ext, version \fileversion\ of \filedate}
+% ^^A {\LaTeX\ Stil-Option listings-ext, version \fileversion\ of \filedate}
+%
+% \maketitle
+%
+% \begin{abstract}
+% This article describes the use and the implementation of the \LaTeX{}
+% package \listingsextSty{}, a package to simplify the insertion of parts
+% of source code files into a document(ation).
+% \end{abstract}
+%
+% \newif\ifmulticols
+% \IfFileExists{multicol.sty}{\multicolstrue}{}
+%
+% \ifmulticols
+% \addtocontents{toc}{\protect\begin{multicols}{2}}
+% \fi
+%
+% \tableofcontents
+%
+% \section{Preface}
+% \label{sec:preface}
+%
+% \changes{v09}{09/04/05}{added some text to the preface}%
+% This package is
+% intended as an implementation of the macros which are described in
+% \cite{lingnau07:_latex_hacks}. If a software developer wants to document
+% a piece of software, in most cases she/he doesn't need to print out whole
+% source code files, but only parts of the files. This can be achieved by the
+% \Lpack{listings}-package \cite{Heinz:Listings-14} and especially by the command
+% \begin{quote}
+% |\lstinputlisting[linerange={|\meta{first1}|-|\meta{last1}|}|, \ldots{}|]{|\meta{filename}|}|
+% \end{quote}
+% In \cite{lingnau07:_latex_hacks} there are described three macros, which
+% can be created automatically, so that in the case of changes in the
+% source code the developer mustn't change the contents of the line ranges,
+% but she/he only has to rerun a program, which regenerates the meaning of
+% the macros. In the following the three macros and a Bash-script to deal with
+% these three macros are provided.
+%
+%
+% \changes{v16}{09/08/18}{added macros to make the documentation
+% independent of non standard packages}
+% \section[Installation and Maintenance]{Hints For Installation And Maintenance}
+% \label{sec:installation-maintenance}
+%
+% The package \listingsextSty{} is belonging to consists of altogether four files:
+% \begin{quote}
+% \Fname{README}, \\
+% \Fname{listings-ext.ins}, \\
+% \Fname{listings-ext.dtx}, \\
+% \Fname{listings-ext.pdf}.
+% \end{quote}
+% In order to generate on the one hand the documentation of the package and
+% on the other hand the corresponding \ext{.sty}-file and the supporting Bash-script
+% one has to proceed as follows:
+%
+% \changes{v46}{09/08/31}{enhanced the documentation at several points}
+% First the file \textsf{listings-ext.ins} must be formatted e.g.\ by
+% \begin{quote}
+%\begin{verbatim}
+%latex listings-ext.ins
+%\end{verbatim}%
+% \end{quote}
+% This formatting run generates several other files. These are first of
+% all the previous mentioned \ext{.sty}-file \Fname{listings-ext.sty}, the
+% style file which can be used by |\usepackage{listings-ext}| and the
+% Bash-script |listings-ext.sh|. Then there are the files
+% \Fname{listings-ext.bib} and \Fname{hyperref.cfg}, which are needed to
+% produce this documentation. The creation of the documentation is is
+% simplified by the files \Fname{listings-ext.makemake} and
+% \Fname{listings-ext.mk}, which can be used to make a \Fname{Makefile}
+% (see section~\ref{sec:Makefile}). Another helper file is
+% \Fname{listings-ext.el}, which can be used with the \XEmacs{} editor (see
+% section~\ref{sec:AUCTeX}). Some simple tests of this package can be done
+% by using the files \Fname{listings-ext*exmpl*} and
+% \Fname{listings-ext*test*}, which are also created; these files use the
+% configuration file \Fname{listings.cfg}, which can also be used as a base or
+% supplement for own configuration files of the
+% \Lpack{listings}-package. This file can be put into the current
+% directory for local use or into the |TEXMFHOME| directory for use with
+% every document. You have to take care about the fact, that the local
+% file in the current directory prevent any |listings.cfg| from being loaded.
+% Finally there is a file \Fname{getversion.tex}, which is used for the
+% creation of a "versioned" distribution.
+%
+% The common procedure to produce the documentation is to execute the
+% commands
+% \begin{quote}
+%\begin{verbatim}
+%latex listings-ext.dtx
+%bibtex listings-ext
+%latex listings-ext.dtx
+%makeindex -s gind.ist listings-ext.idx
+%makeindex -s gglo.ist -o listings-ext.gls -t listings-ext.glg \
+% listings-ext.glo
+%latex listings-ext.dtx
+%\end{verbatim}
+% \end{quote}
+% The result of this formatting run is the documentation in form of a
+% \ext{.dvi}-file, that can be manipulated the normal way. It ain't
+% possible to use |pdflatex| because of the integrated PostScript based
+% figures.
+%
+% One can find further informations about working with the integrated
+% documentation in \cite{FM:TheDocAndShortvrbPackages} and
+% \cite{MittelbachDuchierBraams:DocStrip}.\footnote{Generating the
+% documentation is much easier with the \texttt{make} utility, see
+% section~\ref{sec:Makefile}.}
+%
+% \changes{v33}{09/08/23}{cleaned up the driver once more}
+% \changes{v33}{09/08/23}{moved hyperref settings into hyperref.cfg}
+% \changes{v23}{09/08/20}{cleaned up the code}
+% \changes{v16}{09/08/18}{replaced last german sentences from
+% documentation}
+% This documentation itself is generated by the following internal driver
+% code:
+% \begin{macrocode}
+%<*driver>
+\documentclass[a4paper, ngerman, english]{ltxdoc}
+
+\usepackage[T1]{fontenc}
+\usepackage{lmodern}
+\usepackage{babel,babelbib}
+\usepackage[svgnames]{pstricks}
+
+\usepackage{listings-ext}
+\GetFileInfo{listings-ext.sty}
+
+\newif\ifcolor \IfFileExists{color.sty}{\colortrue}{}
+\ifcolor \RequirePackage{color}\fi
+
+\usepackage[numbered]{hypdoc}
+\usepackage{url}
+
+%\EnableCrossrefs
+%\DisableCrossrefs % say \DisableCrossrefs if index is ready
+%\RecordChanges % gather update information
+%\CodelineIndex % index entry code by line number
+\OnlyDescription % comment out for implementation details
+\MakeShortVerb{\|} % |\foo| acts like \verb+\foo+
+
+\begin{document}
+
+ \DocInput{listings-ext.dtx}%
+\end{document}
+%</driver>
+% \end{macrocode}
+%
+% \changes{v13}{09/05/28}{enhanced the documentation}
+% \section{The User's Interface}
+% \label{sec:users-interface}
+%
+% \changes{v16}{09/08/18}{extended the description of usage}
+% \subsection{Preparing the \LaTeX{} code}
+% \label{sec:preparing-latex}
+%
+% The user's interface is as simple as possible: just load the required
+% package by saying
+% \begin{quote}
+% |\usepackage[|style=\meta{style-name}|]{listings-ext}|
+% \end{quote}
+% \meta{style-name} is the name of a \textsf{listings} style, defined by
+% the command \cite[sec.~4.5]{Heinz:Listings-14}. You can find examples for
+% such styles in the exemplary configuration file \Fname{listings.cfg}.
+% \begin{quote}
+% |\lstdefinestyle{|\meta{style name}|}{|\meta{key=value list}|}|
+% \end{quote}
+%
+% After loading the package provides three commands:
+% \begin{enumerate}
+% \item \begin{quote}
+% |\lstdef{|\meta{identifier}|}{|\meta{file-name}|}{|\meta{range}|}|
+% \end{quote}
+% defines the \meta{identifier}, by which the line range \meta{range} in the
+% file defined by \meta{file-name} can be referenced. If you identify
+% several \meta{filename}s or \meta{range}s by the same
+% \meta{identifier}, the last definition is valid. If you don't like
+% that behaviour, put the corresponding |\lstdef|- and
+% |\lstuse|-commands (see below) into a group of its own.
+% \item \begin{quote}
+% |\lstuse[|\meta{options}|]{|\meta{identifier}|}|
+% \end{quote}
+% includes the source code which is referenced by \meta{identifier} by
+% (internally) calling |\lstinputlisting| of the package
+% \Lpack{listings} \cite{Heinz:Listings-14}, the way of formatting can be influenced by
+% \meta{options}.
+% \item
+% \begin{quote}
+% |\lstcheck{|\meta{identifier}|}{|\meta{file-name}|}|
+% \end{quote}
+% can be used, if one prepares a file \meta{file-name} consisting of a
+% lot of |\lstdef| commands. If \meta{identifier} isn't yet defined,
+% the file defined by \meta{file-name} is |\input|. This command is
+% especially helpful, if you prepare a presentation and you want to
+% format only single slides for testing their look.
+% \end{enumerate}
+%
+%
+% \subsection{Preparing the source code}
+% \label{sec:preparing-source}
+%
+% If you just want to include a small part of a source code file, you can
+% do that without touching the source: just write the corresponding
+% commands |\lstdef| and |\lstuse| into your \LaTeX-code. But if the
+% source code changes, you have to adapt the changes in the |\lstdef|
+% command. That may be very tedious, if are you changing your sources often.
+%
+% It' better to automate that procedure, and one way of implementig that is
+% done at the Bash-script \Fname{listings-ext.sh}. For working with that
+% script you have to tag the parts of the source, which you want to
+% document, by comments.
+%
+% At the moment there are three tags, which can be described by the
+% following regular expressions:
+% \begin{enumerate}
+% \item |^\ +|\meta{endline-comment-character(s)}|\ be:\ |\meta{string}|$|
+%
+% This expression defines the beginning of the environment, which should be
+% |\lstinput| into the document.
+% \item |^\ +|\meta{endline-comment-character(s)}|\ ee:\ |\meta{string}|$|
+%
+% This expression defines the end of that environment.
+% \item |^\ +|\meta{endline-comment-character(s)}|\ ce:\ |\meta{list of
+% keywords}
+%
+% This expression defines, how the the environments defined by the above
+% introduced should be processed.
+% \end{enumerate}
+% The meaning of the regular expressions is: start a line with at least one
+% blank space "\verb*| |", add endline comment characters (C++ and Java:
+% |//|, Fortran: |!|) followed by another blank space. Then you have to
+% enter "\verb*|be: |" for the beginning of a code environment, and %
+% "\verb*|ee: |" for the end. In both cases the line must be ended with a
+% string which should denote the meaning of the environment , the strings for the
+% beginning and the end must be identical.\footnote{You can also use the
+% standard C comments |/*| \ldots|*/|, but in that case the trailing "|*/|"
+% is seen as the end of the \meta{string}.}
+%
+% \changes{v63}{10/06/22}{added remarks about Max OS X}
+% \changes{v53}{10/03/09}{issue solved: now able to handle any file name as
+% list of source files}
+% If you have prepared a source code file with these tags, you can process
+% it by the Bash-script provided by the package. The script should work for
+% a Linux system out of the box, for a Mac OS X 10.x one must additionally
+% install |getopt| from \url{http://getopt.darwinports.com/}, which in turn
+% needs |MacPorts| (from
+% \url{http://www.macports.org/install.php}).\footnote{The package is
+% tested with Max OS X v\,10.6.3, |getopt|'s version number is v\,1.1.4 and
+% |MacPorts| version number is v\,1.9.0.}
+%
+% The simplest way to do it is the call
+% \begin{quote}
+% |listings-ext.sh -co |\meta{file list}
+% \end{quote}
+% \meta{file list} is a list of one or more file names. This call creates
+% the file \meta{directory}|.lst|, where \meta{directory} is the name of
+% the current directory. The file consists of a header and a list of |\lstdef|
+% commands,
+% of the form
+% \begin{quote}
+% |\lstdef{|\meta{identifier}|}{|\meta{filename}|}{|\meta{line range(s)}|}|
+% \end{quote}
+% You can |\input| the file \meta{directory}|.lst| into your documentation;
+% its header looks like (for example)
+%\begin{verbatim}
+% %% -- file listings-ext.lst generated on Mi 26. Aug 22:05:20 CEST 2009
+% by listings-ext.sh
+% \csname listingsextLstLoaded\endcsname
+% \expandafter\let\csname listingsextLstLoaded\endcsname\endinput
+%\end{verbatim}
+% The first line is wrapped by hand, the second and third line prohibit a
+% second load of that file. One of the |\lstdef| could look like
+%\begin{verbatim}
+% \lstdef{listingsExtExmplAA}{/home/xxx%
+% /listings-ext%
+% /listings-ext_exmpl_a.java}{3-5}
+%\end{verbatim}
+%
+% You can input this file in two ways into your document:
+% \begin{enumerate}
+% \item by saying
+%\begin{verbatim}
+% \input{listings-ext.lst}
+%\end{verbatim}
+% at the beginning of a file or
+% \item by saying
+%\begin{verbatim}
+% \lstcheck{listingsExtExmplAA}{listings-ext.lst}
+%\end{verbatim}
+% in an environment to keep the definition local.
+% \end{enumerate}
+%
+% After that you can use the command |\lstuse| to integrate the source
+% code parts into your documentation. The usage is
+% \begin{quote}
+% |\lstuse[|\meta{options}|]{|\meta{identifier}|}|
+% \end{quote}
+% at the place, where you want the part of your source code.
+%
+% The \meta{identifier} is generated automatically, it is derived from the
+% file name, you have to transfer the identifiers from the \ext{.lst}-file
+% to the |\lstuse|-command by hand, but that happens typically only one
+% time. So in this case the |\lstuse| command could look like --- as said
+% you can add options ---
+%\begin{verbatim}
+% \lstuse{listingsExtExmplAA}
+%\end{verbatim}
+%
+% For more information about the use of the Bash-script |listings-ext.sh|
+% enter the command
+% \begin{quote}
+% |listings-ext.sh -h|
+% \end{quote}
+%
+% \changes{v09}{09/04/05}{introduced a description of the ce-commands}
+% There is one optional initial tag |ce:| (\textit{control environment}): It needs one
+% argument \meta{mode}. The argument describes the further
+% processing. \meta{mode} may be one of the following values:
+% \begin{description}
+% \item[\texttt{combine}:] |be: | \ldots{}|ee: | groups with the same
+% description are combined into one piece of code in the output
+% \item[\texttt{join}:] all |be: | \ldots{}|ee: | groups (independent of
+% the description) are combined into one piece of code in the output
+% \end{description}
+% The behaviour of the three modes of operation is shown in
+% Figure~\ref{fig:modes-operation}.
+% |ce:| has to be put before all other tags in the source code.
+% \changes{v35}{09/08/27}{added figure to show the behaviour of listings-ext.sh}
+% \begin{figure}[htb]
+% \psset{unit=6mm} \centering
+% \begin{pspicture}(0,-1.0)(4,7) \rput[lB](0,4.5){\SOURCEA{g}}
+% \rput[lB](0,3.0){\SOURCEB{g}} \rput[lB](0,1.0){\SOURCEC{g}}
+% \rput[lB](0,0){\SOURCEFRAME} \rput[lB](2.5,4.5){\SOURCEA{f}}
+% \rput[lB](2.5,3.0){\SOURCEB{f}} \rput[lB](2.5,1.0){\SOURCEC{f}}
+% \rput(2.5,-0.7){a)}
+% \end{pspicture}
+% \hspace{2cm}
+% \begin{pspicture}(0,-1.0)(4,7) \rput[lB](0,4.5){\SOURCEA{g}}
+% \rput[lB](0,3.0){\SOURCEB{g}} \rput[lB](0,1.0){\SOURCEC{g}}
+% \rput[lB](0,0){\SOURCEFRAME} \rput[lB](2.5,3.5){\SOURCEA{}}
+% \rput[lB](2.5,3.0){\SOURCEB{}} \rput[lB](2.5,1.75){\SOURCEC{}}
+% \psframe(2.5,1.75)(4.0,5.5) \rput(2.5,-0.7){b)}
+% \end{pspicture}
+% \hspace{2cm} \begin{pspicture}(0,-1.0)(4,7)
+% \rput[lB](0,4.5){\SOURCEA{g}} \rput[lB](0,3.0){\SOURCEB{g}}
+% \rput[lB](0,1.0){\SOURCEC{g}} \rput[lB](0,0){\SOURCEFRAME}
+% \rput[lB](2.5,3.5){\SOURCEA{}} \rput[lB](2.5,2.25){\SOURCEC{}}
+% \psframe(2.5,2.25)(4.0,5.5) \rput[lB](2.5,1.0){\SOURCEB{}}
+% \psframe(2.5,1.0)(4.0,1.5) \rput(2.5,-0.7){c)}
+% \end{pspicture}
+% \caption[Modes of operation]{Modes of operation: a) no special control of the tagged
+% parts, every part can be processed by itself, b) control by |ce:
+% join|, all tagged parts are joint into one piece, which can be
+% further processed, c) control by |ce: combine|, tagged parts with
+% the same describing string are joint into one piece, which can be
+% further processed, all other parts can be processed by their own}
+% \label{fig:modes-operation}
+% \end{figure}
+%
+%
+% \changes{v33}{09/08/23}{moved bibliography into listings-ext.bib}
+% \changes{v27}{09/08/21}{a few small layout changes}
+% \changes{v16}{09/08/18}{internalized the bibliography}
+% \StopEventually{
+% \bibliographystyle{babalpha}
+% \bibliography{listings-ext}
+%
+% \ifmulticols
+% \addtocontents{toc}{\protect\end{multicols}}
+% \fi
+%
+% \PrintChanges
+% \PrintIndex
+% } ^^A end of \StopEventually
+%
+% \clearpage
+%
+%
+% \changes{v16}{09/08/18}{started the documentation of the implementation}
+% \section{The Implementation}
+% \label{sec:the-implementation}
+%
+% \subsection{The style file}
+% \label{sec:the-style-file}
+%
+% At first we must declare the required packages :
+% \begin{macrocode}
+%<*extension>
+\RequirePackage{listings}
+\RequirePackage{xkeyval}
+% \end{macrocode}
+% and the package options for \listingsextSty.
+% \begin{macro}{style}
+% is the only option at the moment.
+% \begin{macrocode}
+\DeclareOptionX{style}[]{\lstset{style=#1}}
+\ProcessOptionsX*
+% \end{macrocode}
+% \end{macro}
+%
+% Then we define the three above mentioned commands in the way, which is
+% described in \cite{lingnau07:_latex_hacks}.
+% \begin{macro}{\lstdef}
+% \changes{v46}{09/08/31}{enhanced the documentation}
+% has three parameters:
+% \begin{quote}
+% \begin{tabular}{ll}
+% \#1 & the identifier of the chunk of source code \\
+% \#2 & the file name of the source code \\
+% \#3 & the line range \\
+% \end{tabular}
+% \end{quote}
+% Every parameter can be used at the user's choice, so there is no chance
+% to test the parameters.
+% \begin{macrocode}
+\newcommand{\lstdef}[3]{%
+ \@namedef{lst@l@#1}##1{%
+ \lstinputlisting[##1, linerange={#3}]{#2}}%
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\lstcheck}
+% \changes{v46}{09/08/31}{enhanced the documentation}
+% has two parameters:
+% \begin{quote}
+% \begin{tabular}{ll}
+% \#1 & the identifier of the chunk of source code \\
+% \#2 & the file name of a file with many |lstdef| lines \\
+% \end{tabular}
+% \end{quote}
+% \changes{v45}{09/08/31}{added some checks for arguments}
+% \begin{macrocode}
+\newcommand{\lstcheck}[2]{%
+% \end{macrocode}
+% At first we test, if the identifier is unknown. If so, we read the above
+% mentioned file.
+% \begin{macrocode}
+ \expandafter\ifx\csname lst@l@#1\endcsname\relax%
+ \input{#2}\fi%
+% \end{macrocode}
+% Now the identifier should be known. If not, we emit a corresponding error
+% message.
+% \begin{macrocode}
+ \expandafter\ifx\csname lst@l@#1\endcsname\relax%
+ \PackageError{listings-ext}{undefined identifier}{%
+ You may have mispelled the identifier, check the file%
+ \MessageBreak\space\space\space#2\MessageBreak%
+ for the correct spelling.}\fi%
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\lstuse}
+% \changes{v46}{09/08/31}{enhanced the documentation}
+% has two parameters:
+% \begin{quote}
+% \begin{tabular}{ll}
+% \#1 & options of the |\lstinputlisting| command (optional) \\
+% \#2 & the above defined identifier \\
+% \end{tabular}
+% \end{quote}
+% \changes{v45}{09/08/31}{added some checks for arguments}
+% \begin{macrocode}
+\newcommand{\lstuse}[2][]{%
+% \end{macrocode}
+% At first we test, if the identifier is unknown. If so, we emit a
+% corresponding error message.
+% \begin{macrocode}
+ \expandafter\ifx\csname lst@l@#2\endcsname\relax%
+ \PackageError{listings-ext}{undefined identifier}{%
+ You may have mispelled the identifier.\MessageBreak%
+ If you go on without any change, no source code will be %
+ included,\MessageBreak but your options will be written %
+ into your formatted document.}\fi%
+% \end{macrocode}
+% Now we can |\lstinputlisting| the source code by use of the
+% |\@namedef| ed command.
+% \begin{macrocode}
+ \@nameuse{lst@l@#2}{#1}%
+}
+%</extension>
+% \end{macrocode}
+% \end{macro}
+% That' all for the \LaTeX-side of life.
+%
+%
+% \changes{v46}{09/08/31}{enhanced the documentation at several points}
+% \changes{v45}{09/08/31}{introduced an exemplary configuration file}
+% \subsection{An exemplary configuration file}
+% \label{sec:a-configuration-file}
+%
+% It is a good practise, to format all source code chunks in the same
+% way. The easiest way to do that is to provide a style. The following
+% lines provide two styles, one for the use with a black and white
+% printer, the other for a printer which is capable of color output.
+% \begin{macrocode}
+%<*listings>
+\ProvidesFile{listings.cfg}%
+ [2009/08/23 v1.0 listings configuration of listings-ext]
+
+\RequirePackage{xcolor}
+
+\def\lstlanguagefiles{lstlang1.sty,lstlang2.sty,lstlang3.sty}
+\lstset{defaultdialect=[ANSI]C,
+ defaultdialect=[ISO]C++,
+ defaultdialect=[95]Fortran,
+ defaultdialect=Java,
+ defaultdialect=[LaTeX]TeX,
+ frame=tlb,
+ resetmargins=false,
+ }
+\lstdefinestyle{colored-code}{
+ backgroundcolor=\color{yellow!10},%
+ basicstyle=\footnotesize\ttfamily,%
+ identifierstyle=\color{black},%
+ keywordstyle=\color{blue},%
+ stringstyle=\color{teal},%
+ commentstyle=\itshape\color{orange},%
+}
+\lstdefinestyle{bw-code}{
+ basicstyle=\small\fontfamily{lmtt}\fontseries{m}\fontshape{n}\selectfont,
+ % instead of lmtt one should use ul9 (luximono) for boldface characters
+ keywordstyle=\small\fontfamily{lmtt}\fontseries{b}\fontshape{n}\selectfont,
+ commentstyle=\small\fontfamily{lmtt}\fontseries{m}\fontshape{sl}\selectfont,
+ stringstyle=\small\fontfamily{lmtt}\fontseries{m}\fontshape{it}\selectfont,
+}
+%</listings>
+% \end{macrocode}
+%
+%
+% \changes{v16}{09/08/18}{moved the documentation of the script into the documentation}
+% \subsection{The shell script}
+% \label{sec:the-shell-script}
+%
+% \changes{v58}{10/05/18}{removed some bashisms (according to Ahmed El-Mahmoudy---aelmahmoudy\_at\_sabily.org)}
+% \changes{v37}{09/08/27}{removed small glitches}
+% \changes{v23}{09/08/20}{moved some more comment from the script into the documentation}
+% \changes{v12}{09/05/12}{added some debug code}
+% \changes{v11}{09/04/15}{added some documentation}
+% \changes{v09}{09/04/05}{added some space for a better layout}
+% \changes{v05}{08/03/04}{add a debug option for the script}
+% \changes{v05}{08/03/04}{change the behaviour: hyphens and underscores are removed in
+% the .lst-file}
+% \changes{v05}{08/03/04}{check the correct grouping of be...ee}
+% \changes{v05}{08/03/04}{function delete\_underscore renamed to "replace\_characters"}
+% \changes{v05}{08/03/04}{better error processing with messages to stderr}
+% \changes{v05}{08/03/04}{in replace\_characters now also hyphens are replaced}
+% \changes{v05}{08/03/04}{introduced function print\_error}
+% \changes{v05}{08/03/04}{introduced function break\_line}
+% \changes{v03}{08/02/27}{corrected the on-line help according to the current implementation}
+% \changes{v03}{08/02/27}{changed documentation and behaviour of function print\_header}
+% \changes{v03}{08/02/27}{fixed some typos}
+% \changes{v03}{08/02/27}{output option now has an optional argument}
+% \changes{v03}{08/02/27}{call of print\_header changed according to the
+% optional argument from above}
+% \changes{v06}{08/09/07}{created list of things to do}
+% To get full benefit of the three above introduced commands, we provide a
+% Bash-script, which internally uses |awk|, |grep| and |sed|. A Perl
+% programmer could provide the same functionality by a Perl script.
+%
+% \begin{macrocode}
+%<*scriptfile>
+#! /bin/sh
+### listings-ext.sh ---
+
+## Author: Dr. Jobst Hoffmann <j.hoffmann_(at)_fh-aachen.de>
+## Version: $Id: listings-ext.dtx 67 2010-06-29 16:38:12Z ax006ho $
+## Keywords: LaTeX, listings
+## Copyright: (C) 2008-2010 Jobst Hoffmann, <j.hoffmann_(at)_fh-aachen.de>
+##-------------------------------------------------------------------
+##
+## This file may be distributed and/or modified under the
+## conditions of the LaTeX Project Public License, either version 1.2
+## 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.2 or later is part of all distributions of LaTeX
+## version 1999/12/01 or later.
+##
+## This file belongs to the listings-ext package.
+##
+## listings-ext.sh creates code to be inserted into a
+## LaTeX file from a source file.
+##
+## The commented code can be seen in listings-ext.pdf, which is provided
+## with the distribution package.
+% \end{macrocode}
+%
+% The format of the result is depending on a switch \verb!-c|--command!:
+% \begin{itemize}
+% \item If the switch is set, the result is a single file which can be
+% |\input| into LaTeX code. The file contains lines of the form
+% \begin{quote}
+% |\lstdef{|\meta{identifier}|}{|\meta{filename}|}{|\meta{linerange(s)}|}|
+% \end{quote}
+% \meta{identifier} can be used in the \LaTeX{} code by a command
+% \begin{quote}
+% |\lstuse{|\meta{identifier}|}|
+% \end{quote}
+% to |\lstinputlisting| the source code at that place.
+% \meta{identifier} is derived from the filename of the source file,
+% where there is a sequence of uppercase letters (A, B, \ldots{}, Z,
+% BA, \ldots{}) appended as postfix to distinguish between several
+% chunks. If we are in join mode --- see below ---, there will be no
+% postfix at all. You have to be careful with the filenames: as the
+% identifiers are used as \TeX{}-commands, the have to consist only of
+% characters, but the script allows underscores and hyphens in the
+% filenames and translates them into a camel case notation.
+% \item If the switch is not set, a piece of LaTeX code like the
+% following is generated for every chunk of source code:
+%\begin{verbatim}
+% %===>begin{listingsExtExmplAC}
+% {%
+% \def\inputfile{%
+% /home/xxx/texmf/source/latex/listings-ext%
+% /listings-ext_exmpl_a.java
+% }
+% \ifLecture{%
+% \lstdefinestyle{localStyle}{%
+% caption={\lstinline|listings-ext_exmpl_a.java|: using the resource bundle}
+% }%
+% }
+% {%
+% \lstdefinestyle{localStyle}{%
+% title={\lstinline|listings-ext_exmpl_a.java|: using the resource bundle}
+% }%
+% }
+% \lstinputlisting[style=localStyle, linerange={29-30}]%
+% {%
+% \inputfile
+% }
+% }%
+% % =====>end{listingsExtExmplAC}
+% \end{verbatim}
+% \end{itemize}
+%
+% The source file contains pairs of lines of the form described by the
+% following regular expressions:
+% \begin{itemize}
+% \item |^\ +|\meta{endline-comment-character(s)}|\ be: |\meta{string}|$|
+%
+% This expression defines the beginning of a environment, which should be
+% |\lstinput| into the document.
+% \item |^\ +|\meta{endline-comment-character(s)}|\ ee: |\meta{string}|$|
+%
+% This expression defines the end of that environment.
+% \end{itemize}
+%
+% Another line can preceed all pairs:
+% \begin{quote}
+% |\ +|\meta{endline-comment-character(s)}|\ ce: |\meta{list of keywords}
+% \end{quote}
+%
+% \meta{list of keywords} is a comma separated list of words, the first one
+% must be one of the words
+% \begin{itemize}
+% \item |join|
+% \item |combine|
+% \end{itemize}
+%
+% At the moment we support only these keywords. The meaning of the
+% keywords is
+% \begin{itemize}
+% \item |join|: we generate lines, which print the listing as one part
+% \item |combine|: we generate lines, which print the listing as one part, only
+% for headings, which correspond
+% \end{itemize}
+%
+% These lines will be grepped. The result is processed by |awk| where '|:|' is
+% defined as a field separator, the final result is a range of lines, which
+% is further processed to create the output.
+% \changes{v56}{10/03/09}{a new usage description, added new option "-e"}
+% \changes{v33}{09/08/23}{corrected description of usage of the script}
+% \begin{macrocode}
+ERR_HELP=1
+ME=$(basename $0)
+USAGE="usage:\n\t${ME} [-c|--command] [-e|--ext] [-g|--debug] \\\\\n\
+\t\t[-h|--help] [-n|--no-header] \\\\\n\
+\t\t[{-o|--output-file} [<output filename>]] <filename>, ...\n\
+\t-c:\tgenerate commands, which can be input and later used by\n\
+\t\t\\\\lstuse, optional\n\
+\t-e:\tinclude file name extension into the identifier\n\
+\t-g:\tdebug mode, create some additional output, optional\n\
+\t-h:\tshow this help, optional\n\
+\t-n:\twrite no header into the LaTeX code, optional; valid only,\n\
+\t\tif -c isn't used\n\
+\t-o [<output filename>]: if this argument is present, the output will\n\
+\t\tbe written into a file <output filename>; if the\n\
+\t\t<output filename> is omitted, the output is redirected\n\
+\t\tinto a file with a basename corresponding to the name\n\
+\t\tof the current directory, it has an extension of \".lst\".\n\
+"
+DEBUG_MODE=0
+EXTENSION=0
+HEADER=1
+
+show_usage() { # display help massage
+ printf "${USAGE}"
+ exit ${ERR_HELP}
+}
+% \end{macrocode} ^^A $
+% \changes{v11}{09/04/15}{corrected generation of filename for .lst-output file}
+% \changes{v09}{09/04/05}{changed the documentation of the function
+% print\_header}
+% We define some functions for the internal use. The first one prints the
+% header of the output file, it has two arguments:
+% \begin{itemize}
+% \item \$1: file name---the name of the file to be written on
+% \item \$2: directory - the last name in the directory path (currently
+% not used)
+% \end{itemize}
+% \changes{v63}{10/06/22}{replaced most of the echo commands by printf (because of Mac OS X)}
+% \changes{v53}{10/03/09}{issue solved: now able to handle any file name as
+% list of source files}
+% \begin{macrocode}
+print_header() {
+ FILE=$1
+ printf "%%%% -- file $1 generated on $(date) by ${ME}\n"
+ FILE=$(echo $(basename $1 .lst) | sed -e s/[_\-]//g)
+ printf "\\\\csname ${FILE}LstLoaded\\\\endcsname\n"
+ printf "\\\\expandafter\\\\let\\\\csname ${FILE}LstLoaded\\\\endcsname\\\\endinput\n"
+}
+% \end{macrocode} ^^A $
+% The main function is |do_the_job|. It accepts the following parameter:
+% \begin{enumerate}
+% \item \$1: a filename
+% \end{enumerate}
+% \begin{macrocode}
+do_the_job() {
+% \end{macrocode} ^^A $
+% In |awk| \$0 refers to the whole input record---to the current input
+% line---, so that element could be split into its components which are
+% marked by '/', the result is the name of the current directory without
+% any path elements stored in an array
+%\begin{verbatim}
+% PATHCOMPONENT=$(pwd | \
+% awk -F : '{n = split($0, text, "/"); print text[1] text[n]}')
+%\end{verbatim}
+%
+% The current implementation uses the whole path, it will be split into its
+% parts when it is used.
+% \begin{macrocode}
+ PATHCOMPONENT=$(pwd)
+ SOURCEFILE=$1
+
+ if [ ! -f ${SOURCEFILE} ]
+ then
+ printf "${SOURCEFILE} is no valid file\n"
+ return $ERR_NOFILE
+ fi
+% \end{macrocode} ^^A $
+% \changes{v12}{09/05/12}{added support for ant: filenames are given complete with the path}
+% If the script is called with the full path of the files, the directory
+% part must be cut off from filename
+% \begin{macrocode}
+ SOURCEFILE=${SOURCEFILE##${PATHCOMPONENT}/}
+
+% \end{macrocode} ^^A $
+% \changes{v65}{10/06/28}{grep: replaced blank by space regex}
+% \changes{v51}{10/03/33}{corrected the grep expression according to the definition of the syntax}
+% From the current source file, we grep all the lines with the above
+% mentioned pattern, prepend them by a line number (parameter |-n|)
+% \begin{macrocode}
+ grep -n "^[[:space:]]*[/%;#!][/\* ;][[:space:]]*[cbe]e:" $1 | \
+% \end{macrocode} ^^A $
+% We pass all the lines to |awk|. Additionally we set some parameters and define
+% the field separator by |-F| as "|:|", so that from |awk|'s point of view
+% the lines consist of three parts:
+% \begin{enumerate}
+% \item the line number
+% \item the opening/closing tag
+% \item an identifying string
+% \end{enumerate}
+% \changes{v56}{10/03/09}{a cleaner handling of passing parameters to awk}
+% \begin{macrocode}
+ awk -v pathcomponent="${PATHCOMPONENT}" -v file="${SOURCEFILE}" \
+ -v header="${HEADER}" -v command="${COMMAND}" -v application="${ME}" \
+ -v debugmode="${DEBUG_MODE}" -v respect_extension="${EXTENSION}"\
+ -F : \
+'
+BEGIN {
+% \end{macrocode} ^^A $
+% \changes{v09}{09/04/05}{reflect the introduction of the command combine}
+% We start the code with some settings.
+% In |awk| the value 1 means "true", the value 0 "false".
+% \begin{macrocode}
+ is_opened = 0;
+ initialised = 0;
+ configured = 0;
+ join = 0;
+ combine = 0;
+
+ idChar = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
+ split(idChar, idArray, "")
+ idPt = 0
+ linerange = "";
+
+ linelen = 75; # length of the output line
+ addchars = 8; # number of additional characters like %, > or so
+
+ if ( debugmode ) printf("path: %s\n", pathcomponent) > "/dev/stderr"
+ if ( debugmode ) printf("file: %s\n", file) > "/dev/stderr"
+% \end{macrocode}
+% For |\lstinputting| the file, we need the absolute filepath. In the
+% following, we construct this, the correspondent variable is |inputfile|,
+% the filename to be formatted is split into convenient pieces by a
+% macro
+% \changes{v63}{10/06/22}{rewrote code for splitting paths into names}
+% \begin{macrocode}
+ n = split(pathcomponent, partsa, "/");
+ curr_dir = parts[n]
+% \end{macrocode}
+% \changes{v65}{10/06/28}{breaking of lines moved into a single place}
+% Add the file to the array to process the whole name in a similar manner.
+% \begin{macrocode}
+ n++;
+ partsa[n] = file;
+ inputfile = "/" partsa[2];
+ for ( i = 3; i <= n; i++ ) {
+ inputfile = inputfile "/" partsa[i];
+ }
+ if ( debugmode ) printf("inputfile: %s\n", inputfile) > "/dev/stderr"
+% \end{macrocode}
+% For the identification of the several chunks we need the filename
+% without path and without suffix. We take everything behind the last
+% dot as suffix
+%
+% \changes{v65}{10/06/28}{moved single \{ from beginning of line to end of previous line}
+% The |identifier| mustn't contain any path parts of the filename. So we
+% split the filename here.
+% \begin{macrocode}
+ n = split(file, partsa, "/")
+ n = split(partsa[n], partsb, ".")
+ identifier = partsb[1]
+ for ( i = 2; i < n; i++ ) {
+ identifier = identifier partsb[i]
+ }
+% \end{macrocode}
+% If there are files with the same basename, but different extensions, we
+% may take account of the extensions.
+% \changes{v56}{10/03/09}{added processing of option "-e"}
+% \begin{macrocode}
+ if ( respect_extension ) {
+ identifier = identifier partsb[n]
+ }
+ identifier = replace_characters(identifier)
+ if ( debugmode ) printf("identifier: %s\n", identifier) > "/dev/stderr"
+}
+% \end{macrocode}
+% The following code will be executed for every line, the standard delimiter is ":"
+% \begin{macrocode}
+{
+% \end{macrocode}
+% \changes{v09}{09/04/05}{test external (LaTeX-)documentation of the code}
+% |$0| is the whole line, |$NF| the text, which is used in combine mode as
+% identifier not only for the beginning and ending of a chunk but also for
+% collecting all the chunks.
+% \begin{macrocode}
+ if ( debugmode ) print $0 > "/dev/stderr"
+ if ( !initialised ) {
+% \end{macrocode} ^^A $
+% \changes{v67}{10/06/29}{added remark about CR and LF}
+% \changes{v09}{09/04/05}{extend the external documentation}
+% In the beginning, there are two cases to distinguish:
+% \begin{enumerate}
+% \item There is an introducing |ce| marker
+% \item There is no introducing |ce| marker
+% \end{enumerate}
+% In the first case we have to set a flag according to the value of the
+% mark, in the second case we have to look for the first mark (|be| or
+% |ce|). The marker is supposed to end at the line's end. If a \LaTeX{}
+% source file is created with an editor, which creates the CRLF combination
+% as the end of line, the CR would be thought as part of the marker. To
+% avoid the trouble, the CR is removed (if it exists).
+% \changes{v65}{10/06/28}{added code to remove spurious carriage return character}
+% \begin{macrocode}
+ if ( match($2, /ce/) > 0 ) {
+ n = split($(NF), text, ",");
+ if ( match(text[1], "join") ) {
+ join = 1;
+ } else if ( match(text[1], "combine") ) {
+ combine = 1;
+ }
+ } else if ( match($2, /be/) > 0 ) {
+ opening_tag = $(NF)
+ gsub(/\r/, "", opening_tag);
+ is_opened = 1
+ start = $1 + 1; # entry $1 is the line number
+ } else if ( match($2, /ee/) > 0 ) {
+ print_error($1, "missing \"be\" declaration")
+ }
+ initialised = 1;
+ } else {
+ tag = $(NF)
+ if ( match($2, /be/) > 0 ) {
+ if ( is_opened ) {
+ print_error($1, "incorrect grouping, previous group"\
+ " not closed")
+ } else {
+ opening_tag = $(NF)
+ gsub(/\r/, "", opening_tag);
+ is_opened = 1
+ start = $1 + 1; # entry $1 is the line number
+ }
+ } else {
+ if ( match($2, /ee/) > 0 ) {
+ closing_tag = $(NF)
+ gsub(/\r/, "", closing_tag);
+ if ( !is_opened ) {
+ print_error($1, "missing \"be\" declaration")
+ } else if ( opening_tag == closing_tag ) {
+ is_opened = 0
+% \end{macrocode} ^^A $
+% \changes{v65}{10/06/28}{changed the prefix to a double \% to unify the output}
+% We found the correct end of the environment, now we prepare the output entries
+% \begin{macrocode}
+ split($(NF), text, "*"); # omit a trailing comment
+ sub(/ /, "", text[1]); # delete leading spaces
+ gsub(/"/, "", text[1]);
+ if ( index(text[1], "_") > 0 ) gsub(/_/, "\\_", text[1]);
+ caption = "\\lstinline|" file "|: " text[1]
+
+ # setup the prefixes
+ len = linelen - addchars - length(caption);
+ begin_prefix = "%%";
+ cnt = 0;
+ while ( cnt < len) {
+ begin_prefix = begin_prefix "=";
+ cnt++;
+ };
+ begin_prefix = begin_prefix ">";
+ end_prefix = begin_prefix;
+ sub(/%%/, "%%==", end_prefix);
+% \end{macrocode} ^^A $
+% \changes{v09}{09/04/05}{rewrote the check of the flags}
+% Now we distinguish between |join|- and |combine|-mode and the default mode:
+% \begin{macrocode}
+ if ( join ) {
+% \end{macrocode} ^^A $
+% In |join|-mode we have to collect all informations about chunks into one
+% linerange, this is done by
+% \begin{macrocode}
+ linerange = linerange ", " start "-" $1-1;
+ } else if ( combine ) {
+% \end{macrocode} ^^A $
+% \changes{v11}{09/04/15}{rewrote some code for adding the combine mode}
+% In combine mode we need the whole tag but without leading or trailing
+% blanks, so we delete leading spaces.
+% \begin{macrocode}
+ sub(/ /, "", closing_tag)
+ if ( combine_array[closing_tag] == "" ) {
+ combine_array[closing_tag] = start "-" $1-1
+ } else {
+ combine_array[closing_tag] = \
+ combine_array[closing_tag] ", " start "-" $1-1
+ }
+ if ( debugmode ) printf("combine_array: >%s<\n",\
+ combine_array[closing_tag]) > "/dev/stderr"
+ } else {
+% \end{macrocode} ^^A $
+% We are neither in |combine|- nor in |join|-mode, so we can print out the
+% separate linechunks directly.
+%
+% The line range for a separated chunk is calculated by
+% \begin{macrocode}
+ linerange = start "-" $1-1;
+ if ( command ) {
+ print_command(\
+ (identifier toB26(idPt++)), \
+ linerange);
+ } else {
+ print_linerange(\
+ (identifier toB26(idPt++)), \
+ caption, linerange);
+ }
+ }
+ } else if ( opening_tag != closing_tag ) {
+ print_error($1, "opening and closing tags differ")
+ } else {
+ print_error($1, "unknown error")
+ }
+ }
+ }
+ }
+}
+END {
+% \end{macrocode} ^^A $
+% There may be an erroneous open group, this is announced now.
+% \changes{v56}{10/03/09}{added handling of missing "ee" declarations}
+% \begin{macrocode}
+ if ( is_opened ) {
+ print_error($1, "missing \"ee\" declaration")
+ }
+% \end{macrocode} ^^A $
+% And now for the post processing \ldots
+% \begin{macrocode}
+ caption = "\\lstinline|" file "|";
+ if ( join ) {
+ sub(/, /, "", linerange);
+ if ( command ) {
+ print_command(identifier, linerange);
+ } else {
+ caption = "\\lstinline|" file "|";
+ print_linerange(identifier, caption, linerange);
+ }
+ } else if ( combine ) {
+ for ( range in combine_array ) {
+% \end{macrocode} ^^A $
+% In combine mode we prefix the |\lstdef|-command by the tag to make the
+% association easier.
+% \begin{macrocode}
+ if ( debugmode ) printf("range: %s, combine_array[range]: >%s<\n", \
+ range, combine_array[range]) > "/dev/stderr"
+ printf("%%%%-->> %s <<--\n", range)
+ if ( command ) {
+ print_command((identifier toB26(idPt++)), \
+ combine_array[range]);
+ } else {
+ print_linerange((identifier toB26(idPt++)), caption, \
+ combine_array[range]);
+ }
+ }
+ }
+}
+% \end{macrocode} ^^A $
+%
+% \changes{v25}{09/08/21}{corrected some leading spaces before the beginning
+% percent sign of a line}
+% Finally there are some helper functions. We start with
+% |replace_characters|. It replaces characters that are not allowed in
+% \TeX-commands like "\_", "\.-" from an identifier and turns
+% it into camel case notation. Its arguments are:
+% \begin{enumerate}
+% \item |identifier|---the identifier with underscore characters
+% \end{enumerate}
+% \begin{macrocode}
+function replace_characters(identifier) {
+ tmp = ""
+ toUppercase = 0
+ n = split(identifier, sequence, "") # split the string into an array
+ # of single characters
+ for ( i = 1; i <= n; i++ )
+ {
+ if ( (sequence[i] == "_") || (sequence[i] == "-") ) {
+ toUppercase = 1
+ } else {
+ if ( toUppercase ) {
+ cTmp = toupper(sequence[i])
+ tmp = (tmp cTmp)
+ toUppercase = 0
+ } else {
+ tmp = (tmp sequence[i])
+ }
+ }
+ }
+ return tmp
+}
+% \end{macrocode}
+%
+% |print_command| generates the |\lstdef|-line. Its arguments are:
+% \begin{enumerate}
+% \item |identifier|---the identifier, which can be used in the
+% \LaTeX-source to format a range of lines.
+% \item |linerange|---a linerange or a list of line ranges (in join or
+% combine mode)
+% \end{enumerate}
+% \begin{macrocode}
+function print_command(identifier, linerange) {
+ if ( debugmode ) printf("print_command.linerange: >%s<\n", linerange) > "/dev/stderr"
+ print break_line("\\lstdef{" identifier "}{" inputfile "}{" \
+ linerange "}", linelen)
+}
+% \end{macrocode}
+%
+% \changes{v65}{10/06/28}{added print\_break function call to print\_linerange}
+% |print_linerange| does something similar: instead of defining an identifier it
+% prints out a bunch of lines, which can be pasted into the
+% \LaTeX-source. Its arguments are
+% \begin{enumerate}
+% \item |identifier|---the identifier, an environment which has to be
+% defined in advance
+% \item |caption|---title or caption, taken either from surrounding
+% environment or from the file name (in join mode)
+% \item |linerange|---a linerange or a list of line ranges (in join or
+% combine mode)
+% \end{enumerate}
+% \begin{macrocode}
+function print_linerange(identifier, caption, linerange) {
+ print break_line(begin_prefix "begin{" \
+ identifier"}\n{%\n \\def\\inputfile{%\n " inputfile "%\n }");
+ local_style = "";
+ if ( header )
+ {
+ print " \\ifLecture{%\n \\lstdefinestyle{localStyle}{%\n " \
+ "caption={" caption"}\n }%\n }\n {%\n" \
+ " \\lstdefinestyle{localStyle}{%\n" \
+ " title={" caption "}\n }%\n }";
+ local_style="style=localStyle, "
+ }
+ print " \\lstinputlisting[" local_style "linerange={" linerange "}]" \
+ "{%\n \\inputfile\n }\n" \
+ "}%\n" end_prefix "end{"identifier"}";
+}
+% \end{macrocode}
+%
+% |print_error| prints out errors to stderr. Its arguments are
+% \begin{enumerate}
+% \item |linenumber|---the number of the line/record where the error happens
+% \item |error_message|---the error message
+% \end{enumerate}
+% \begin{macrocode}
+function print_error(linenumber, error_message)
+{
+ printf "%--> error (line number %d): %s\n", \
+ linenumber, error_message > "/dev/stderr"
+}
+% \end{macrocode}
+%
+% |break_line| breaks a (long) line into parts, which each have a length less
+% than a given line length. Its arguments are:
+% \begin{enumerate}
+% \item |input_line|---the line to bwe broken
+% \item |line_len|---the target length
+% \end{enumerate}
+% |input_line| may contain line breaks, so the results may look odd.
+% \begin{macrocode}
+function break_line(input_line, line_len) {
+ n = split(input_line, parts, "/");
+ output_line = parts[1];
+ len_curr = length(output_line)
+ for ( i = 2; i <= n; i++ ) {
+ len_next = length(parts[i])
+ if ( len_curr + len_next + 1 < linelen ) {
+ output_line = output_line "/" parts[i];
+ len_curr += len_next + 1 # continue current line
+ } else {
+ output_line = output_line "%\n /" parts[i];
+ len_curr = len_next + 7 # start a new line
+ }
+ }
+ return output_line
+}
+% \end{macrocode}
+%
+% \changes{v27}{09/08/21}{changed the conversion algorithm}
+% \changes{v25}{09/08/21}{changed the numbering of chunks by introducing the function
+% toB26}
+% |toB26| converts its integer argument into a number with the base
+% of 26, the number's digits are upper case characters. Its arguments are:
+% \begin{enumerate}
+% \item |n10|---the number to convert (base 10)
+% \end{enumerate}
+% \begin{macrocode}
+function toB26(n10) {
+ v26 = ""
+ do {
+ remainder = n10%26
+ v26 = idArray[remainder+1] v26
+ n10 = int(n10/26)
+ } while ( n10 != 0 )
+ return v26
+}
+'
+ return $?
+}
+
+if [ $# -eq 0 ]
+then
+ show_usage
+fi
+% \end{macrocode}
+% Processing the options is done by means of getop, see |man getopt|
+% \begin{macrocode}
+GETOPT=$(getopt -o ceghno:: \
+ --longoptions command,debug-mode,ext,help,no-header,output-file:: \
+ -n ${ME} -- "$@")
+
+if [ $? -ne 0 ] # no success
+then
+ show_usage
+fi
+
+eval set -- "$GETOPT"
+
+while true
+do
+ case "$1" in
+ -c|--command) COMMAND=1; HEADER=0; shift;;
+ -e|--ext) EXTENSION=1; shift;;
+ -g|--debug-mode) DEBUG_MODE=1; shift;;
+ -h|--help) show_usage ;;
+ -n|--no-header) HEADER=0; shift;;
+ -o|--output-file)
+% \end{macrocode}
+% |o| has an optional argument. As we are in quoted mode, an empty
+% parameter will be generated if its optional argument is not found.
+% \begin{macrocode}
+ case "$2" in
+ "") OUTFILE=$(basename $(pwd)).lst; shift 2 ;;
+ *) OUTFILE=$2; shift 2 ;;
+ esac ;;
+ --) shift ; break ;;
+ *) show_usage ;;
+ esac
+done
+% \end{macrocode}
+% If the output-file is set, redirect output to it's value.
+% \begin{macrocode}
+if [ -n "${OUTFILE}" ]
+then
+ if [ -f "${OUTFILE}" ]
+ then
+ printf "%s\n" "%--> file \"${OUTFILE}\" already exists, creating backup"
+ mv ${OUTFILE} ${OUTFILE}~
+ fi
+ exec > ${OUTFILE} # redirect stdout to ${OUTFILE}
+ CURR_DIR=$(basename $(pwd))
+ print_header ${OUTFILE} ${CURR_DIR}
+fi
+
+# now take all remaining arguments (should be all filenames) and do the job
+for arg do
+ printf "%s\n" "%%--> processing file \"$arg\"" 1>&2 # echo the current
+ # filename to stderr
+ do_the_job $arg
+done
+
+### listings-ext.sh ends here
+%</scriptfile>
+% \end{macrocode} ^^A $
+%
+%
+% \subsection[Example/Test Files]{Example and Test Files For Testing The Macros}
+% \label{sec:example-files}
+%
+% In this section there are introduced some examples of source code files
+% (C, Fortran and Java) and corresponding test files to show the behaviour
+% of the package and the script.
+%
+%
+% \subsubsection{A Small Java-Example With Correct Grouping}
+% \label{sec:small-java-example-correct}
+%
+% The correct (Java) source file is
+% \begin{macrocode}
+%<*example1>
+package application.helloworld;
+// be: packages
+import java.util.Locale;
+import java.util.MissingResourceException;
+import java.util.ResourceBundle;
+// ee: packages
+/**
+ * HelloWorld.java
+ */
+public class HelloWorld
+{
+ // be: specific constructor
+ public HelloWorld()
+ {
+ System.out.println("Object HelloWorld created");
+ } // end of specific constructor "HelloWorld()"
+ // ee: specific constructor
+
+ public static final void main(final String[] args)
+ {
+ String baseName = "HelloWorld";
+ // be: using the resource bundle
+ ResourceBundle rb = ResourceBundle.getBundle(baseName);
+ String greetings = rb.getString("hello_msg");
+ // ee: using the resource bundle
+ System.out.printf("%s\n", greetings);
+ } // end of method "main(String[] args)"
+} // end of class "HelloWorld"
+%</example1>
+% \end{macrocode}
+% We have two correct groups, the output for |-c| should contain
+% two lines like
+%\begin{verbatim}
+%\lstdef{listingsExtTestAA}{/home/xxx/texmf/source/latex%
+% /listings-ext/listings-ext_test_a.java}{3-5}
+%\lstdef{listingsExtTestAB}{/home/xxx/texmf/source/latex%
+% /listings-ext/listings-ext_test_a.java}{20-22}
+%\lstdef{listingsExtTestAC}{/home/xxx/texmf/source/latex%
+% /listings-ext/listings-ext_test_a.java}{29-30}
+%\end{verbatim}
+%
+% A small \LaTeX-file to test this case is
+%
+% \begin{macrocode}
+%<*test1>
+\documentclass[a4paper,12pt]{article}
+\usepackage[T1]{fontenc}
+\usepackage{listings-ext}
+\begin{document}
+\input{listings-ext.lst}
+\lstuse[style=bw-code, language=Java]{listingsExtExmplAC}
+\end{document}
+%</test1>
+% \end{macrocode}
+%
+%
+% \subsubsection{Small Java-Examples With Wrong Initialisation or Ending}
+% \label{sec:small-java-example-wrong-initialisation}
+%
+% In the following Java source code the initial tag \verb*-be: - is
+% missing. Processing the file by |listings-ext.sh| must give an
+% appropriate error message.
+% \begin{macrocode}
+%<*example2>
+// ee: package declaration
+package application.helloworld;
+// ee: package declaration
+import java.util.Locale;
+import java.util.MissingResourceException;
+import java.util.ResourceBundle;
+
+/**
+ * HelloWorld.java
+ */
+
+public class HelloWorld
+{
+ // be: specific constructor
+ public HelloWorld()
+ {
+ System.out.println("Object HelloWorld created");
+ } // end of specific constructor "HelloWorld()"
+ // ee: specific constructor
+
+ public static final void main(final String[] args)
+ {
+ String baseName = "HelloWorld";
+ ResourceBundle rb = ResourceBundle.getBundle(baseName);
+ String greetings = rb.getString("hello_msg");
+ System.out.printf("%s\n", greetings);
+ } // end of method "main(String[] args)"
+} // end of class "HelloWorld"
+%</example2>
+% \end{macrocode}
+%
+% \changes{v56}{10/03/09}{added test case for missing "ee" declarations}
+% In the following Java source code the closing tag \verb*-ee: - is
+% missing. Processing the file by |listings-ext.sh| must give an
+% appropriate error message.
+% \begin{macrocode}
+%<*example3>
+package application.helloworld;
+import java.util.Locale;
+import java.util.MissingResourceException;
+import java.util.ResourceBundle;
+
+/**
+ * HelloWorld.java
+ */
+
+public class HelloWorld
+{
+ // be: specific constructor
+ public HelloWorld()
+ {
+ System.out.println("Object HelloWorld created");
+ } // end of specific constructor "HelloWorld()"
+ // ee: specific constructor
+
+ // be: the main method
+ public static final void main(final String[] args)
+ {
+ String baseName = "HelloWorld";
+ ResourceBundle rb = ResourceBundle.getBundle(baseName);
+ String greetings = rb.getString("hello_msg");
+ System.out.printf("%s\n", greetings);
+ } // end of method "main(String[] args)"
+} // end of class "HelloWorld"
+%</example3>
+% \end{macrocode}
+%
+% \subsubsection{A Small Java-Example With Correct Grouping}
+% \label{sec:small-java-example-correct}
+%
+% \changes{v58}{10/05/18}{corrected example 4}
+% \begin{macrocode}
+%<*example4>
+package application.helloworld;
+// be: packages
+import java.util.Locale;
+import java.util.MissingResourceException;
+import java.util.ResourceBundle;
+// ee: packages
+// be: introductory comment
+/**
+ * HelloWorld.java
+ *
+ *
+ * <br>
+ * Created: : 2007/04/12 11:24:48$
+ *
+ * @author <a href="mailto:N.N_(at)_fh-aachen.de">N.N.</a>
+ * @version : 0.0$
+ */
+// ee: introductory comment
+// be: class declaration
+public class HelloWorld
+// ee: class declaration
+{
+ // be: specific constructor
+ public HelloWorld()
+ {
+ System.out.println("Object HelloWorld created");
+ } // end of specific constructor "HelloWorld()"
+ // ee: specific constructor
+
+ public static final void main(final String[] args)
+ {
+ String baseName = "HelloWorld";
+ // ee: using the resource bundle
+ ResourceBundle rb = ResourceBundle.getBundle(baseName);
+ String greetings = rb.getString("hello_msg");
+ // ee: using the resource bundle
+ System.out.printf("%s\n", greetings);
+ } // end of method "main(String[] args)"
+} // end of class "HelloWorld"
+%</example4>
+% \end{macrocode}
+%
+% \changes{v11}{09/04/15}{added a test for combine mode}
+% \subsubsection{A Small Java-Example With Correct Grouping, Showing the
+% Combine Mode}
+% \label{sec:java-combine}
+%
+% We have two correct groups, |ce| at the beginning of the file sets the
+% combine mode, so the output for |-c| should contain three lines like
+%\begin{verbatim}
+%\lstdef{listingsExtTestDA}{/home/xxx/texmf/source/latex%
+% /listings-ext/listings-ext_test_a.java}{12-13, 29-29}
+%\lstdef{listingsExtTestDB}{/home/xxx/texmf/source/latex%
+% /listings-ext/listings-ext_test_a.java}{16-19}
+%\lstdef{listingsExtTestDC}{/home/xxx/texmf/source/latex%
+% /listings-ext/listings-ext_test_a.java}{23-26}
+%\end{verbatim}
+%
+% \begin{macrocode}
+%<*example5>
+// ce: combine
+/**
+ * HelloWorld.java
+// be: the class
+public class HelloWorld
+{
+// ee: the class
+ // be: specific constructor
+ public HelloWorld()
+ {
+ System.out.println("Object HelloWorld created");
+ } // end of specific constructor "HelloWorld()"
+ // ee: specific constructor
+
+ // be: main method
+ public static final void main(final String[] args)
+ {
+ HelloWorld h = new HelloWorld();
+ } // end of method "main(String[] args)"
+ // ee: main method
+// be: the class
+} // end of class "HelloWorld"
+// ee: the class
+%</example5>
+% \end{macrocode}
+%
+% The result of the call |listings-ext.sh -c -o listings-ext_test_d.java|
+% must contain the lines
+% \begin{verbatim}
+% %-->> main method <<--
+% \lstdef{listingsExtExmplDA}{/home/ax006ho/TeX/texmf/source/latex%
+% /listings-ext%
+% /listings-ext_exmpl_d.java}{16-19}
+% %-->> the class <<--
+% \lstdef{listingsExtExmplDB}{/home/ax006ho/TeX/texmf/source/latex%
+% /listings-ext%
+% /listings-ext_exmpl_d.java}{5-6, 22-22}
+% %-->> specific constructor <<--
+% \lstdef{listingsExtExmplDC}{/home/ax006ho/TeX/texmf/source/latex%
+% /listings-ext%
+% /listings-ext_exmpl_d.java}{9-12}
+% \end{verbatim}
+%
+% So a small \LaTeX-file to test this case is
+%
+% \begin{macrocode}
+%<*test2>
+\documentclass[a4paper,12pt]{article}
+\usepackage[T1]{fontenc}
+\usepackage[style=colored-code]{listings-ext}
+\begin{document}
+\lstcheck{listingsExtExmplDC}{listings-ext.lst}
+\lstuse[language=Java]{listingsExtExmplDC}
+\end{document}
+%</test2>
+% \end{macrocode}
+%
+%
+% \changes{v16}{09/08/18}{enhanced the .el-file}
+% \subsection[AUC\TeX{} Style file]{Style file for AUC\TeX{} to ease the
+% Editing with \XEmacs{}}
+% \label{sec:AUCTeX}
+%
+% \XEmacs{} and the package AUC\TeX{}
+% (\url{http://www.gnu.org/software/auctex/}) form a powerful tool for
+% creating and editing of \TeX/\LaTeX{} files. If there is a suitable
+% AUCTeX style file for a \LaTeX{} package like the hereby provided
+% \listingsextSty{} package, then there is support for many common
+% operations like creating environments, inserting macros, prompting for
+% arguments and so on. The following elisp code provides such a style
+% file; it must be copied to a place, where \XEmacs{} can find it after its
+% creation.%
+%
+% This file is still in a development phase, i.\,e. one can work with it,
+% but there is a couple of missing things as for example font locking or
+% the automatic insertion of \cs{switch} commands according to the user's
+% input.
+%
+% \begin{macrocode}
+%<*auctex>
+;;; listings-ext.el --- AUCTeX style for `listings-ext.sty'
+
+;; Copyright (C) 2008-2010 Free Software Foundation, Inc.
+
+;; Maintainer: Jobst Hoffmann, <j.hoffmann_(at)_fh-aachen.de>
+;; $Author: ax006ho $
+;; $Date: 2010-06-29 18:38:12 +0200 (Di, 29 Jun 2010) $
+;; $Revision: 67 $
+;; Keywords: tex
+
+;;; Commentary:
+;; This file adds support for `listings-ext.sty'
+
+;;; Code:
+(TeX-add-style-hook
+ "listings-ext"
+ (lambda ()
+ (TeX-add-symbols
+ '("lstcheck" "identifier" TeX-arg-input-file 0)
+ '("lstdef" "identifier" TeX-arg-input-file "line range" 0)
+ '("lstuse" ["options"] "identifier"0))
+
+ ;; Filling
+
+ ;; Fontification
+ (when (and (featurep 'font-latex)
+ (eq TeX-install-font-lock 'font-latex-setup))
+ (add-to-list 'font-latex-match-function-keywords-local "lstcheck")
+ (add-to-list 'font-latex-match-function-keywords-local "lstdef")
+ (add-to-list 'font-latex-match-function-keywords-local "lstuse")
+ (font-latex-match-function-make)
+ ;; For syntactic fontification, e.g. verbatim constructs
+ (font-latex-set-syntactic-keywords)
+ ;; Tell font-lock about the update.
+ (setq font-lock-set-defaults nil)
+ (font-lock-set-defaults))))
+
+;; preparing of environments isn't necessary
+
+;; support for options
+(defvar LaTeX-listings-ext-package-options nil
+ "Package options for the listings-ext package.")
+
+;;; listings-ext.el ends here.
+%</auctex>
+% \end{macrocode}
+%
+%
+% \changes{v50}{10/02/15}{small changes to the Makefile: main documentation now in .pdf-format}
+% \changes{v47}{09/08/31}{removed unnecessary files from the distribution}
+% \changes{v45}{09/08/31}{some small corrections for the test files}
+% \changes{v41}{09/08/27}{Makefile: removed TODO from the distributed tar-file}
+% \changes{v38}{09/08/27}{Makefile: corrected the examples-part}
+% \changes{v33}{09/08/23}{Makefile: now all targets are described}
+% \changes{v33}{09/08/23}{Makefile: mirrored the move from rcs to subversion}
+% \changes{v33}{09/08/23}{Makefile: introduced implicit rules}
+% \changes{v33}{09/08/23}{Makefile: removed some small glitches}
+% \changes{v16}{09/08/18}{better documentation of the Makefile}
+% \changes{v16}{09/08/18}{removed unnecessary code from the Makefile}
+% \changes{v16}{09/08/18}{corrected small glitches in the Makefile}
+% \subsection[Makefile]{%
+% Makefile for the automated generation of the documentation and tests
+% of the \listingsextSty}
+% \label{sec:Makefile}
+%
+% Working with \ext{.dtx}-packages is much easier, if there is a tool
+% for the automated processing of the mean steps like formatting or
+% unpacking. For systems based on Unix/Linux one can implement that with
+% |make| and a an adequate |Makefile|. Here the |Makefile| is integrated
+% into the documentation, the special syntax with tabulator characters is
+% generated by a short program, which is shown below. Using the |Makefile|
+% isn't explained here, the experienced user can get this information
+% directly from the |Makefile|.
+%
+% \changes{v03}{08/02/27}{remove the intermediate PostScript file after
+% generating the .pdf-output from it}
+% \begin{macrocode}
+%<*makefile>
+#-----------------------------------------------------------------------
+# Purpose: generation of the documentation of the listings-ext package
+# Notice: this file can be used without any change only with dmake and
+# the option "-B", this option lets dmake interpret the leading
+# spaces as distinguishing characters for commands in the make
+# rules.
+# The necessary changes for the common make can be applied by
+# the script listings-ext.makemake
+#
+# Rules:
+# - all: generate all the files and the basic
+# documentation
+# - develop: generate the documentation with revision
+# - develop-pdf: history and source code (the latter provides
+# a .pdf file as output)
+# - history: generate the documentation with revision
+# - history-pdf: history (the latter provides a .pdf file as
+# output)
+# - examples: format the examples
+# - install: install the package in a standard TDS tree
+# - uninstall: uninstall the package from a standard TDS
+# tree
+# - clean: clean the directory of intermediate files
+# - clean-examples: example and test files
+# - clean-support: support files
+# - realclean: all but the pure source
+# files
+# - tar-src: create a gzipped .tar-file of the pure
+# source files
+# - tar-dist: create a gzipped .tar-file containing
+# version information
+#
+# Author: Jobst Hoffmann, Fachhochschule Aachen, Campus Juelich
+# $Date: 2010-06-29 18:38:12 +0200 (Di, 29 Jun 2010) $
+#-----------------------------------------------------------------------
+
+# The texmf-directory, where to install new stuff (see texmf.cnf)
+# If you don't know what to do, search for directory texmf at /usr.
+# With teTeX and linux often one of following is used:
+#INSTALLTEXMF=/usr/TeX/texmf
+#INSTALLTEXMF=/usr/local/TeX/texmf
+#INSTALLTEXMF=/usr/share/texmf
+#INSTALLTEXMF=/usr/local/share/texmf
+# user tree:
+#INSTALLTEXMF=$(HOME)/texmf
+# Try to use user's tree known by kpsewhich:
+INSTALLTEXMF=`kpsewhich --expand-var '$$TEXMFHOME'`
+# Try to use the local tree known by kpsewhich:
+#INSTALLTEXMF=`kpsewhich --expand-var '$$TEXMFLOCAL'`
+# But you may set INSTALLTEXMF to every directory you want.
+# Use the following, if you only want to test the installation:
+#INSTALLTEXMF=/tmp/texmf
+
+# If texhash must run after installation, you can invoke this:
+TEXHASH=texhash
+
+# change this to the directory which contains the graphic files
+GRAPHICPATH=.
+
+######### Edit the following only, if you want to change defaults!
+
+# The directory, where to install *.cls and *.sty
+CLSDIR=$(INSTALLTEXMF)/tex/latex/jhf/$(PACKAGE)
+
+# The directory, where to install documentation
+DOCDIR=$(INSTALLTEXMF)/doc/latex/jhf/$(PACKAGE)
+
+# The directory, where to install the sources
+SRCDIR=$(INSTALLTEXMF)/source/latex/jhf/$(PACKAGE)
+
+# The directory, where to install demo-files
+# If we have some, we have to add following 2 lines to install rule:
+# $(MKDIR) $(DEMODIR); \
+# $(INSTALL) $(DEMO_FILES) $(DEMODIR); \
+DEMODIR=$(DOCDIR)/demo
+
+# We need this, because the documentation needs the classes and packages
+# It's not really a good solution, but it's a working solution.
+TEXINPUTS := $(PWD):$(TEXINPUTS)
+
+# To generate the version number of the distribution from the source
+VERSION_L := latex getversion | grep '^VERSION'
+VERSION_S := `latex getversion | grep '^VERSION' | \
+ sed 's+^VERSION \\(.*\\) of .*+\\1+'`
+########################################################################
+# End of customization section
+########################################################################
+
+# formatting tools
+BIBTEX = bibtex
+DVIPS = dvips
+LATEX = latex
+PDFLATEX = pdflatex
+TEX = tex
+PS2PDF = ps2pdf
+
+# postscript viewer
+GV = gv
+
+# tarring options
+DATE = `date +%Y-%m-%d`
+TAR_SRC = $(PACKAGE)_$(DATE)_source.tar.gz
+EXsvn = --exclude .svn --exclude auto
+
+# formatting options
+COMMON_OPTIONS =
+HISTORY_OPTIONS = \RecordChanges
+DEVELOPER_OPTIONS = \AlsoImplementation\RecordChanges\CodelineIndex\EnableCrossrefs
+DEVELOPER_OPTIONS_FINAL = \AlsoImplementation\CodelineIndex\DisableCrossrefs\RecordChanges
+
+PACKAGE = listings-ext
+
+DISTRIBUTION_FILES = $(PACKAGE).pdf $(PACKAGE).dtx \
+ $(PACKAGE).ins README
+
+.SUFFIXES: # Delete the default suffixes
+.SUFFIXES: .dtx .dvi .ins .ps .pdf .sty # Define our suffix list
+
+## Main Targets
+
+# strip off the comments from the package
+$(PACKAGE).sty $(PACKAGE)-test-*.tex: $(PACKAGE).ins $(PACKAGE).dtx
+ +$(LATEX) $<; \
+ sh $(PACKAGE).makemake
+
+all: $(PACKAGE).dvi
+
+# generate the documentation
+$(PACKAGE).dvi: $(PACKAGE).dtx $(PACKAGE).sty
+ +rm -f *.ind *.gls
+ +$(LATEX) "\AtBeginDocument{$(COMMON_OPTIONS)}\input{$<}"
+ +$(BIBTEX) $(PACKAGE)
+ +$(LATEX) "\AtBeginDocument{$(COMMON_OPTIONS)}\input{$<}"
+ +$(LATEX) "\AtBeginDocument{$(COMMON_OPTIONS)}\input{$<}"
+
+# generate the documentation with revision history
+history: $(PACKAGE).dtx $(PACKAGE).sty
+ +$(LATEX) "\AtBeginDocument{$(COMMON_OPTIONS)$(HISTORY_OPTIONS)}\input{$<}"
+ +$(BIBTEX) $(PACKAGE)
+ +$(LATEX) "\AtBeginDocument{$(COMMON_OPTIONS)$(HISTORY_OPTIONS)}\input{$<}"
+ +makeindex -s gind.ist $(PACKAGE).idx
+ +makeindex -s gglo.ist -o $(PACKAGE).gls -t $(PACKAGE).glg $(PACKAGE).glo
+ +$(LATEX) "\AtBeginDocument{$(COMMON_OPTIONS)$(HISTORY_OPTIONS)}\input{$<}"
+
+# generate the documentation for the developer
+develop: $(PACKAGE).dtx $(PACKAGE).sty
+ +$(LATEX) "\AtBeginDocument{$(DEVELOPER_OPTIONS)}\input{$<}"
+ +$(BIBTEX) $(PACKAGE)
+ +$(LATEX) "\AtBeginDocument{$(DEVELOPER_OPTIONS)}\input{$<}"
+ +makeindex -s gind.ist $(PACKAGE).idx
+ +makeindex -s gglo.ist -o $(PACKAGE).gls -t $(PACKAGE).glg $(PACKAGE).glo
+ +$(LATEX) "\AtBeginDocument{$(DEVELOPER_OPTIONS_FINAL)}\input{$<}"
+
+develop-pdf: develop
+ +$(DVIPS) $(PACKAGE).dvi; \
+ $(PS2PDF) $(PACKAGE).ps; \
+ rm $(PACKAGE).ps
+
+history-pdf: history
+ +$(DVIPS) $(PACKAGE).dvi; \
+ $(PS2PDF) $(PACKAGE).ps; \
+ rm $(PACKAGE).ps
+
+# implicit rule for generating the .pdf files
+%%%.pdf: %.dvi
+ +$(DVIPS) $<; \
+ $(PS2PDF) $(<:.dvi=.ps); \
+ rm $(<:.dvi=.ps)
+
+# format the example/test files
+examples:
+ sh listings-ext.sh -c -o *.java; \
+ for i in $(PACKAGE)*test*.tex; do \
+ f=$${i%.tex}; \
+ $(LATEX) "\nofiles\input{$$f}"; \
+ $(DVIPS) -o $$f.ps $$f.dvi; \
+ $(PS2PDF) $$f.ps; \
+ rm $$f.dvi $$f.ps; \
+ done
+
+install: $(PACKAGE).dtx $(PACKAGE).pdf
+ [ -d $(CLSDIR) ] || mkdir -p $(CLSDIR)
+ [ -d $(DOCDIR) ] || mkdir -p $(DOCDIR)
+ [ -d $(SRCDIR) ] || mkdir -p $(SRCDIR)
+ cp $(PACKAGE).sty $(CLSDIR)
+ cp $(PACKAGE).pdf $(DOCDIR)
+ cp $(PACKAGE).ins $(SRCDIR)
+ cp $(PACKAGE).dtx $(SRCDIR)
+ cp $(PACKAGE)_{exmpl,test}_* $(SRCDIR)
+ cp README $(SRCDIR)
+ cp THIS-IS-VERSION-$(VERSION) $(SRCDIR)
+
+uninstall:
+ rm -f $(CLSDIR)/$(PACKAGE).sty
+ rm -fr $(DOCDIR)
+ rm -fr $(SRCDIR)
+
+## Clean Targets
+clean:
+ -rm -f *.aux *.dvi *.hd *.lof *.log *.lot *.tmp *.toc
+ -rm -f *.idx *.ilg *.ind *.glg *.glo *.gls *.out
+ -rm -f *.bbl *.blg *.bm *.brf *.hd
+ -rm -f *.pdf *.ps
+ -rm -f *.rel *.thm
+
+clean-examples:
+ -rm -f $(PACKAGE)_test* $(PACKAGE)_exmpl*
+
+clean-support:
+ -rm -f *.el *.sh
+ -rm -f *.mk *.makemake
+
+realclean: clean clean-examples clean-support
+ -rm -f *~ *.bib *.cfg *.sty *.tex
+ -rm -f Makefile
+
+### create packed files
+tar-src:
+ $(MAKE) realclean
+ @cd ..; tar $(EXsvn) -czvf $(PACKAGE)/$(TAR_SRC) $(PACKAGE)
+
+tar-dist: $(DISTRIBUTION_FILES)
+ +rm -f THIS_IS_VERSION_* *.tgz; \
+ $(VERSION_L) > THIS_IS_VERSION_$(VERSION_S); \
+ tar cfvz $(PACKAGE)-$(VERSION_S).tgz $^ THIS_IS_VERSION_*; \
+ rm getversion.log
+%</makefile>
+% \end{macrocode} ^^A $
+%
+% The following line -- stripped off as |listings-ext.makemake| -- can
+% be used with the command
+% \begin{verbatim}
+% sh listings-ext.makemake
+% \end{verbatim}
+% to generate the file |Makefile|, which can be further used to
+% generate the documentation with a common |make| like the GNU |make|.
+% \changes{v58}{10/05/18}{changed the .setup contents}
+% \begin{macrocode}
+%<*setup>
+#! /bin/sh
+
+sed -e "`echo \"s/^ /@/g\" | tr '@' '\011'`" listings-ext.mk > Makefile && \
+ rm listings-ext.mk
+%</setup>
+% \end{macrocode}
+%
+%
+% \changes{v50}{10/02/15}{added title to the section "getting the revision"}
+% \subsection{Automated Determining of the Revision Number}
+% \label{sec:automated-determining}
+%
+% The purpose of the following file is to determine the version of the
+% package for the case of creating a distribution version of the package.
+% \changes{v33}{09/08/23}{changed getversion.tex: introduced the date}
+% \begin{macrocode}
+%<*getversion>
+\documentclass{ltxdoc}
+\nofiles
+\usepackage{listings-ext}
+\GetFileInfo{listings-ext.sty}
+\typeout{VERSION \fileversion\space of \filedate}
+\begin{document}
+\end{document}
+%</getversion>
+% \end{macrocode}
+%
+% \Finale
+%
+%
+% \iffalse
+%<*bibtex>
+@Book{lingnau07:_latex_hacks,
+ author = {Anselm Lingnau},
+ title = {\LaTeX-Hacks},
+ publisher = {O'Reilly},
+ year = 2007,
+ address = {Beijing; Cambridge; Farnham; K\"oln; Paris; Sebastopol;
+ Taipei; Tokyo},
+ edition = {1.},
+ note = {Tipps \& Techniken f\"ur den professionellen Textsatz},
+ language = {ngerman},
+}
+@Manual{Heinz:Listings-14,
+ author = {Carsten Heinz and Brooks Moses},
+ title = {The \textsf{listings} package},
+ note = {Version 1.4},
+ year = 2007,
+ month = FEB,
+ language = {english}
+}
+@Manual{FM:TheDocAndShortvrbPackages,
+ author = {Frank Mittelbach},
+ title = {{The {\sf doc} and {\sf shortvrb} Packages}},
+ year = 2006,
+ month = FEB,
+ note = {version number 2.1d},
+ language = {english}
+}
+@Manual{MittelbachDuchierBraams:DocStrip,
+ author = {Frank Mittelbach and Denys Duchier and Johannes Braams
+ and Marcin Woli\'nski and Mark Wooding},
+ title = {{The {\sf DocStrip} program}},
+ year = 2005,
+ month = JUL,
+ note = {version number 2.5d},
+ language = {english}
+}
+%</bibtex>
+%<*hyperref>
+\ProvidesFile{hyperref.cfg}%
+ [2009/08/23 v1.0 hyperref configuration of listings-ext]
+% Change default driver to "dvips" instead of "hypertex",
+% requires hyperref 2002/06/05 v6.72s
+\providecommand*{\Hy@defaultdriver}{hdvips}%
+
+\hypersetup{
+ ps2pdf, % the documentation uses ps2pdf
+ colorlinks, % display links in the text coloured
+ pdfpagemode=UseOutlines,
+ plainpages=false,
+ pagebackref=true, % one can jump from the bibliography to the
+ % origin of the citations
+ hyperindex=true, % index is linked
+ bookmarks=true, % I want Acrobat bookmarks,
+ bookmarksopen=true, % they should be shown when the foils
+ % are displayed
+ bookmarksnumbered=true, % numbering is on
+ pdftitle={listings-ext},
+ pdfsubject={A collection of LaTeX macros to support the automatic
+ integration of parts of source files into a documentation}
+ pdfauthor={Jobst Hoffmann,
+ Fachhochschule Aachen J\"ulich Campus,
+ <j.hoffmann_(at)_fh-aachen.de>},
+ pdfkeywords={PDF, TeX, LaTeX, listings},
+}
+%</hyperref>
+% \fi
+\endinput
+%
+%% \CharacterTable
+%% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
+%% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
+%% Digits \0\1\2\3\4\5\6\7\8\9
+%% Exclamation \! Double quote \" Hash (number) \#
+%% Dollar \$ Percent \% Ampersand \&
+%% Acute accent \' Left paren \( Right paren \)
+%% Asterisk \* Plus \+ Comma \,
+%% Minus \- Point \. Solidus \/
+%% Colon \: Semicolon \; Less than \<
+%% Equals \= Greater than \> Question mark \?
+%% Commercial at \@ Left bracket \[ Backslash \\
+%% Right bracket \] Circumflex \^ Underscore \_
+%% Grave accent \` Left brace \{ Vertical bar \|
+%% Right brace \} Tilde \~}
+%
+%%% ^^A Local Variables:
+%%% ^^A mode: docTeX
+%%% ^^A TeX-master: t
+%%% ^^A mode: flyspell
+%%% ^^A ispell-local-dictionary: "english"
+%%% ^^A End:
+%
+% end of listings-ext.dtx
diff --git a/macros/latex/contrib/listings-ext/listings-ext.ins b/macros/latex/contrib/listings-ext/listings-ext.ins
new file mode 100644
index 0000000000..dc480f8e4d
--- /dev/null
+++ b/macros/latex/contrib/listings-ext/listings-ext.ins
@@ -0,0 +1,123 @@
+%%
+%% $Revision: 55 $
+%%
+%% This file will generate fast loadable files and documentation
+%% driver files from the .dtx files in this package when run through
+%% LaTeX or TeX.
+%%
+%% IMPORTANT COPYRIGHT NOTICE:
+%%
+%% No other permissions to copy or distribute this file in any form
+%% are granted and in particular NO PERMISSION to modify its contents.
+%%
+%% You are NOT ALLOWED to change this file.
+%%
+%% --------------- start of docstrip commands ------------------
+%%
+\def\batchfile{listings-ext.ins}
+\input docstrip.tex
+
+\preamble
+
+Copyright (C) 2008-2010 Jobst Hoffmann, <j.hoffmann (at) fh-aachen.de>, all rights reserved
+--------------------------------------------------------------------------------------
+
+This file may be distributed and/or modified under the
+conditions of the LaTeX Project Public License, either version 1.2
+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.2 or later is part of all distributions of LaTeX
+version 1999/12/01 or later.
+
+Please address error reports and any problems in case of UNCHANGED versions
+to
+ j.hoffmann (at) fh-aachen.de
+\endpreamble
+
+\declarepostamble\examplepost
+\endpostamble
+
+%\BaseDirectory{~/TeX/texmf}
+%\UseTDS
+%\usedir{tex/latex/jhf}
+
+\keepsilent
+\askonceonly
+
+%\def\targetdirectory{} % or may be for example
+%\def\targetdirectory{./../../texmf/tex/latex/jhf}
+
+
+% programs and packages
+
+\Msg{*** Generating the package files ***}
+
+\generate%
+{%
+ \askforoverwritefalse
+ \file{listings-ext.sty}{%
+ \from{listings-ext.dtx}{extension}}
+}
+
+\Msg{*** Generating the test and example files ***}
+
+\preamble
+\endpreamble
+\generate%
+{%
+ \askforoverwritefalse
+ \nopreamble\nopostamble\def\MetaPrefix{}%
+ \file{listings-ext_exmpl_a.java}{\from{listings-ext.dtx}{example1}}
+ \file{listings-ext_exmpl_b.java}{\from{listings-ext.dtx}{example2}}
+ \file{listings-ext_exmpl_c.java}{\from{listings-ext.dtx}{example3}}
+ \file{listings-ext_exmpl_d.java}{\from{listings-ext.dtx}{example4}}
+ \file{listings-ext_exmpl_e.java}{\from{listings-ext.dtx}{example5}}
+ \file{listings-ext_test_a.tex}{\from{listings-ext.dtx}{test1}}
+ \file{listings-ext_test_d.tex}{\from{listings-ext.dtx}{test2}}
+}
+
+\Msg{*** Generating make file and make setup file ***}
+\generate
+{%
+ \nopreamble\nopostamble\def\MetaPrefix{}%
+ \file{getversion.tex}{\from{listings-ext.dtx}{getversion}}%
+ \file{hyperref.cfg}{\from{listings-ext.dtx}{hyperref}}%
+ \file{listings-ext.bib}{\from{listings-ext.dtx}{bibtex}}%
+ \file{listings-ext.el}{\from{listings-ext.dtx}{auctex}}%
+ \file{listings-ext.mk}{\from{listings-ext.dtx}{makefile}}%
+ \file{listings-ext.makemake}{\from{listings-ext.dtx}{setup}}%
+ \file{listings.cfg}{\from{listings-ext.dtx}{listings}}%
+}
+
+\Msg{*** Generating the script file ***}
+\generate
+{%
+ \nopreamble\nopostamble\def\MetaPrefix{}%
+ \file{listings-ext.sh}{\from{listings-ext.dtx}{scriptfile}}%
+}
+
+\ifToplevel{%
+\Msg{***********************************************************}
+\Msg{*}
+\Msg{* To finish the installation you have to move the following}
+\Msg{* style file(s) into a directory searched by TeX:}
+\Msg{*}
+\Msg{* \space\space listings-ext.sty}
+\Msg{*}
+\Msg{* To produce the documentation run the file(s) ending with}
+\Msg{* `.dtx' through LaTeX.}
+\Msg{*}
+\Msg{* Happy TeXing}
+\Msg{***********************************************************}
+}
+
+\endinput
+%%% Local Variables:
+%%% mode: latex
+%%% TeX-master: t
+%%% mode: flyspell
+%%% ispell-local-dictionary: "english"
+%%% End:
diff --git a/macros/latex/contrib/listings-ext/listings-ext.pdf b/macros/latex/contrib/listings-ext/listings-ext.pdf
new file mode 100644
index 0000000000..fcd79a717a
--- /dev/null
+++ b/macros/latex/contrib/listings-ext/listings-ext.pdf
Binary files differ