path: root/Master/texmf-dist/source/latex/listings-ext/listings-ext.dtx

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