Debian Codegraph @

texmf-dist/source/latex/listings-ext/listings-ext.dtx

raw
1 % \iffalse meta-comment
2 %
3 % Copyright (C) 2008-2010 Jobst Hoffmann, FH Aachen, Campus J\"ulich <j.hoffmann_(at)_fh-aachen.de>
4 % -----------------------------------------------------------------------------------------
5 %
6 % This file may be distributed and/or modified under the
7 % conditions of the LaTeX Project Public License, either version 1.2
8 % of this license or (at your option) any later version.
9 % The latest version of this license is in:
10 %
11 % http://www.latex-project.org/lppl.txt
12 %
13 % and version 1.2 or later is part of all distributions of LaTeX
14 % version 1999/12/01 or later.
15 %
16 % \fi
17 %
18 %
19 % \changes{v67}{10/06/29}{removed some needless blanks}
20 % \changes{v67}{10/06/29}{email adresses are obfuscated now}
21 % \changes{v58}{10/05/18}{moved the docstrip guards into the corresponding macrocode environments}
22 % \changes{v56}{10/03/09}{some small layout changes}
23 % \changes{v37}{09/08/27}{changed the copyright message again}
24 % \changes{v11}{09/04/15}{changed the Copyright message}
25 % \changes{v16}{09/08/18}{replaced macroname rcs by svn}
26 % \iffalse
27 %<extension>\NeedsTeXFormat{LaTeX2e}[1995/12/01]
28 %<extension>{%
29 %<extension> \def\@svn@ $#1Date: #2-#3-#4 #5$$#6Revision: #7$ {%
30 %<extension> \ProvidesPackage{listings-ext}[#2/#3/#4 v#7 an extension for the listings package (JHf)]}
31 %<extension> \@svn@ $Date: 2010-06-29 18:38:12 +0200 (Di, 29 Jun 2010) $$Revision: 67 $ %
32 %<extension>}
33 % \fi
34 % \CheckSum{363}
35 % \changes{v41}{09/08/27}{removed typos again}
36 % \def\docdate {10/06/29} ^^A not style'able!!
37 %
38 % \changes{v11}{09/04/15}{turned german documentation into an english one}
39 %\iffalse
40 %
41 % Package `listings-ext' for use with LaTeX v2e
42 % Copyright (C) 2008-2010 Jobst Hoffmann <j.hoffmann (at) fh-aachen.de>, all rights reserved.
43 % -----------------------------------------------------------------
44 %
45 % This file may be distributed and/or modified under the
46 % conditions of the LaTeX Project Public License, either version 1.2
47 % of this license or (at your option) any later version.
48 % The latest version of this license is in:
49 %
50 % http://www.latex-project.org/lppl.txt
51 %
52 % and version 1.2 or later is part of all distributions of LaTeX
53 % version 1999/12/01 or later.
54 %
55 % Address your error messages to:
56 % Jobst Hoffmann
57 % Fachhochschule Aachen, Campus J"ulich
58 % Ginsterweg 1
59 % 52428 J"ulich
60 % Bundesrepublik Deutschland
61 % Email: <j.hoffmann_(at)_fh-aachen.de>
62 %
63 %\fi
64 %
65 % \def\listingsextSty{{\sf listings-ext.sty}}
66 % \def\listingsext{{\sf listings-ext}}
67 %
68 % \changes{v33}{09/08/23}{updated `DoNotIndex list}
69 % \DoNotIndex{\ ,\!,\C,\[,\\,\],\^,\`,\{,\},\~,\<,\=, \", \|}
70 % \DoNotIndex{\@ifundefined,\@ne, \@spaces, \author}
71 % \DoNotIndex{\catcode, \copyright, \def, \docdate, \documentclass}
72 % \DoNotIndex{\else,\endinput,\expandafter,\fi,\filedate,\fileversion}
73 % \DoNotIndex{\gdef,\global,\ifnum,\ifx,\let,\long}
74 % \DoNotIndex{\newcount,\newdimen,\newif,\next,\space,\string}
75 % \DoNotIndex{\the,\xdef,\z@}
76 % \DoNotIndex{\@@par, \@empty, \@hangfrom, \@reffalse, \@reftrue,}
77 % \DoNotIndex{\advance, \Alph, \alph, \arabic, \arraystretch, \baselineskip}
78 % \DoNotIndex{\begin}
79 % \DoNotIndex{\bgroup, \bigskip, \box, \bullet, \cdot, \centering}
80 % \DoNotIndex{\columnwidth, \csname, \day, \divide, \dotfill, \dp}
81 % \DoNotIndex{\edef, \egroup, \empty, \end, \endcsname, \font, \footins, \foo}
82 % \DoNotIndex{\frenchspacing, \hbadness, \hbox, \hfil, \hfill, \hline}
83 % \DoNotIndex{\hrule, \hsize, \hskip, \hspace, \hss, \ht, \ifcase}
84 % \DoNotIndex{\ifdim, \ifodd}
85 % \DoNotIndex{\ifvmode, \ignorespaces, \input, \interlinepenalty, \item}
86 % \DoNotIndex{\itemindent, \kern, \L, \large, \leaders, \list, \listparindent}
87 % \DoNotIndex{\magstep}
88 % \DoNotIndex{\magstephalf, \makelabel, \MakeShortVerb, \marginpar}
89 % \DoNotIndex{\mark, \mbox, \month, \multicolumn, \newpage, \newcommand}
90 % \DoNotIndex{\nobreak, \noexpand, \noindent}
91 % \DoNotIndex{\normalsize, \null}
92 % \DoNotIndex{\number, \onecolumn, \or, \overfullrule}
93 % \DoNotIndex{\pagebreak, \pagestyle, \parbox, \penalty, \phantom, \protect}
94 % \DoNotIndex{\quad}
95 % \DoNotIndex{\raggedbottom, \raggedleft}
96 % \DoNotIndex{\relax, \renewcommand, \reversemarginpar}
97 % \DoNotIndex{\rightmargin, \rule, \setbox, \setcounter}
98 % \DoNotIndex{\setlength, \settowidth, \shortstack, \strut, \svtnsfb, \switch}
99 % \DoNotIndex{\thepage, \thispagestyle, \tiny, \today, \triangleright, \typeout}
100 % \DoNotIndex{\underbar, \underline, \unskip, \uppercase, \usepackage}
101 % \DoNotIndex{\vadjust, \vbadness, \vbox, \verb, \vfil, \vfill, \vrule, \vskip}
102 % \DoNotIndex{\vspace, \vtop, \wd, \year}
103 % \DoNotIndex{\bf, \tt, \par, \smallskip, \stepcounter}
104 %
105 % ^^A some extra entries to make wrong entries in the index invisible
106 % \DoNotIndex{\-, \n, \t, \tbe, \tcase, \tdebug, \tgenerate, \tIf, \tif, \tinto}
107 % \DoNotIndex{\tof, \tprocessed, \tshow, \twrite}
108 %
109 % ^^A \setlength{\IndexMin}{0.3\textheight}
110 %
111 % \changes{v56}{10/03/09}{corrected typo at `Fname}
112 % \changes{v50}{10/02/15}{changed some documentation commands to starred version}
113 % \changes{v37}{09/08/27}{reworked the documentation}
114 % \changes{v35}{09/08/27}{some textual changes}%
115 % \changes{v34}{09/08/24}{reworked the documentation}%
116 % \changes{v34}{09/08/24}{added commands `Fname and `ext to unify the documentation}%
117 % \changes{v34}{09/08/24}{changed the title again}%
118 % \changes{v33}{09/08/23}{changed title}%
119 % \changes{v23}{09/08/20}{enhanced the documentation}%
120 % \changes{v23}{09/08/20}{rearranged the sections about Makefile, tests,
121 % AUCTeX}%
122 % \changes{v16}{09/08/18}{added macros to make the documentation
123 % independent of non standard packages}%
124 % \changes{v11}{09/04/15}{corrected some text}%
125 % ^^A now some macros to simplify the writing of the documentation
126 % \newcommand*\Lopt[1]{\textsf{#1}}%
127 % \let\Lpack\Lopt%
128 % \let\ext\Lopt%
129 % \newcommand*{\Fname}[1]{\texttt{#1}}%
130 % \newcommand*{\XEmacs}{\textsf{(X)Emacs}}%
131 % \newcommand*{\SOURCEFRAME}{%
132 % \psline(0,0)(0,7)
133 % \psline(1.5,0)(1.5,7)
134 % \rput[lc](0.75,0){\ldots}
135 % \rput[lc](0.75,7){\ldots}
136 % }
137 % \newcommand*{\SOURCEA}[1]{%
138 % \psline*[linecolor=LemonChiffon](0,0)(1.5,0)(1.5,2)(0,2)%
139 % \if#1f%
140 % \psline(0,0)(1.5,0)(1.5,2.0)(0,2.0)(0,0)%
141 % \else\if#1g
142 % \psline[linewidth=1mm, linecolor=Olive](1.5,2.05)(0,2.05)%
143 % \psline[linewidth=1mm, linecolor=DarkOliveGreen](0,-0.05)(1.5,-0.05)%
144 % \fi\fi%
145 % }
146 % \newcommand*{\SOURCEB}[1]{%
147 % \psline*[linecolor=LightGreen](0,0)(1.5,0)(1.5,0.5)(0,0.5)%
148 % \if#1f%
149 % \psline(0,0)(1.5,0)(1.5,0.5)(0,0.5)(0,0)%
150 % \else\if#1g
151 % \psline[linewidth=1mm, linecolor=Olive](1.5,0.55)(0,0.55)%
152 % \psline[linewidth=1mm, linecolor=DarkOliveGreen](0,-0.05)(1.5,-0.05)%
153 % \fi\fi%
154 % }
155 % \newcommand*{\SOURCEC}[1]{%
156 % \psline*[linecolor=LightCyan](0,0)(1.5,0)(1.5,1.25)(0,1.25)%
157 % \if#1f%
158 % \psline(0,0)(1.5,0)(1.5,1.25)(0,1.25)(0,0)%
159 % \else\if#1g
160 % \psline[linewidth=1mm, linecolor=Olive](0,-0.05)(1.5,-0.05)%
161 % \psline[linewidth=1mm, linecolor=DarkOliveGreen](1.5,1.30)(0,1.30)%
162 % \fi\fi%
163 % }
164 % ^^A to avoid underfull messages while formatting two/three columns
165 % \hbadness=10000 \vbadness=10000%
166 % \setcounter{secnumdepth}{2}%
167 % \setcounter{tocdepth}{2}%
168 %
169 % \title{\listingsext\ --- A collection of \LaTeX{} commands and some
170 % helper files to support the automatic integration of parts of source
171 % files into a documentation\thanks{%
172 % This file has version number \fileversion, last revised on \filedate{},
173 % documentation dated \docdate.}%
174 % }%
175 % \author{Jobst Hoffmann\\
176 % Fachhochschule Aachen, Campus J\"ulich\\
177 % Ginsterweg 1\\
178 % 52428 J\"ulich\\
179 % Bundesrepublik Deutschland\\
180 % email: j.hoffmann\_(at)\_fh-aachen.de}%
181 % \date{printed on \today}
182 %
183 % ^^A\markboth{\LaTeX\ Stil-Option listings-ext, version \fileversion\ of \filedate}
184 % ^^A {\LaTeX\ Stil-Option listings-ext, version \fileversion\ of \filedate}
185 %
186 % \maketitle
187 %
188 % \begin{abstract}
189 % This article describes the use and the implementation of the \LaTeX{}
190 % package \listingsextSty{}, a package to simplify the insertion of parts
191 % of source code files into a document(ation).
192 % \end{abstract}
193 %
194 % \newif\ifmulticols
195 % \IfFileExists{multicol.sty}{\multicolstrue}{}
196 %
197 % \ifmulticols
198 % \addtocontents{toc}{\protect\begin{multicols}{2}}
199 % \fi
200 %
201 % \tableofcontents
202 %
203 % \section{Preface}
204 % \label{sec:preface}
205 %
206 % \changes{v09}{09/04/05}{added some text to the preface}%
207 % This package is
208 % intended as an implementation of the macros which are described in
209 % \cite{lingnau07:_latex_hacks}. If a software developer wants to document
210 % a piece of software, in most cases she/he doesn't need to print out whole
211 % source code files, but only parts of the files. This can be achieved by the
212 % \Lpack{listings}-package \cite{Heinz:Listings-14} and especially by the command
213 % \begin{quote}
214 % |\lstinputlisting[linerange={|\meta{first1}|-|\meta{last1}|}|, \ldots{}|]{|\meta{filename}|}|
215 % \end{quote}
216 % In \cite{lingnau07:_latex_hacks} there are described three macros, which
217 % can be created automatically, so that in the case of changes in the
218 % source code the developer mustn't change the contents of the line ranges,
219 % but she/he only has to rerun a program, which regenerates the meaning of
220 % the macros. In the following the three macros and a Bash-script to deal with
221 % these three macros are provided.
222 %
223 %
224 % \changes{v16}{09/08/18}{added macros to make the documentation
225 % independent of non standard packages}
226 % \section[Installation and Maintenance]{Hints For Installation And Maintenance}
227 % \label{sec:installation-maintenance}
228 %
229 % The package \listingsextSty{} is belonging to consists of altogether four files:
230 % \begin{quote}
231 % \Fname{README}, \\
232 % \Fname{listings-ext.ins}, \\
233 % \Fname{listings-ext.dtx}, \\
234 % \Fname{listings-ext.pdf}.
235 % \end{quote}
236 % In order to generate on the one hand the documentation of the package and
237 % on the other hand the corresponding \ext{.sty}-file and the supporting Bash-script
238 % one has to proceed as follows:
239 %
240 % \changes{v46}{09/08/31}{enhanced the documentation at several points}
241 % First the file \textsf{listings-ext.ins} must be formatted e.g.\ by
242 % \begin{quote}
243 %\begin{verbatim}
244 %latex listings-ext.ins
245 %\end{verbatim}%
246 % \end{quote}
247 % This formatting run generates several other files. These are first of
248 % all the previous mentioned \ext{.sty}-file \Fname{listings-ext.sty}, the
249 % style file which can be used by |\usepackage{listings-ext}| and the
250 % Bash-script |listings-ext.sh|. Then there are the files
251 % \Fname{listings-ext.bib} and \Fname{hyperref.cfg}, which are needed to
252 % produce this documentation. The creation of the documentation is is
253 % simplified by the files \Fname{listings-ext.makemake} and
254 % \Fname{listings-ext.mk}, which can be used to make a \Fname{Makefile}
255 % (see section~\ref{sec:Makefile}). Another helper file is
256 % \Fname{listings-ext.el}, which can be used with the \XEmacs{} editor (see
257 % section~\ref{sec:AUCTeX}). Some simple tests of this package can be done
258 % by using the files \Fname{listings-ext*exmpl*} and
259 % \Fname{listings-ext*test*}, which are also created; these files use the
260 % configuration file \Fname{listings.cfg}, which can also be used as a base or
261 % supplement for own configuration files of the
262 % \Lpack{listings}-package. This file can be put into the current
263 % directory for local use or into the |TEXMFHOME| directory for use with
264 % every document. You have to take care about the fact, that the local
265 % file in the current directory prevent any |listings.cfg| from being loaded.
266 % Finally there is a file \Fname{getversion.tex}, which is used for the
267 % creation of a "versioned" distribution.
268 %
269 % The common procedure to produce the documentation is to execute the
270 % commands
271 % \begin{quote}
272 %\begin{verbatim}
273 %latex listings-ext.dtx
274 %bibtex listings-ext
275 %latex listings-ext.dtx
276 %makeindex -s gind.ist listings-ext.idx
277 %makeindex -s gglo.ist -o listings-ext.gls -t listings-ext.glg \
278 % listings-ext.glo
279 %latex listings-ext.dtx
280 %\end{verbatim}
281 % \end{quote}
282 % The result of this formatting run is the documentation in form of a
283 % \ext{.dvi}-file, that can be manipulated the normal way. It ain't
284 % possible to use |pdflatex| because of the integrated PostScript based
285 % figures.
286 %
287 % One can find further informations about working with the integrated
288 % documentation in \cite{FM:TheDocAndShortvrbPackages} and
289 % \cite{MittelbachDuchierBraams:DocStrip}.\footnote{Generating the
290 % documentation is much easier with the \texttt{make} utility, see
291 % section~\ref{sec:Makefile}.}
292 %
293 % \changes{v33}{09/08/23}{cleaned up the driver once more}
294 % \changes{v33}{09/08/23}{moved hyperref settings into hyperref.cfg}
295 % \changes{v23}{09/08/20}{cleaned up the code}
296 % \changes{v16}{09/08/18}{replaced last german sentences from
297 % documentation}
298 % This documentation itself is generated by the following internal driver
299 % code:
300 % \begin{macrocode}
301 %<*driver>
302 \documentclass[a4paper, ngerman, english]{ltxdoc}
303
304 \usepackage[T1]{fontenc}
305 \usepackage{lmodern}
306 \usepackage{babel,babelbib}
307 \usepackage[svgnames]{pstricks}
308
309 \usepackage{listings-ext}
310 \GetFileInfo{listings-ext.sty}
311
312 \newif\ifcolor \IfFileExists{color.sty}{\colortrue}{}
313 \ifcolor \RequirePackage{color}\fi
314
315 \usepackage[numbered]{hypdoc}
316 \usepackage{url}
317
318 %\EnableCrossrefs
319 %\DisableCrossrefs % say \DisableCrossrefs if index is ready
320 %\RecordChanges % gather update information
321 %\CodelineIndex % index entry code by line number
322 \OnlyDescription % comment out for implementation details
323 \MakeShortVerb{\|} % |\foo| acts like \verb+\foo+
324
325 \begin{document}
326
327 \DocInput{listings-ext.dtx}%
328 \end{document}
329 %</driver>
330 % \end{macrocode}
331 %
332 % \changes{v13}{09/05/28}{enhanced the documentation}
333 % \section{The User's Interface}
334 % \label{sec:users-interface}
335 %
336 % \changes{v16}{09/08/18}{extended the description of usage}
337 % \subsection{Preparing the \LaTeX{} code}
338 % \label{sec:preparing-latex}
339 %
340 % The user's interface is as simple as possible: just load the required
341 % package by saying
342 % \begin{quote}
343 % |\usepackage[|style=\meta{style-name}|]{listings-ext}|
344 % \end{quote}
345 % \meta{style-name} is the name of a \textsf{listings} style, defined by
346 % the command \cite[sec.~4.5]{Heinz:Listings-14}. You can find examples for
347 % such styles in the exemplary configuration file \Fname{listings.cfg}.
348 % \begin{quote}
349 % |\lstdefinestyle{|\meta{style name}|}{|\meta{key=value list}|}|
350 % \end{quote}
351 %
352 % After loading the package provides three commands:
353 % \begin{enumerate}
354 % \item \begin{quote}
355 % |\lstdef{|\meta{identifier}|}{|\meta{file-name}|}{|\meta{range}|}|
356 % \end{quote}
357 % defines the \meta{identifier}, by which the line range \meta{range} in the
358 % file defined by \meta{file-name} can be referenced. If you identify
359 % several \meta{filename}s or \meta{range}s by the same
360 % \meta{identifier}, the last definition is valid. If you don't like
361 % that behaviour, put the corresponding |\lstdef|- and
362 % |\lstuse|-commands (see below) into a group of its own.
363 % \item \begin{quote}
364 % |\lstuse[|\meta{options}|]{|\meta{identifier}|}|
365 % \end{quote}
366 % includes the source code which is referenced by \meta{identifier} by
367 % (internally) calling |\lstinputlisting| of the package
368 % \Lpack{listings} \cite{Heinz:Listings-14}, the way of formatting can be influenced by
369 % \meta{options}.
370 % \item
371 % \begin{quote}
372 % |\lstcheck{|\meta{identifier}|}{|\meta{file-name}|}|
373 % \end{quote}
374 % can be used, if one prepares a file \meta{file-name} consisting of a
375 % lot of |\lstdef| commands. If \meta{identifier} isn't yet defined,
376 % the file defined by \meta{file-name} is |\input|. This command is
377 % especially helpful, if you prepare a presentation and you want to
378 % format only single slides for testing their look.
379 % \end{enumerate}
380 %
381 %
382 % \subsection{Preparing the source code}
383 % \label{sec:preparing-source}
384 %
385 % If you just want to include a small part of a source code file, you can
386 % do that without touching the source: just write the corresponding
387 % commands |\lstdef| and |\lstuse| into your \LaTeX-code. But if the
388 % source code changes, you have to adapt the changes in the |\lstdef|
389 % command. That may be very tedious, if are you changing your sources often.
390 %
391 % It' better to automate that procedure, and one way of implementig that is
392 % done at the Bash-script \Fname{listings-ext.sh}. For working with that
393 % script you have to tag the parts of the source, which you want to
394 % document, by comments.
395 %
396 % At the moment there are three tags, which can be described by the
397 % following regular expressions:
398 % \begin{enumerate}
399 % \item |^\ +|\meta{endline-comment-character(s)}|\ be:\ |\meta{string}|$|
400 %
401 % This expression defines the beginning of the environment, which should be
402 % |\lstinput| into the document.
403 % \item |^\ +|\meta{endline-comment-character(s)}|\ ee:\ |\meta{string}|$|
404 %
405 % This expression defines the end of that environment.
406 % \item |^\ +|\meta{endline-comment-character(s)}|\ ce:\ |\meta{list of
407 % keywords}
408 %
409 % This expression defines, how the the environments defined by the above
410 % introduced should be processed.
411 % \end{enumerate}
412 % The meaning of the regular expressions is: start a line with at least one
413 % blank space "\verb*| |", add endline comment characters (C++ and Java:
414 % |//|, Fortran: |!|) followed by another blank space. Then you have to
415 % enter "\verb*|be: |" for the beginning of a code environment, and %
416 % "\verb*|ee: |" for the end. In both cases the line must be ended with a
417 % string which should denote the meaning of the environment , the strings for the
418 % beginning and the end must be identical.\footnote{You can also use the
419 % standard C comments |/*| \ldots|*/|, but in that case the trailing "|*/|"
420 % is seen as the end of the \meta{string}.}
421 %
422 % \changes{v63}{10/06/22}{added remarks about Max OS X}
423 % \changes{v53}{10/03/09}{issue solved: now able to handle any file name as
424 % list of source files}
425 % If you have prepared a source code file with these tags, you can process
426 % it by the Bash-script provided by the package. The script should work for
427 % a Linux system out of the box, for a Mac OS X 10.x one must additionally
428 % install |getopt| from \url{http://getopt.darwinports.com/}, which in turn
429 % needs |MacPorts| (from
430 % \url{http://www.macports.org/install.php}).\footnote{The package is
431 % tested with Max OS X v\,10.6.3, |getopt|'s version number is v\,1.1.4 and
432 % |MacPorts| version number is v\,1.9.0.}
433 %
434 % The simplest way to do it is the call
435 % \begin{quote}
436 % |listings-ext.sh -co |\meta{file list}
437 % \end{quote}
438 % \meta{file list} is a list of one or more file names. This call creates
439 % the file \meta{directory}|.lst|, where \meta{directory} is the name of
440 % the current directory. The file consists of a header and a list of |\lstdef|
441 % commands,
442 % of the form
443 % \begin{quote}
444 % |\lstdef{|\meta{identifier}|}{|\meta{filename}|}{|\meta{line range(s)}|}|
445 % \end{quote}
446 % You can |\input| the file \meta{directory}|.lst| into your documentation;
447 % its header looks like (for example)
448 %\begin{verbatim}
449 % %% -- file listings-ext.lst generated on Mi 26. Aug 22:05:20 CEST 2009
450 % by listings-ext.sh
451 % \csname listingsextLstLoaded\endcsname
452 % \expandafter\let\csname listingsextLstLoaded\endcsname\endinput
453 %\end{verbatim}
454 % The first line is wrapped by hand, the second and third line prohibit a
455 % second load of that file. One of the |\lstdef| could look like
456 %\begin{verbatim}
457 % \lstdef{listingsExtExmplAA}{/home/xxx%
458 % /listings-ext%
459 % /listings-ext_exmpl_a.java}{3-5}
460 %\end{verbatim}
461 %
462 % You can input this file in two ways into your document:
463 % \begin{enumerate}
464 % \item by saying
465 %\begin{verbatim}
466 % \input{listings-ext.lst}
467 %\end{verbatim}
468 % at the beginning of a file or
469 % \item by saying
470 %\begin{verbatim}
471 % \lstcheck{listingsExtExmplAA}{listings-ext.lst}
472 %\end{verbatim}
473 % in an environment to keep the definition local.
474 % \end{enumerate}
475 %
476 % After that you can use the command |\lstuse| to integrate the source
477 % code parts into your documentation. The usage is
478 % \begin{quote}
479 % |\lstuse[|\meta{options}|]{|\meta{identifier}|}|
480 % \end{quote}
481 % at the place, where you want the part of your source code.
482 %
483 % The \meta{identifier} is generated automatically, it is derived from the
484 % file name, you have to transfer the identifiers from the \ext{.lst}-file
485 % to the |\lstuse|-command by hand, but that happens typically only one
486 % time. So in this case the |\lstuse| command could look like --- as said
487 % you can add options ---
488 %\begin{verbatim}
489 % \lstuse{listingsExtExmplAA}
490 %\end{verbatim}
491 %
492 % For more information about the use of the Bash-script |listings-ext.sh|
493 % enter the command
494 % \begin{quote}
495 % |listings-ext.sh -h|
496 % \end{quote}
497 %
498 % \changes{v09}{09/04/05}{introduced a description of the ce-commands}
499 % There is one optional initial tag |ce:| (\textit{control environment}): It needs one
500 % argument \meta{mode}. The argument describes the further
501 % processing. \meta{mode} may be one of the following values:
502 % \begin{description}
503 % \item[\texttt{combine}:] |be: | \ldots{}|ee: | groups with the same
504 % description are combined into one piece of code in the output
505 % \item[\texttt{join}:] all |be: | \ldots{}|ee: | groups (independent of
506 % the description) are combined into one piece of code in the output
507 % \end{description}
508 % The behaviour of the three modes of operation is shown in
509 % Figure~\ref{fig:modes-operation}.
510 % |ce:| has to be put before all other tags in the source code.
511 % \changes{v35}{09/08/27}{added figure to show the behaviour of listings-ext.sh}
512 % \begin{figure}[htb]
513 % \psset{unit=6mm} \centering
514 % \begin{pspicture}(0,-1.0)(4,7) \rput[lB](0,4.5){\SOURCEA{g}}
515 % \rput[lB](0,3.0){\SOURCEB{g}} \rput[lB](0,1.0){\SOURCEC{g}}
516 % \rput[lB](0,0){\SOURCEFRAME} \rput[lB](2.5,4.5){\SOURCEA{f}}
517 % \rput[lB](2.5,3.0){\SOURCEB{f}} \rput[lB](2.5,1.0){\SOURCEC{f}}
518 % \rput(2.5,-0.7){a)}
519 % \end{pspicture}
520 % \hspace{2cm}
521 % \begin{pspicture}(0,-1.0)(4,7) \rput[lB](0,4.5){\SOURCEA{g}}
522 % \rput[lB](0,3.0){\SOURCEB{g}} \rput[lB](0,1.0){\SOURCEC{g}}
523 % \rput[lB](0,0){\SOURCEFRAME} \rput[lB](2.5,3.5){\SOURCEA{}}
524 % \rput[lB](2.5,3.0){\SOURCEB{}} \rput[lB](2.5,1.75){\SOURCEC{}}
525 % \psframe(2.5,1.75)(4.0,5.5) \rput(2.5,-0.7){b)}
526 % \end{pspicture}
527 % \hspace{2cm} \begin{pspicture}(0,-1.0)(4,7)
528 % \rput[lB](0,4.5){\SOURCEA{g}} \rput[lB](0,3.0){\SOURCEB{g}}
529 % \rput[lB](0,1.0){\SOURCEC{g}} \rput[lB](0,0){\SOURCEFRAME}
530 % \rput[lB](2.5,3.5){\SOURCEA{}} \rput[lB](2.5,2.25){\SOURCEC{}}
531 % \psframe(2.5,2.25)(4.0,5.5) \rput[lB](2.5,1.0){\SOURCEB{}}
532 % \psframe(2.5,1.0)(4.0,1.5) \rput(2.5,-0.7){c)}
533 % \end{pspicture}
534 % \caption[Modes of operation]{Modes of operation: a) no special control of the tagged
535 % parts, every part can be processed by itself, b) control by |ce:
536 % join|, all tagged parts are joint into one piece, which can be
537 % further processed, c) control by |ce: combine|, tagged parts with
538 % the same describing string are joint into one piece, which can be
539 % further processed, all other parts can be processed by their own}
540 % \label{fig:modes-operation}
541 % \end{figure}
542 %
543 %
544 % \changes{v33}{09/08/23}{moved bibliography into listings-ext.bib}
545 % \changes{v27}{09/08/21}{a few small layout changes}
546 % \changes{v16}{09/08/18}{internalized the bibliography}
547 % \StopEventually{
548 % \bibliographystyle{babalpha}
549 % \bibliography{listings-ext}
550 %
551 % \ifmulticols
552 % \addtocontents{toc}{\protect\end{multicols}}
553 % \fi
554 %
555 % \PrintChanges
556 % \PrintIndex
557 % } ^^A end of \StopEventually
558 %
559 % \clearpage
560 %
561 %
562 % \changes{v16}{09/08/18}{started the documentation of the implementation}
563 % \section{The Implementation}
564 % \label{sec:the-implementation}
565 %
566 % \subsection{The style file}
567 % \label{sec:the-style-file}
568 %
569 % At first we must declare the required packages :
570 % \begin{macrocode}
571 %<*extension>
572 \RequirePackage{listings}
573 \RequirePackage{xkeyval}
574 % \end{macrocode}
575 % and the package options for \listingsextSty.
576 % \begin{macro}{style}
577 % is the only option at the moment.
578 % \begin{macrocode}
579 \DeclareOptionX{style}[]{\lstset{style=#1}}
580 \ProcessOptionsX*
581 % \end{macrocode}
582 % \end{macro}
583 %
584 % Then we define the three above mentioned commands in the way, which is
585 % described in \cite{lingnau07:_latex_hacks}.
586 % \begin{macro}{\lstdef}
587 % \changes{v46}{09/08/31}{enhanced the documentation}
588 % has three parameters:
589 % \begin{quote}
590 % \begin{tabular}{ll}
591 % \#1 & the identifier of the chunk of source code \\
592 % \#2 & the file name of the source code \\
593 % \#3 & the line range \\
594 % \end{tabular}
595 % \end{quote}
596 % Every parameter can be used at the user's choice, so there is no chance
597 % to test the parameters.
598 % \begin{macrocode}
599 \newcommand{\lstdef}[3]{%
600 \@namedef{lst@l@#1}##1{%
601 \lstinputlisting[##1, linerange={#3}]{#2}}%
602 }
603 % \end{macrocode}
604 % \end{macro}
605 %
606 % \begin{macro}{\lstcheck}
607 % \changes{v46}{09/08/31}{enhanced the documentation}
608 % has two parameters:
609 % \begin{quote}
610 % \begin{tabular}{ll}
611 % \#1 & the identifier of the chunk of source code \\
612 % \#2 & the file name of a file with many |lstdef| lines \\
613 % \end{tabular}
614 % \end{quote}
615 % \changes{v45}{09/08/31}{added some checks for arguments}
616 % \begin{macrocode}
617 \newcommand{\lstcheck}[2]{%
618 % \end{macrocode}
619 % At first we test, if the identifier is unknown. If so, we read the above
620 % mentioned file.
621 % \begin{macrocode}
622 \expandafter\ifx\csname lst@l@#1\endcsname\relax%
623 \input{#2}\fi%
624 % \end{macrocode}
625 % Now the identifier should be known. If not, we emit a corresponding error
626 % message.
627 % \begin{macrocode}
628 \expandafter\ifx\csname lst@l@#1\endcsname\relax%
629 \PackageError{listings-ext}{undefined identifier}{%
630 You may have mispelled the identifier, check the file%
631 \MessageBreak\space\space\space#2\MessageBreak%
632 for the correct spelling.}\fi%
633 }
634 % \end{macrocode}
635 % \end{macro}
636 %
637 % \begin{macro}{\lstuse}
638 % \changes{v46}{09/08/31}{enhanced the documentation}
639 % has two parameters:
640 % \begin{quote}
641 % \begin{tabular}{ll}
642 % \#1 & options of the |\lstinputlisting| command (optional) \\
643 % \#2 & the above defined identifier \\
644 % \end{tabular}
645 % \end{quote}
646 % \changes{v45}{09/08/31}{added some checks for arguments}
647 % \begin{macrocode}
648 \newcommand{\lstuse}[2][]{%
649 % \end{macrocode}
650 % At first we test, if the identifier is unknown. If so, we emit a
651 % corresponding error message.
652 % \begin{macrocode}
653 \expandafter\ifx\csname lst@l@#2\endcsname\relax%
654 \PackageError{listings-ext}{undefined identifier}{%
655 You may have mispelled the identifier.\MessageBreak%
656 If you go on without any change, no source code will be %
657 included,\MessageBreak but your options will be written %
658 into your formatted document.}\fi%
659 % \end{macrocode}
660 % Now we can |\lstinputlisting| the source code by use of the
661 % |\@namedef| ed command.
662 % \begin{macrocode}
663 \@nameuse{lst@l@#2}{#1}%
664 }
665 %</extension>
666 % \end{macrocode}
667 % \end{macro}
668 % That' all for the \LaTeX-side of life.
669 %
670 %
671 % \changes{v46}{09/08/31}{enhanced the documentation at several points}
672 % \changes{v45}{09/08/31}{introduced an exemplary configuration file}
673 % \subsection{An exemplary configuration file}
674 % \label{sec:a-configuration-file}
675 %
676 % It is a good practise, to format all source code chunks in the same
677 % way. The easiest way to do that is to provide a style. The following
678 % lines provide two styles, one for the use with a black and white
679 % printer, the other for a printer which is capable of color output.
680 % \begin{macrocode}
681 %<*listings>
682 \ProvidesFile{listings.cfg}%
683 [2009/08/23 v1.0 listings configuration of listings-ext]
684
685 \RequirePackage{xcolor}
686
687 \def\lstlanguagefiles{lstlang1.sty,lstlang2.sty,lstlang3.sty}
688 \lstset{defaultdialect=[ANSI]C,
689 defaultdialect=[ISO]C++,
690 defaultdialect=[95]Fortran,
691 defaultdialect=Java,
692 defaultdialect=[LaTeX]TeX,
693 frame=tlb,
694 resetmargins=false,
695 }
696 \lstdefinestyle{colored-code}{
697 backgroundcolor=\color{yellow!10},%
698 basicstyle=\footnotesize\ttfamily,%
699 identifierstyle=\color{black},%
700 keywordstyle=\color{blue},%
701 stringstyle=\color{teal},%
702 commentstyle=\itshape\color{orange},%
703 }
704 \lstdefinestyle{bw-code}{
705 basicstyle=\small\fontfamily{lmtt}\fontseries{m}\fontshape{n}\selectfont,
706 % instead of lmtt one should use ul9 (luximono) for boldface characters
707 keywordstyle=\small\fontfamily{lmtt}\fontseries{b}\fontshape{n}\selectfont,
708 commentstyle=\small\fontfamily{lmtt}\fontseries{m}\fontshape{sl}\selectfont,
709 stringstyle=\small\fontfamily{lmtt}\fontseries{m}\fontshape{it}\selectfont,
710 }
711 %</listings>
712 % \end{macrocode}
713 %
714 %
715 % \changes{v16}{09/08/18}{moved the documentation of the script into the documentation}
716 % \subsection{The shell script}
717 % \label{sec:the-shell-script}
718 %
719 % \changes{v58}{10/05/18}{removed some bashisms (according to Ahmed El-Mahmoudy---aelmahmoudy\_at\_sabily.org)}
720 % \changes{v37}{09/08/27}{removed small glitches}
721 % \changes{v23}{09/08/20}{moved some more comment from the script into the documentation}
722 % \changes{v12}{09/05/12}{added some debug code}
723 % \changes{v11}{09/04/15}{added some documentation}
724 % \changes{v09}{09/04/05}{added some space for a better layout}
725 % \changes{v05}{08/03/04}{add a debug option for the script}
726 % \changes{v05}{08/03/04}{change the behaviour: hyphens and underscores are removed in
727 % the .lst-file}
728 % \changes{v05}{08/03/04}{check the correct grouping of be...ee}
729 % \changes{v05}{08/03/04}{function delete\_underscore renamed to "replace\_characters"}
730 % \changes{v05}{08/03/04}{better error processing with messages to stderr}
731 % \changes{v05}{08/03/04}{in replace\_characters now also hyphens are replaced}
732 % \changes{v05}{08/03/04}{introduced function print\_error}
733 % \changes{v05}{08/03/04}{introduced function break\_line}
734 % \changes{v03}{08/02/27}{corrected the on-line help according to the current implementation}
735 % \changes{v03}{08/02/27}{changed documentation and behaviour of function print\_header}
736 % \changes{v03}{08/02/27}{fixed some typos}
737 % \changes{v03}{08/02/27}{output option now has an optional argument}
738 % \changes{v03}{08/02/27}{call of print\_header changed according to the
739 % optional argument from above}
740 % \changes{v06}{08/09/07}{created list of things to do}
741 % To get full benefit of the three above introduced commands, we provide a
742 % Bash-script, which internally uses |awk|, |grep| and |sed|. A Perl
743 % programmer could provide the same functionality by a Perl script.
744 %
745 % \begin{macrocode}
746 %<*scriptfile>
747 #! /bin/sh
748 ### listings-ext.sh ---
749
750 ## Author: Dr. Jobst Hoffmann <j.hoffmann_(at)_fh-aachen.de>
751 ## Version: $Id: listings-ext.dtx 67 2010-06-29 16:38:12Z ax006ho $
752 ## Keywords: LaTeX, listings
753 ## Copyright: (C) 2008-2010 Jobst Hoffmann, <j.hoffmann_(at)_fh-aachen.de>
754 ##-------------------------------------------------------------------
755 ##
756 ## This file may be distributed and/or modified under the
757 ## conditions of the LaTeX Project Public License, either version 1.2
758 ## of this license or (at your option) any later version.
759 ## The latest version of this license is in:
760 ##
761 ## http://www.latex-project.org/lppl.txt
762 ##
763 ## and version 1.2 or later is part of all distributions of LaTeX
764 ## version 1999/12/01 or later.
765 ##
766 ## This file belongs to the listings-ext package.
767 ##
768 ## listings-ext.sh creates code to be inserted into a
769 ## LaTeX file from a source file.
770 ##
771 ## The commented code can be seen in listings-ext.pdf, which is provided
772 ## with the distribution package.
773 % \end{macrocode}
774 %
775 % The format of the result is depending on a switch \verb!-c|--command!:
776 % \begin{itemize}
777 % \item If the switch is set, the result is a single file which can be
778 % |\input| into LaTeX code. The file contains lines of the form
779 % \begin{quote}
780 % |\lstdef{|\meta{identifier}|}{|\meta{filename}|}{|\meta{linerange(s)}|}|
781 % \end{quote}
782 % \meta{identifier} can be used in the \LaTeX{} code by a command
783 % \begin{quote}
784 % |\lstuse{|\meta{identifier}|}|
785 % \end{quote}
786 % to |\lstinputlisting| the source code at that place.
787 % \meta{identifier} is derived from the filename of the source file,
788 % where there is a sequence of uppercase letters (A, B, \ldots{}, Z,
789 % BA, \ldots{}) appended as postfix to distinguish between several
790 % chunks. If we are in join mode --- see below ---, there will be no
791 % postfix at all. You have to be careful with the filenames: as the
792 % identifiers are used as \TeX{}-commands, the have to consist only of
793 % characters, but the script allows underscores and hyphens in the
794 % filenames and translates them into a camel case notation.
795 % \item If the switch is not set, a piece of LaTeX code like the
796 % following is generated for every chunk of source code:
797 %\begin{verbatim}
798 % %===>begin{listingsExtExmplAC}
799 % {%
800 % \def\inputfile{%
801 % /home/xxx/texmf/source/latex/listings-ext%
802 % /listings-ext_exmpl_a.java
803 % }
804 % \ifLecture{%
805 % \lstdefinestyle{localStyle}{%
806 % caption={\lstinline|listings-ext_exmpl_a.java|: using the resource bundle}
807 % }%
808 % }
809 % {%
810 % \lstdefinestyle{localStyle}{%
811 % title={\lstinline|listings-ext_exmpl_a.java|: using the resource bundle}
812 % }%
813 % }
814 % \lstinputlisting[style=localStyle, linerange={29-30}]%
815 % {%
816 % \inputfile
817 % }
818 % }%
819 % % =====>end{listingsExtExmplAC}
820 % \end{verbatim}
821 % \end{itemize}
822 %
823 % The source file contains pairs of lines of the form described by the
824 % following regular expressions:
825 % \begin{itemize}
826 % \item |^\ +|\meta{endline-comment-character(s)}|\ be: |\meta{string}|$|
827 %
828 % This expression defines the beginning of a environment, which should be
829 % |\lstinput| into the document.
830 % \item |^\ +|\meta{endline-comment-character(s)}|\ ee: |\meta{string}|$|
831 %
832 % This expression defines the end of that environment.
833 % \end{itemize}
834 %
835 % Another line can preceed all pairs:
836 % \begin{quote}
837 % |\ +|\meta{endline-comment-character(s)}|\ ce: |\meta{list of keywords}
838 % \end{quote}
839 %
840 % \meta{list of keywords} is a comma separated list of words, the first one
841 % must be one of the words
842 % \begin{itemize}
843 % \item |join|
844 % \item |combine|
845 % \end{itemize}
846 %
847 % At the moment we support only these keywords. The meaning of the
848 % keywords is
849 % \begin{itemize}
850 % \item |join|: we generate lines, which print the listing as one part
851 % \item |combine|: we generate lines, which print the listing as one part, only
852 % for headings, which correspond
853 % \end{itemize}
854 %
855 % These lines will be grepped. The result is processed by |awk| where '|:|' is
856 % defined as a field separator, the final result is a range of lines, which
857 % is further processed to create the output.
858 % \changes{v56}{10/03/09}{a new usage description, added new option "-e"}
859 % \changes{v33}{09/08/23}{corrected description of usage of the script}
860 % \begin{macrocode}
861 ERR_HELP=1
862 ME=$(basename $0)
863 USAGE="usage:\n\t${ME} [-c|--command] [-e|--ext] [-g|--debug] \\\\\n\
864 \t\t[-h|--help] [-n|--no-header] \\\\\n\
865 \t\t[{-o|--output-file} [<output filename>]] <filename>, ...\n\
866 \t-c:\tgenerate commands, which can be input and later used by\n\
867 \t\t\\\\lstuse, optional\n\
868 \t-e:\tinclude file name extension into the identifier\n\
869 \t-g:\tdebug mode, create some additional output, optional\n\
870 \t-h:\tshow this help, optional\n\
871 \t-n:\twrite no header into the LaTeX code, optional; valid only,\n\
872 \t\tif -c isn't used\n\
873 \t-o [<output filename>]: if this argument is present, the output will\n\
874 \t\tbe written into a file <output filename>; if the\n\
875 \t\t<output filename> is omitted, the output is redirected\n\
876 \t\tinto a file with a basename corresponding to the name\n\
877 \t\tof the current directory, it has an extension of \".lst\".\n\
878 "
879 DEBUG_MODE=0
880 EXTENSION=0
881 HEADER=1
882
883 show_usage() { # display help massage
884 printf "${USAGE}"
885 exit ${ERR_HELP}
886 }
887 % \end{macrocode} ^^A $
888 % \changes{v11}{09/04/15}{corrected generation of filename for .lst-output file}
889 % \changes{v09}{09/04/05}{changed the documentation of the function
890 % print\_header}
891 % We define some functions for the internal use. The first one prints the
892 % header of the output file, it has two arguments:
893 % \begin{itemize}
894 % \item \$1: file name---the name of the file to be written on
895 % \item \$2: directory - the last name in the directory path (currently
896 % not used)
897 % \end{itemize}
898 % \changes{v63}{10/06/22}{replaced most of the echo commands by printf (because of Mac OS X)}
899 % \changes{v53}{10/03/09}{issue solved: now able to handle any file name as
900 % list of source files}
901 % \begin{macrocode}
902 print_header() {
903 FILE=$1
904 printf "%%%% -- file $1 generated on $(date) by ${ME}\n"
905 FILE=$(echo $(basename $1 .lst) | sed -e s/[_\-]//g)
906 printf "\\\\csname ${FILE}LstLoaded\\\\endcsname\n"
907 printf "\\\\expandafter\\\\let\\\\csname ${FILE}LstLoaded\\\\endcsname\\\\endinput\n"
908 }
909 % \end{macrocode} ^^A $
910 % The main function is |do_the_job|. It accepts the following parameter:
911 % \begin{enumerate}
912 % \item \$1: a filename
913 % \end{enumerate}
914 % \begin{macrocode}
915 do_the_job() {
916 % \end{macrocode} ^^A $
917 % In |awk| \$0 refers to the whole input record---to the current input
918 % line---, so that element could be split into its components which are
919 % marked by '/', the result is the name of the current directory without
920 % any path elements stored in an array
921 %\begin{verbatim}
922 % PATHCOMPONENT=$(pwd | \
923 % awk -F : '{n = split($0, text, "/"); print text[1] text[n]}')
924 %\end{verbatim}
925 %
926 % The current implementation uses the whole path, it will be split into its
927 % parts when it is used.
928 % \begin{macrocode}
929 PATHCOMPONENT=$(pwd)
930 SOURCEFILE=$1
931
932 if [ ! -f ${SOURCEFILE} ]
933 then
934 printf "${SOURCEFILE} is no valid file\n"
935 return $ERR_NOFILE
936 fi
937 % \end{macrocode} ^^A $
938 % \changes{v12}{09/05/12}{added support for ant: filenames are given complete with the path}
939 % If the script is called with the full path of the files, the directory
940 % part must be cut off from filename
941 % \begin{macrocode}
942 SOURCEFILE=${SOURCEFILE##${PATHCOMPONENT}/}
943
944 % \end{macrocode} ^^A $
945 % \changes{v65}{10/06/28}{grep: replaced blank by space regex}
946 % \changes{v51}{10/03/33}{corrected the grep expression according to the definition of the syntax}
947 % From the current source file, we grep all the lines with the above
948 % mentioned pattern, prepend them by a line number (parameter |-n|)
949 % \begin{macrocode}
950 grep -n "^[[:space:]]*[/%;#!][/\* ;][[:space:]]*[cbe]e:" $1 | \
951 % \end{macrocode} ^^A $
952 % We pass all the lines to |awk|. Additionally we set some parameters and define
953 % the field separator by |-F| as "|:|", so that from |awk|'s point of view
954 % the lines consist of three parts:
955 % \begin{enumerate}
956 % \item the line number
957 % \item the opening/closing tag
958 % \item an identifying string
959 % \end{enumerate}
960 % \changes{v56}{10/03/09}{a cleaner handling of passing parameters to awk}
961 % \begin{macrocode}
962 awk -v pathcomponent="${PATHCOMPONENT}" -v file="${SOURCEFILE}" \
963 -v header="${HEADER}" -v command="${COMMAND}" -v application="${ME}" \
964 -v debugmode="${DEBUG_MODE}" -v respect_extension="${EXTENSION}"\
965 -F : \
966 '
967 BEGIN {
968 % \end{macrocode} ^^A $
969 % \changes{v09}{09/04/05}{reflect the introduction of the command combine}
970 % We start the code with some settings.
971 % In |awk| the value 1 means "true", the value 0 "false".
972 % \begin{macrocode}
973 is_opened = 0;
974 initialised = 0;
975 configured = 0;
976 join = 0;
977 combine = 0;
978
979 idChar = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
980 split(idChar, idArray, "")
981 idPt = 0
982 linerange = "";
983
984 linelen = 75; # length of the output line
985 addchars = 8; # number of additional characters like %, > or so
986
987 if ( debugmode ) printf("path: %s\n", pathcomponent) > "/dev/stderr"
988 if ( debugmode ) printf("file: %s\n", file) > "/dev/stderr"
989 % \end{macrocode}
990 % For |\lstinputting| the file, we need the absolute filepath. In the
991 % following, we construct this, the correspondent variable is |inputfile|,
992 % the filename to be formatted is split into convenient pieces by a
993 % macro
994 % \changes{v63}{10/06/22}{rewrote code for splitting paths into names}
995 % \begin{macrocode}
996 n = split(pathcomponent, partsa, "/");
997 curr_dir = parts[n]
998 % \end{macrocode}
999 % \changes{v65}{10/06/28}{breaking of lines moved into a single place}
1000 % Add the file to the array to process the whole name in a similar manner.
1001 % \begin{macrocode}
1002 n++;
1003 partsa[n] = file;
1004 inputfile = "/" partsa[2];
1005 for ( i = 3; i <= n; i++ ) {
1006 inputfile = inputfile "/" partsa[i];
1007 }
1008 if ( debugmode ) printf("inputfile: %s\n", inputfile) > "/dev/stderr"
1009 % \end{macrocode}
1010 % For the identification of the several chunks we need the filename
1011 % without path and without suffix. We take everything behind the last
1012 % dot as suffix
1013 %
1014 % \changes{v65}{10/06/28}{moved single \{ from beginning of line to end of previous line}
1015 % The |identifier| mustn't contain any path parts of the filename. So we
1016 % split the filename here.
1017 % \begin{macrocode}
1018 n = split(file, partsa, "/")
1019 n = split(partsa[n], partsb, ".")
1020 identifier = partsb[1]
1021 for ( i = 2; i < n; i++ ) {
1022 identifier = identifier partsb[i]
1023 }
1024 % \end{macrocode}
1025 % If there are files with the same basename, but different extensions, we
1026 % may take account of the extensions.
1027 % \changes{v56}{10/03/09}{added processing of option "-e"}
1028 % \begin{macrocode}
1029 if ( respect_extension ) {
1030 identifier = identifier partsb[n]
1031 }
1032 identifier = replace_characters(identifier)
1033 if ( debugmode ) printf("identifier: %s\n", identifier) > "/dev/stderr"
1034 }
1035 % \end{macrocode}
1036 % The following code will be executed for every line, the standard delimiter is ":"
1037 % \begin{macrocode}
1038 {
1039 % \end{macrocode}
1040 % \changes{v09}{09/04/05}{test external (LaTeX-)documentation of the code}
1041 % |$0| is the whole line, |$NF| the text, which is used in combine mode as
1042 % identifier not only for the beginning and ending of a chunk but also for
1043 % collecting all the chunks.
1044 % \begin{macrocode}
1045 if ( debugmode ) print $0 > "/dev/stderr"
1046 if ( !initialised ) {
1047 % \end{macrocode} ^^A $
1048 % \changes{v67}{10/06/29}{added remark about CR and LF}
1049 % \changes{v09}{09/04/05}{extend the external documentation}
1050 % In the beginning, there are two cases to distinguish:
1051 % \begin{enumerate}
1052 % \item There is an introducing |ce| marker
1053 % \item There is no introducing |ce| marker
1054 % \end{enumerate}
1055 % In the first case we have to set a flag according to the value of the
1056 % mark, in the second case we have to look for the first mark (|be| or
1057 % |ce|). The marker is supposed to end at the line's end. If a \LaTeX{}
1058 % source file is created with an editor, which creates the CRLF combination
1059 % as the end of line, the CR would be thought as part of the marker. To
1060 % avoid the trouble, the CR is removed (if it exists).
1061 % \changes{v65}{10/06/28}{added code to remove spurious carriage return character}
1062 % \begin{macrocode}
1063 if ( match($2, /ce/) > 0 ) {
1064 n = split($(NF), text, ",");
1065 if ( match(text[1], "join") ) {
1066 join = 1;
1067 } else if ( match(text[1], "combine") ) {
1068 combine = 1;
1069 }
1070 } else if ( match($2, /be/) > 0 ) {
1071 opening_tag = $(NF)
1072 gsub(/\r/, "", opening_tag);
1073 is_opened = 1
1074 start = $1 + 1; # entry $1 is the line number
1075 } else if ( match($2, /ee/) > 0 ) {
1076 print_error($1, "missing \"be\" declaration")
1077 }
1078 initialised = 1;
1079 } else {
1080 tag = $(NF)
1081 if ( match($2, /be/) > 0 ) {
1082 if ( is_opened ) {
1083 print_error($1, "incorrect grouping, previous group"\
1084 " not closed")
1085 } else {
1086 opening_tag = $(NF)
1087 gsub(/\r/, "", opening_tag);
1088 is_opened = 1
1089 start = $1 + 1; # entry $1 is the line number
1090 }
1091 } else {
1092 if ( match($2, /ee/) > 0 ) {
1093 closing_tag = $(NF)
1094 gsub(/\r/, "", closing_tag);
1095 if ( !is_opened ) {
1096 print_error($1, "missing \"be\" declaration")
1097 } else if ( opening_tag == closing_tag ) {
1098 is_opened = 0
1099 % \end{macrocode} ^^A $
1100 % \changes{v65}{10/06/28}{changed the prefix to a double \% to unify the output}
1101 % We found the correct end of the environment, now we prepare the output entries
1102 % \begin{macrocode}
1103 split($(NF), text, "*"); # omit a trailing comment
1104 sub(/ /, "", text[1]); # delete leading spaces
1105 gsub(/"/, "", text[1]);
1106 if ( index(text[1], "_") > 0 ) gsub(/_/, "\\_", text[1]);
1107 caption = "\\lstinline|" file "|: " text[1]
1108
1109 # setup the prefixes
1110 len = linelen - addchars - length(caption);
1111 begin_prefix = "%%";
1112 cnt = 0;
1113 while ( cnt < len) {
1114 begin_prefix = begin_prefix "=";
1115 cnt++;
1116 };
1117 begin_prefix = begin_prefix ">";
1118 end_prefix = begin_prefix;
1119 sub(/%%/, "%%==", end_prefix);
1120 % \end{macrocode} ^^A $
1121 % \changes{v09}{09/04/05}{rewrote the check of the flags}
1122 % Now we distinguish between |join|- and |combine|-mode and the default mode:
1123 % \begin{macrocode}
1124 if ( join ) {
1125 % \end{macrocode} ^^A $
1126 % In |join|-mode we have to collect all informations about chunks into one
1127 % linerange, this is done by
1128 % \begin{macrocode}
1129 linerange = linerange ", " start "-" $1-1;
1130 } else if ( combine ) {
1131 % \end{macrocode} ^^A $
1132 % \changes{v11}{09/04/15}{rewrote some code for adding the combine mode}
1133 % In combine mode we need the whole tag but without leading or trailing
1134 % blanks, so we delete leading spaces.
1135 % \begin{macrocode}
1136 sub(/ /, "", closing_tag)
1137 if ( combine_array[closing_tag] == "" ) {
1138 combine_array[closing_tag] = start "-" $1-1
1139 } else {
1140 combine_array[closing_tag] = \
1141 combine_array[closing_tag] ", " start "-" $1-1
1142 }
1143 if ( debugmode ) printf("combine_array: >%s<\n",\
1144 combine_array[closing_tag]) > "/dev/stderr"
1145 } else {
1146 % \end{macrocode} ^^A $
1147 % We are neither in |combine|- nor in |join|-mode, so we can print out the
1148 % separate linechunks directly.
1149 %
1150 % The line range for a separated chunk is calculated by
1151 % \begin{macrocode}
1152 linerange = start "-" $1-1;
1153 if ( command ) {
1154 print_command(\
1155 (identifier toB26(idPt++)), \
1156 linerange);
1157 } else {
1158 print_linerange(\
1159 (identifier toB26(idPt++)), \
1160 caption, linerange);
1161 }
1162 }
1163 } else if ( opening_tag != closing_tag ) {
1164 print_error($1, "opening and closing tags differ")
1165 } else {
1166 print_error($1, "unknown error")
1167 }
1168 }
1169 }
1170 }
1171 }
1172 END {
1173 % \end{macrocode} ^^A $
1174 % There may be an erroneous open group, this is announced now.
1175 % \changes{v56}{10/03/09}{added handling of missing "ee" declarations}
1176 % \begin{macrocode}
1177 if ( is_opened ) {
1178 print_error($1, "missing \"ee\" declaration")
1179 }
1180 % \end{macrocode} ^^A $
1181 % And now for the post processing \ldots
1182 % \begin{macrocode}
1183 caption = "\\lstinline|" file "|";
1184 if ( join ) {
1185 sub(/, /, "", linerange);
1186 if ( command ) {
1187 print_command(identifier, linerange);
1188 } else {
1189 caption = "\\lstinline|" file "|";
1190 print_linerange(identifier, caption, linerange);
1191 }
1192 } else if ( combine ) {
1193 for ( range in combine_array ) {
1194 % \end{macrocode} ^^A $
1195 % In combine mode we prefix the |\lstdef|-command by the tag to make the
1196 % association easier.
1197 % \begin{macrocode}
1198 if ( debugmode ) printf("range: %s, combine_array[range]: >%s<\n", \
1199 range, combine_array[range]) > "/dev/stderr"
1200 printf("%%%%-->> %s <<--\n", range)
1201 if ( command ) {
1202 print_command((identifier toB26(idPt++)), \
1203 combine_array[range]);
1204 } else {
1205 print_linerange((identifier toB26(idPt++)), caption, \
1206 combine_array[range]);
1207 }
1208 }
1209 }
1210 }
1211 % \end{macrocode} ^^A $
1212 %
1213 % \changes{v25}{09/08/21}{corrected some leading spaces before the beginning
1214 % percent sign of a line}
1215 % Finally there are some helper functions. We start with
1216 % |replace_characters|. It replaces characters that are not allowed in
1217 % \TeX-commands like "\_", "\.-" from an identifier and turns
1218 % it into camel case notation. Its arguments are:
1219 % \begin{enumerate}
1220 % \item |identifier|---the identifier with underscore characters
1221 % \end{enumerate}
1222 % \begin{macrocode}
1223 function replace_characters(identifier) {
1224 tmp = ""
1225 toUppercase = 0
1226 n = split(identifier, sequence, "") # split the string into an array
1227 # of single characters
1228 for ( i = 1; i <= n; i++ )
1229 {
1230 if ( (sequence[i] == "_") || (sequence[i] == "-") ) {
1231 toUppercase = 1
1232 } else {
1233 if ( toUppercase ) {
1234 cTmp = toupper(sequence[i])
1235 tmp = (tmp cTmp)
1236 toUppercase = 0
1237 } else {
1238 tmp = (tmp sequence[i])
1239 }
1240 }
1241 }
1242 return tmp
1243 }
1244 % \end{macrocode}
1245 %
1246 % |print_command| generates the |\lstdef|-line. Its arguments are:
1247 % \begin{enumerate}
1248 % \item |identifier|---the identifier, which can be used in the
1249 % \LaTeX-source to format a range of lines.
1250 % \item |linerange|---a linerange or a list of line ranges (in join or
1251 % combine mode)
1252 % \end{enumerate}
1253 % \begin{macrocode}
1254 function print_command(identifier, linerange) {
1255 if ( debugmode ) printf("print_command.linerange: >%s<\n", linerange) > "/dev/stderr"
1256 print break_line("\\lstdef{" identifier "}{" inputfile "}{" \
1257 linerange "}", linelen)
1258 }
1259 % \end{macrocode}
1260 %
1261 % \changes{v65}{10/06/28}{added print\_break function call to print\_linerange}
1262 % |print_linerange| does something similar: instead of defining an identifier it
1263 % prints out a bunch of lines, which can be pasted into the
1264 % \LaTeX-source. Its arguments are
1265 % \begin{enumerate}
1266 % \item |identifier|---the identifier, an environment which has to be
1267 % defined in advance
1268 % \item |caption|---title or caption, taken either from surrounding
1269 % environment or from the file name (in join mode)
1270 % \item |linerange|---a linerange or a list of line ranges (in join or
1271 % combine mode)
1272 % \end{enumerate}
1273 % \begin{macrocode}
1274 function print_linerange(identifier, caption, linerange) {
1275 print break_line(begin_prefix "begin{" \
1276 identifier"}\n{%\n \\def\\inputfile{%\n " inputfile "%\n }");
1277 local_style = "";
1278 if ( header )
1279 {
1280 print " \\ifLecture{%\n \\lstdefinestyle{localStyle}{%\n " \
1281 "caption={" caption"}\n }%\n }\n {%\n" \
1282 " \\lstdefinestyle{localStyle}{%\n" \
1283 " title={" caption "}\n }%\n }";
1284 local_style="style=localStyle, "
1285 }
1286 print " \\lstinputlisting[" local_style "linerange={" linerange "}]" \
1287 "{%\n \\inputfile\n }\n" \
1288 "}%\n" end_prefix "end{"identifier"}";
1289 }
1290 % \end{macrocode}
1291 %
1292 % |print_error| prints out errors to stderr. Its arguments are
1293 % \begin{enumerate}
1294 % \item |linenumber|---the number of the line/record where the error happens
1295 % \item |error_message|---the error message
1296 % \end{enumerate}
1297 % \begin{macrocode}
1298 function print_error(linenumber, error_message)
1299 {
1300 printf "%--> error (line number %d): %s\n", \
1301 linenumber, error_message > "/dev/stderr"
1302 }
1303 % \end{macrocode}
1304 %
1305 % |break_line| breaks a (long) line into parts, which each have a length less
1306 % than a given line length. Its arguments are:
1307 % \begin{enumerate}
1308 % \item |input_line|---the line to bwe broken
1309 % \item |line_len|---the target length
1310 % \end{enumerate}
1311 % |input_line| may contain line breaks, so the results may look odd.
1312 % \begin{macrocode}
1313 function break_line(input_line, line_len) {
1314 n = split(input_line, parts, "/");
1315 output_line = parts[1];
1316 len_curr = length(output_line)
1317 for ( i = 2; i <= n; i++ ) {
1318 len_next = length(parts[i])
1319 if ( len_curr + len_next + 1 < linelen ) {
1320 output_line = output_line "/" parts[i];
1321 len_curr += len_next + 1 # continue current line
1322 } else {
1323 output_line = output_line "%\n /" parts[i];
1324 len_curr = len_next + 7 # start a new line
1325 }
1326 }
1327 return output_line
1328 }
1329 % \end{macrocode}
1330 %
1331 % \changes{v27}{09/08/21}{changed the conversion algorithm}
1332 % \changes{v25}{09/08/21}{changed the numbering of chunks by introducing the function
1333 % toB26}
1334 % |toB26| converts its integer argument into a number with the base
1335 % of 26, the number's digits are upper case characters. Its arguments are:
1336 % \begin{enumerate}
1337 % \item |n10|---the number to convert (base 10)
1338 % \end{enumerate}
1339 % \begin{macrocode}
1340 function toB26(n10) {
1341 v26 = ""
1342 do {
1343 remainder = n10%26
1344 v26 = idArray[remainder+1] v26
1345 n10 = int(n10/26)
1346 } while ( n10 != 0 )
1347 return v26
1348 }
1349 '
1350 return $?
1351 }
1352
1353 if [ $# -eq 0 ]
1354 then
1355 show_usage
1356 fi
1357 % \end{macrocode}
1358 % Processing the options is done by means of getop, see |man getopt|
1359 % \begin{macrocode}
1360 GETOPT=$(getopt -o ceghno:: \
1361 --longoptions command,debug-mode,ext,help,no-header,output-file:: \
1362 -n ${ME} -- "$@")
1363
1364 if [ $? -ne 0 ] # no success
1365 then
1366 show_usage
1367 fi
1368
1369 eval set -- "$GETOPT"
1370
1371 while true
1372 do
1373 case "$1" in
1374 -c|--command) COMMAND=1; HEADER=0; shift;;
1375 -e|--ext) EXTENSION=1; shift;;
1376 -g|--debug-mode) DEBUG_MODE=1; shift;;
1377 -h|--help) show_usage ;;
1378 -n|--no-header) HEADER=0; shift;;
1379 -o|--output-file)
1380 % \end{macrocode}
1381 % |o| has an optional argument. As we are in quoted mode, an empty
1382 % parameter will be generated if its optional argument is not found.
1383 % \begin{macrocode}
1384 case "$2" in
1385 "") OUTFILE=$(basename $(pwd)).lst; shift 2 ;;
1386 *) OUTFILE=$2; shift 2 ;;
1387 esac ;;
1388 --) shift ; break ;;
1389 *) show_usage ;;
1390 esac
1391 done
1392 % \end{macrocode}
1393 % If the output-file is set, redirect output to it's value.
1394 % \begin{macrocode}
1395 if [ -n "${OUTFILE}" ]
1396 then
1397 if [ -f "${OUTFILE}" ]
1398 then
1399 printf "%s\n" "%--> file \"${OUTFILE}\" already exists, creating backup"
1400 mv ${OUTFILE} ${OUTFILE}~
1401 fi
1402 exec > ${OUTFILE} # redirect stdout to ${OUTFILE}
1403 CURR_DIR=$(basename $(pwd))
1404 print_header ${OUTFILE} ${CURR_DIR}
1405 fi
1406
1407 # now take all remaining arguments (should be all filenames) and do the job
1408 for arg do
1409 printf "%s\n" "%%--> processing file \"$arg\"" 1>&2 # echo the current
1410 # filename to stderr
1411 do_the_job $arg
1412 done
1413
1414 ### listings-ext.sh ends here
1415 %</scriptfile>
1416 % \end{macrocode} ^^A $
1417 %
1418 %
1419 % \subsection[Example/Test Files]{Example and Test Files For Testing The Macros}
1420 % \label{sec:example-files}
1421 %
1422 % In this section there are introduced some examples of source code files
1423 % (C, Fortran and Java) and corresponding test files to show the behaviour
1424 % of the package and the script.
1425 %
1426 %
1427 % \subsubsection{A Small Java-Example With Correct Grouping}
1428 % \label{sec:small-java-example-correct}
1429 %
1430 % The correct (Java) source file is
1431 % \begin{macrocode}
1432 %<*example1>
1433 package application.helloworld;
1434 // be: packages
1435 import java.util.Locale;
1436 import java.util.MissingResourceException;
1437 import java.util.ResourceBundle;
1438 // ee: packages
1439 /**
1440 * HelloWorld.java
1441 */
1442 public class HelloWorld
1443 {
1444 // be: specific constructor
1445 public HelloWorld()
1446 {
1447 System.out.println("Object HelloWorld created");
1448 } // end of specific constructor "HelloWorld()"
1449 // ee: specific constructor
1450
1451 public static final void main(final String[] args)
1452 {
1453 String baseName = "HelloWorld";
1454 // be: using the resource bundle
1455 ResourceBundle rb = ResourceBundle.getBundle(baseName);
1456 String greetings = rb.getString("hello_msg");
1457 // ee: using the resource bundle
1458 System.out.printf("%s\n", greetings);
1459 } // end of method "main(String[] args)"
1460 } // end of class "HelloWorld"
1461 %</example1>
1462 % \end{macrocode}
1463 % We have two correct groups, the output for |-c| should contain
1464 % two lines like
1465 %\begin{verbatim}
1466 %\lstdef{listingsExtTestAA}{/home/xxx/texmf/source/latex%
1467 % /listings-ext/listings-ext_test_a.java}{3-5}
1468 %\lstdef{listingsExtTestAB}{/home/xxx/texmf/source/latex%
1469 % /listings-ext/listings-ext_test_a.java}{20-22}
1470 %\lstdef{listingsExtTestAC}{/home/xxx/texmf/source/latex%
1471 % /listings-ext/listings-ext_test_a.java}{29-30}
1472 %\end{verbatim}
1473 %
1474 % A small \LaTeX-file to test this case is
1475 %
1476 % \begin{macrocode}
1477 %<*test1>
1478 \documentclass[a4paper,12pt]{article}
1479 \usepackage[T1]{fontenc}
1480 \usepackage{listings-ext}
1481 \begin{document}
1482 \input{listings-ext.lst}
1483 \lstuse[style=bw-code, language=Java]{listingsExtExmplAC}
1484 \end{document}
1485 %</test1>
1486 % \end{macrocode}
1487 %
1488 %
1489 % \subsubsection{Small Java-Examples With Wrong Initialisation or Ending}
1490 % \label{sec:small-java-example-wrong-initialisation}
1491 %
1492 % In the following Java source code the initial tag \verb*-be: - is
1493 % missing. Processing the file by |listings-ext.sh| must give an
1494 % appropriate error message.
1495 % \begin{macrocode}
1496 %<*example2>
1497 // ee: package declaration
1498 package application.helloworld;
1499 // ee: package declaration
1500 import java.util.Locale;
1501 import java.util.MissingResourceException;
1502 import java.util.ResourceBundle;
1503
1504 /**
1505 * HelloWorld.java
1506 */
1507
1508 public class HelloWorld
1509 {
1510 // be: specific constructor
1511 public HelloWorld()
1512 {
1513 System.out.println("Object HelloWorld created");
1514 } // end of specific constructor "HelloWorld()"
1515 // ee: specific constructor
1516
1517 public static final void main(final String[] args)
1518 {
1519 String baseName = "HelloWorld";
1520 ResourceBundle rb = ResourceBundle.getBundle(baseName);
1521 String greetings = rb.getString("hello_msg");
1522 System.out.printf("%s\n", greetings);
1523 } // end of method "main(String[] args)"
1524 } // end of class "HelloWorld"
1525 %</example2>
1526 % \end{macrocode}
1527 %
1528 % \changes{v56}{10/03/09}{added test case for missing "ee" declarations}
1529 % In the following Java source code the closing tag \verb*-ee: - is
1530 % missing. Processing the file by |listings-ext.sh| must give an
1531 % appropriate error message.
1532 % \begin{macrocode}
1533 %<*example3>
1534 package application.helloworld;
1535 import java.util.Locale;
1536 import java.util.MissingResourceException;
1537 import java.util.ResourceBundle;
1538
1539 /**
1540 * HelloWorld.java
1541 */
1542
1543 public class HelloWorld
1544 {
1545 // be: specific constructor
1546 public HelloWorld()
1547 {
1548 System.out.println("Object HelloWorld created");
1549 } // end of specific constructor "HelloWorld()"
1550 // ee: specific constructor
1551
1552 // be: the main method
1553 public static final void main(final String[] args)
1554 {
1555 String baseName = "HelloWorld";
1556 ResourceBundle rb = ResourceBundle.getBundle(baseName);
1557 String greetings = rb.getString("hello_msg");
1558 System.out.printf("%s\n", greetings);
1559 } // end of method "main(String[] args)"
1560 } // end of class "HelloWorld"
1561 %</example3>
1562 % \end{macrocode}
1563 %
1564 % \subsubsection{A Small Java-Example With Correct Grouping}
1565 % \label{sec:small-java-example-correct}
1566 %
1567 % \changes{v58}{10/05/18}{corrected example 4}
1568 % \begin{macrocode}
1569 %<*example4>
1570 package application.helloworld;
1571 // be: packages
1572 import java.util.Locale;
1573 import java.util.MissingResourceException;
1574 import java.util.ResourceBundle;
1575 // ee: packages
1576 // be: introductory comment
1577 /**
1578 * HelloWorld.java
1579 *
1580 *
1581 * <br>
1582 * Created: : 2007/04/12 11:24:48$
1583 *
1584 * @author <a href="mailto:N.N_(at)_fh-aachen.de">N.N.</a>
1585 * @version : 0.0$
1586 */
1587 // ee: introductory comment
1588 // be: class declaration
1589 public class HelloWorld
1590 // ee: class declaration
1591 {
1592 // be: specific constructor
1593 public HelloWorld()
1594 {
1595 System.out.println("Object HelloWorld created");
1596 } // end of specific constructor "HelloWorld()"
1597 // ee: specific constructor
1598
1599 public static final void main(final String[] args)
1600 {
1601 String baseName = "HelloWorld";
1602 // ee: using the resource bundle
1603 ResourceBundle rb = ResourceBundle.getBundle(baseName);
1604 String greetings = rb.getString("hello_msg");
1605 // ee: using the resource bundle
1606 System.out.printf("%s\n", greetings);
1607 } // end of method "main(String[] args)"
1608 } // end of class "HelloWorld"
1609 %</example4>
1610 % \end{macrocode}
1611 %
1612 % \changes{v11}{09/04/15}{added a test for combine mode}
1613 % \subsubsection{A Small Java-Example With Correct Grouping, Showing the
1614 % Combine Mode}
1615 % \label{sec:java-combine}
1616 %
1617 % We have two correct groups, |ce| at the beginning of the file sets the
1618 % combine mode, so the output for |-c| should contain three lines like
1619 %\begin{verbatim}
1620 %\lstdef{listingsExtTestDA}{/home/xxx/texmf/source/latex%
1621 % /listings-ext/listings-ext_test_a.java}{12-13, 29-29}
1622 %\lstdef{listingsExtTestDB}{/home/xxx/texmf/source/latex%
1623 % /listings-ext/listings-ext_test_a.java}{16-19}
1624 %\lstdef{listingsExtTestDC}{/home/xxx/texmf/source/latex%
1625 % /listings-ext/listings-ext_test_a.java}{23-26}
1626 %\end{verbatim}
1627 %
1628 % \begin{macrocode}
1629 %<*example5>
1630 // ce: combine
1631 /**
1632 * HelloWorld.java
1633 // be: the class
1634 public class HelloWorld
1635 {
1636 // ee: the class
1637 // be: specific constructor
1638 public HelloWorld()
1639 {
1640 System.out.println("Object HelloWorld created");
1641 } // end of specific constructor "HelloWorld()"
1642 // ee: specific constructor
1643
1644 // be: main method
1645 public static final void main(final String[] args)
1646 {
1647 HelloWorld h = new HelloWorld();
1648 } // end of method "main(String[] args)"
1649 // ee: main method
1650 // be: the class
1651 } // end of class "HelloWorld"
1652 // ee: the class
1653 %</example5>
1654 % \end{macrocode}
1655 %
1656 % The result of the call |listings-ext.sh -c -o listings-ext_test_d.java|
1657 % must contain the lines
1658 % \begin{verbatim}
1659 % %-->> main method <<--
1660 % \lstdef{listingsExtExmplDA}{/home/ax006ho/TeX/texmf/source/latex%
1661 % /listings-ext%
1662 % /listings-ext_exmpl_d.java}{16-19}
1663 % %-->> the class <<--
1664 % \lstdef{listingsExtExmplDB}{/home/ax006ho/TeX/texmf/source/latex%
1665 % /listings-ext%
1666 % /listings-ext_exmpl_d.java}{5-6, 22-22}
1667 % %-->> specific constructor <<--
1668 % \lstdef{listingsExtExmplDC}{/home/ax006ho/TeX/texmf/source/latex%
1669 % /listings-ext%
1670 % /listings-ext_exmpl_d.java}{9-12}
1671 % \end{verbatim}
1672 %
1673 % So a small \LaTeX-file to test this case is
1674 %
1675 % \begin{macrocode}
1676 %<*test2>
1677 \documentclass[a4paper,12pt]{article}
1678 \usepackage[T1]{fontenc}
1679 \usepackage[style=colored-code]{listings-ext}
1680 \begin{document}
1681 \lstcheck{listingsExtExmplDC}{listings-ext.lst}
1682 \lstuse[language=Java]{listingsExtExmplDC}
1683 \end{document}
1684 %</test2>
1685 % \end{macrocode}
1686 %
1687 %
1688 % \changes{v16}{09/08/18}{enhanced the .el-file}
1689 % \subsection[AUC\TeX{} Style file]{Style file for AUC\TeX{} to ease the
1690 % Editing with \XEmacs{}}
1691 % \label{sec:AUCTeX}
1692 %
1693 % \XEmacs{} and the package AUC\TeX{}
1694 % (\url{http://www.gnu.org/software/auctex/}) form a powerful tool for
1695 % creating and editing of \TeX/\LaTeX{} files. If there is a suitable
1696 % AUCTeX style file for a \LaTeX{} package like the hereby provided
1697 % \listingsextSty{} package, then there is support for many common
1698 % operations like creating environments, inserting macros, prompting for
1699 % arguments and so on. The following elisp code provides such a style
1700 % file; it must be copied to a place, where \XEmacs{} can find it after its
1701 % creation.%
1702 %
1703 % This file is still in a development phase, i.\,e. one can work with it,
1704 % but there is a couple of missing things as for example font locking or
1705 % the automatic insertion of \cs{switch} commands according to the user's
1706 % input.
1707 %
1708 % \begin{macrocode}
1709 %<*auctex>
1710 ;;; listings-ext.el --- AUCTeX style for `listings-ext.sty'
1711
1712 ;; Copyright (C) 2008-2010 Free Software Foundation, Inc.
1713
1714 ;; Maintainer: Jobst Hoffmann, <j.hoffmann_(at)_fh-aachen.de>
1715 ;; $Author: ax006ho $
1716 ;; $Date: 2010-06-29 18:38:12 +0200 (Di, 29 Jun 2010) $
1717 ;; $Revision: 67 $
1718 ;; Keywords: tex
1719
1720 ;;; Commentary:
1721 ;; This file adds support for `listings-ext.sty'
1722
1723 ;;; Code:
1724 (TeX-add-style-hook
1725 "listings-ext"
1726 (lambda ()
1727 (TeX-add-symbols
1728 '("lstcheck" "identifier" TeX-arg-input-file 0)
1729 '("lstdef" "identifier" TeX-arg-input-file "line range" 0)
1730 '("lstuse" ["options"] "identifier"0))
1731
1732 ;; Filling
1733
1734 ;; Fontification
1735 (when (and (featurep 'font-latex)
1736 (eq TeX-install-font-lock 'font-latex-setup))
1737 (add-to-list 'font-latex-match-function-keywords-local "lstcheck")
1738 (add-to-list 'font-latex-match-function-keywords-local "lstdef")
1739 (add-to-list 'font-latex-match-function-keywords-local "lstuse")
1740 (font-latex-match-function-make)
1741 ;; For syntactic fontification, e.g. verbatim constructs
1742 (font-latex-set-syntactic-keywords)
1743 ;; Tell font-lock about the update.
1744 (setq font-lock-set-defaults nil)
1745 (font-lock-set-defaults))))
1746
1747 ;; preparing of environments isn't necessary
1748
1749 ;; support for options
1750 (defvar LaTeX-listings-ext-package-options nil
1751 "Package options for the listings-ext package.")
1752
1753 ;;; listings-ext.el ends here.
1754 %</auctex>
1755 % \end{macrocode}
1756 %
1757 %
1758 % \changes{v50}{10/02/15}{small changes to the Makefile: main documentation now in .pdf-format}
1759 % \changes{v47}{09/08/31}{removed unnecessary files from the distribution}
1760 % \changes{v45}{09/08/31}{some small corrections for the test files}
1761 % \changes{v41}{09/08/27}{Makefile: removed TODO from the distributed tar-file}
1762 % \changes{v38}{09/08/27}{Makefile: corrected the examples-part}
1763 % \changes{v33}{09/08/23}{Makefile: now all targets are described}
1764 % \changes{v33}{09/08/23}{Makefile: mirrored the move from rcs to subversion}
1765 % \changes{v33}{09/08/23}{Makefile: introduced implicit rules}
1766 % \changes{v33}{09/08/23}{Makefile: removed some small glitches}
1767 % \changes{v16}{09/08/18}{better documentation of the Makefile}
1768 % \changes{v16}{09/08/18}{removed unnecessary code from the Makefile}
1769 % \changes{v16}{09/08/18}{corrected small glitches in the Makefile}
1770 % \subsection[Makefile]{%
1771 % Makefile for the automated generation of the documentation and tests
1772 % of the \listingsextSty}
1773 % \label{sec:Makefile}
1774 %
1775 % Working with \ext{.dtx}-packages is much easier, if there is a tool
1776 % for the automated processing of the mean steps like formatting or
1777 % unpacking. For systems based on Unix/Linux one can implement that with
1778 % |make| and a an adequate |Makefile|. Here the |Makefile| is integrated
1779 % into the documentation, the special syntax with tabulator characters is
1780 % generated by a short program, which is shown below. Using the |Makefile|
1781 % isn't explained here, the experienced user can get this information
1782 % directly from the |Makefile|.
1783 %
1784 % \changes{v03}{08/02/27}{remove the intermediate PostScript file after
1785 % generating the .pdf-output from it}
1786 % \begin{macrocode}
1787 %<*makefile>
1788 #-----------------------------------------------------------------------
1789 # Purpose: generation of the documentation of the listings-ext package
1790 # Notice: this file can be used without any change only with dmake and
1791 # the option "-B", this option lets dmake interpret the leading
1792 # spaces as distinguishing characters for commands in the make
1793 # rules.
1794 # The necessary changes for the common make can be applied by
1795 # the script listings-ext.makemake
1796 #
1797 # Rules:
1798 # - all: generate all the files and the basic
1799 # documentation
1800 # - develop: generate the documentation with revision
1801 # - develop-pdf: history and source code (the latter provides
1802 # a .pdf file as output)
1803 # - history: generate the documentation with revision
1804 # - history-pdf: history (the latter provides a .pdf file as
1805 # output)
1806 # - examples: format the examples
1807 # - install: install the package in a standard TDS tree
1808 # - uninstall: uninstall the package from a standard TDS
1809 # tree
1810 # - clean: clean the directory of intermediate files
1811 # - clean-examples: example and test files
1812 # - clean-support: support files
1813 # - realclean: all but the pure source
1814 # files
1815 # - tar-src: create a gzipped .tar-file of the pure
1816 # source files
1817 # - tar-dist: create a gzipped .tar-file containing
1818 # version information
1819 #
1820 # Author: Jobst Hoffmann, Fachhochschule Aachen, Campus Juelich
1821 # $Date: 2010-06-29 18:38:12 +0200 (Di, 29 Jun 2010) $
1822 #-----------------------------------------------------------------------
1823
1824 # The texmf-directory, where to install new stuff (see texmf.cnf)
1825 # If you don't know what to do, search for directory texmf at /usr.
1826 # With teTeX and linux often one of following is used:
1827 #INSTALLTEXMF=/usr/TeX/texmf
1828 #INSTALLTEXMF=/usr/local/TeX/texmf
1829 #INSTALLTEXMF=/usr/share/texmf
1830 #INSTALLTEXMF=/usr/local/share/texmf
1831 # user tree:
1832 #INSTALLTEXMF=$(HOME)/texmf
1833 # Try to use user's tree known by kpsewhich:
1834 INSTALLTEXMF=`kpsewhich --expand-var '$$TEXMFHOME'`
1835 # Try to use the local tree known by kpsewhich:
1836 #INSTALLTEXMF=`kpsewhich --expand-var '$$TEXMFLOCAL'`
1837 # But you may set INSTALLTEXMF to every directory you want.
1838 # Use the following, if you only want to test the installation:
1839 #INSTALLTEXMF=/tmp/texmf
1840
1841 # If texhash must run after installation, you can invoke this:
1842 TEXHASH=texhash
1843
1844 # change this to the directory which contains the graphic files
1845 GRAPHICPATH=.
1846
1847 ######### Edit the following only, if you want to change defaults!
1848
1849 # The directory, where to install *.cls and *.sty
1850 CLSDIR=$(INSTALLTEXMF)/tex/latex/jhf/$(PACKAGE)
1851
1852 # The directory, where to install documentation
1853 DOCDIR=$(INSTALLTEXMF)/doc/latex/jhf/$(PACKAGE)
1854
1855 # The directory, where to install the sources
1856 SRCDIR=$(INSTALLTEXMF)/source/latex/jhf/$(PACKAGE)
1857
1858 # The directory, where to install demo-files
1859 # If we have some, we have to add following 2 lines to install rule:
1860 # $(MKDIR) $(DEMODIR); \
1861 # $(INSTALL) $(DEMO_FILES) $(DEMODIR); \
1862 DEMODIR=$(DOCDIR)/demo
1863
1864 # We need this, because the documentation needs the classes and packages
1865 # It's not really a good solution, but it's a working solution.
1866 TEXINPUTS := $(PWD):$(TEXINPUTS)
1867
1868 # To generate the version number of the distribution from the source
1869 VERSION_L := latex getversion | grep '^VERSION'
1870 VERSION_S := `latex getversion | grep '^VERSION' | \
1871 sed 's+^VERSION \\(.*\\) of .*+\\1+'`
1872 ########################################################################
1873 # End of customization section
1874 ########################################################################
1875
1876 # formatting tools
1877 BIBTEX = bibtex
1878 DVIPS = dvips
1879 LATEX = latex
1880 PDFLATEX = pdflatex
1881 TEX = tex
1882 PS2PDF = ps2pdf
1883
1884 # postscript viewer
1885 GV = gv
1886
1887 # tarring options
1888 DATE = `date +%Y-%m-%d`
1889 TAR_SRC = $(PACKAGE)_$(DATE)_source.tar.gz
1890 EXsvn = --exclude .svn --exclude auto
1891
1892 # formatting options
1893 COMMON_OPTIONS =
1894 HISTORY_OPTIONS = \RecordChanges
1895 DEVELOPER_OPTIONS = \AlsoImplementation\RecordChanges\CodelineIndex\EnableCrossrefs
1896 DEVELOPER_OPTIONS_FINAL = \AlsoImplementation\CodelineIndex\DisableCrossrefs\RecordChanges
1897
1898 PACKAGE = listings-ext
1899
1900 DISTRIBUTION_FILES = $(PACKAGE).pdf $(PACKAGE).dtx \
1901 $(PACKAGE).ins README
1902
1903 .SUFFIXES: # Delete the default suffixes
1904 .SUFFIXES: .dtx .dvi .ins .ps .pdf .sty # Define our suffix list
1905
1906 ## Main Targets
1907
1908 # strip off the comments from the package
1909 $(PACKAGE).sty $(PACKAGE)-test-*.tex: $(PACKAGE).ins $(PACKAGE).dtx
1910 +$(LATEX) $<; \
1911 sh $(PACKAGE).makemake
1912
1913 all: $(PACKAGE).dvi
1914
1915 # generate the documentation
1916 $(PACKAGE).dvi: $(PACKAGE).dtx $(PACKAGE).sty
1917 +rm -f *.ind *.gls
1918 +$(LATEX) "\AtBeginDocument{$(COMMON_OPTIONS)}\input{$<}"
1919 +$(BIBTEX) $(PACKAGE)
1920 +$(LATEX) "\AtBeginDocument{$(COMMON_OPTIONS)}\input{$<}"
1921 +$(LATEX) "\AtBeginDocument{$(COMMON_OPTIONS)}\input{$<}"
1922
1923 # generate the documentation with revision history
1924 history: $(PACKAGE).dtx $(PACKAGE).sty
1925 +$(LATEX) "\AtBeginDocument{$(COMMON_OPTIONS)$(HISTORY_OPTIONS)}\input{$<}"
1926 +$(BIBTEX) $(PACKAGE)
1927 +$(LATEX) "\AtBeginDocument{$(COMMON_OPTIONS)$(HISTORY_OPTIONS)}\input{$<}"
1928 +makeindex -s gind.ist $(PACKAGE).idx
1929 +makeindex -s gglo.ist -o $(PACKAGE).gls -t $(PACKAGE).glg $(PACKAGE).glo
1930 +$(LATEX) "\AtBeginDocument{$(COMMON_OPTIONS)$(HISTORY_OPTIONS)}\input{$<}"
1931
1932 # generate the documentation for the developer
1933 develop: $(PACKAGE).dtx $(PACKAGE).sty
1934 +$(LATEX) "\AtBeginDocument{$(DEVELOPER_OPTIONS)}\input{$<}"
1935 +$(BIBTEX) $(PACKAGE)
1936 +$(LATEX) "\AtBeginDocument{$(DEVELOPER_OPTIONS)}\input{$<}"
1937 +makeindex -s gind.ist $(PACKAGE).idx
1938 +makeindex -s gglo.ist -o $(PACKAGE).gls -t $(PACKAGE).glg $(PACKAGE).glo
1939 +$(LATEX) "\AtBeginDocument{$(DEVELOPER_OPTIONS_FINAL)}\input{$<}"
1940
1941 develop-pdf: develop
1942 +$(DVIPS) $(PACKAGE).dvi; \
1943 $(PS2PDF) $(PACKAGE).ps; \
1944 rm $(PACKAGE).ps
1945
1946 history-pdf: history
1947 +$(DVIPS) $(PACKAGE).dvi; \
1948 $(PS2PDF) $(PACKAGE).ps; \
1949 rm $(PACKAGE).ps
1950
1951 # implicit rule for generating the .pdf files
1952 %%%.pdf: %.dvi
1953 +$(DVIPS) $<; \
1954 $(PS2PDF) $(<:.dvi=.ps); \
1955 rm $(<:.dvi=.ps)
1956
1957 # format the example/test files
1958 examples:
1959 sh listings-ext.sh -c -o *.java; \
1960 for i in $(PACKAGE)*test*.tex; do \
1961 f=$${i%.tex}; \
1962 $(LATEX) "\nofiles\input{$$f}"; \
1963 $(DVIPS) -o $$f.ps $$f.dvi; \
1964 $(PS2PDF) $$f.ps; \
1965 rm $$f.dvi $$f.ps; \
1966 done
1967
1968 install: $(PACKAGE).dtx $(PACKAGE).pdf
1969 [ -d $(CLSDIR) ] || mkdir -p $(CLSDIR)
1970 [ -d $(DOCDIR) ] || mkdir -p $(DOCDIR)
1971 [ -d $(SRCDIR) ] || mkdir -p $(SRCDIR)
1972 cp $(PACKAGE).sty $(CLSDIR)
1973 cp $(PACKAGE).pdf $(DOCDIR)
1974 cp $(PACKAGE).ins $(SRCDIR)
1975 cp $(PACKAGE).dtx $(SRCDIR)
1976 cp $(PACKAGE)_{exmpl,test}_* $(SRCDIR)
1977 cp README $(SRCDIR)
1978 cp THIS-IS-VERSION-$(VERSION) $(SRCDIR)
1979
1980 uninstall:
1981 rm -f $(CLSDIR)/$(PACKAGE).sty
1982 rm -fr $(DOCDIR)
1983 rm -fr $(SRCDIR)
1984
1985 ## Clean Targets
1986 clean:
1987 -rm -f *.aux *.dvi *.hd *.lof *.log *.lot *.tmp *.toc
1988 -rm -f *.idx *.ilg *.ind *.glg *.glo *.gls *.out
1989 -rm -f *.bbl *.blg *.bm *.brf *.hd
1990 -rm -f *.pdf *.ps
1991 -rm -f *.rel *.thm
1992
1993 clean-examples:
1994 -rm -f $(PACKAGE)_test* $(PACKAGE)_exmpl*
1995
1996 clean-support:
1997 -rm -f *.el *.sh
1998 -rm -f *.mk *.makemake
1999
2000 realclean: clean clean-examples clean-support
2001 -rm -f *~ *.bib *.cfg *.sty *.tex
2002 -rm -f Makefile
2003
2004 ### create packed files
2005 tar-src:
2006 $(MAKE) realclean
2007 @cd ..; tar $(EXsvn) -czvf $(PACKAGE)/$(TAR_SRC) $(PACKAGE)
2008
2009 tar-dist: $(DISTRIBUTION_FILES)
2010 +rm -f THIS_IS_VERSION_* *.tgz; \
2011 $(VERSION_L) > THIS_IS_VERSION_$(VERSION_S); \
2012 tar cfvz $(PACKAGE)-$(VERSION_S).tgz $^ THIS_IS_VERSION_*; \
2013 rm getversion.log
2014 %</makefile>
2015 % \end{macrocode} ^^A $
2016 %
2017 % The following line -- stripped off as |listings-ext.makemake| -- can
2018 % be used with the command
2019 % \begin{verbatim}
2020 % sh listings-ext.makemake
2021 % \end{verbatim}
2022 % to generate the file |Makefile|, which can be further used to
2023 % generate the documentation with a common |make| like the GNU |make|.
2024 % \changes{v58}{10/05/18}{changed the .setup contents}
2025 % \begin{macrocode}
2026 %<*setup>
2027 #! /bin/sh
2028
2029 sed -e "`echo \"s/^ /@/g\" | tr '@' '\011'`" listings-ext.mk > Makefile && \
2030 rm listings-ext.mk
2031 %</setup>
2032 % \end{macrocode}
2033 %
2034 %
2035 % \changes{v50}{10/02/15}{added title to the section "getting the revision"}
2036 % \subsection{Automated Determining of the Revision Number}
2037 % \label{sec:automated-determining}
2038 %
2039 % The purpose of the following file is to determine the version of the
2040 % package for the case of creating a distribution version of the package.
2041 % \changes{v33}{09/08/23}{changed getversion.tex: introduced the date}
2042 % \begin{macrocode}
2043 %<*getversion>
2044 \documentclass{ltxdoc}
2045 \nofiles
2046 \usepackage{listings-ext}
2047 \GetFileInfo{listings-ext.sty}
2048 \typeout{VERSION \fileversion\space of \filedate}
2049 \begin{document}
2050 \end{document}
2051 %</getversion>
2052 % \end{macrocode}
2053 %
2054 % \Finale
2055 %
2056 %
2057 % \iffalse
2058 %<*bibtex>
2059 @Book{lingnau07:_latex_hacks,
2060 author = {Anselm Lingnau},
2061 title = {\LaTeX-Hacks},
2062 publisher = {O'Reilly},
2063 year = 2007,
2064 address = {Beijing; Cambridge; Farnham; K\"oln; Paris; Sebastopol;
2065 Taipei; Tokyo},
2066 edition = {1.},
2067 note = {Tipps \& Techniken f\"ur den professionellen Textsatz},
2068 language = {ngerman},
2069 }
2070 @Manual{Heinz:Listings-14,
2071 author = {Carsten Heinz and Brooks Moses},
2072 title = {The \textsf{listings} package},
2073 note = {Version 1.4},
2074 year = 2007,
2075 month = FEB,
2076 language = {english}
2077 }
2078 @Manual{FM:TheDocAndShortvrbPackages,
2079 author = {Frank Mittelbach},
2080 title = {{The {\sf doc} and {\sf shortvrb} Packages}},
2081 year = 2006,
2082 month = FEB,
2083 note = {version number 2.1d},
2084 language = {english}
2085 }
2086 @Manual{MittelbachDuchierBraams:DocStrip,
2087 author = {Frank Mittelbach and Denys Duchier and Johannes Braams
2088 and Marcin Woli\'nski and Mark Wooding},
2089 title = {{The {\sf DocStrip} program}},
2090 year = 2005,
2091 month = JUL,
2092 note = {version number 2.5d},
2093 language = {english}
2094 }
2095 %</bibtex>
2096 %<*hyperref>
2097 \ProvidesFile{hyperref.cfg}%
2098 [2009/08/23 v1.0 hyperref configuration of listings-ext]
2099 % Change default driver to "dvips" instead of "hypertex",
2100 % requires hyperref 2002/06/05 v6.72s
2101 \providecommand*{\Hy@defaultdriver}{hdvips}%
2102
2103 \hypersetup{
2104 ps2pdf, % the documentation uses ps2pdf
2105 colorlinks, % display links in the text coloured
2106 pdfpagemode=UseOutlines,
2107 plainpages=false,
2108 pagebackref=true, % one can jump from the bibliography to the
2109 % origin of the citations
2110 hyperindex=true, % index is linked
2111 bookmarks=true, % I want Acrobat bookmarks,
2112 bookmarksopen=true, % they should be shown when the foils
2113 % are displayed
2114 bookmarksnumbered=true, % numbering is on
2115 pdftitle={listings-ext},
2116 pdfsubject={A collection of LaTeX macros to support the automatic
2117 integration of parts of source files into a documentation}
2118 pdfauthor={Jobst Hoffmann,
2119 Fachhochschule Aachen J\"ulich Campus,
2120 <j.hoffmann_(at)_fh-aachen.de>},
2121 pdfkeywords={PDF, TeX, LaTeX, listings},
2122 }
2123 %</hyperref>
2124 % \fi
2125 \endinput
2126 %
2127 %% \CharacterTable
2128 %% {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
2129 %% 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
2130 %% Digits \0\1\2\3\4\5\6\7\8\9
2131 %% Exclamation \! Double quote \" Hash (number) \#
2132 %% Dollar \$ Percent \% Ampersand \&
2133 %% Acute accent \' Left paren \( Right paren \)
2134 %% Asterisk \* Plus \+ Comma \,
2135 %% Minus \- Point \. Solidus \/
2136 %% Colon \: Semicolon \; Less than \<
2137 %% Equals \= Greater than \> Question mark \?
2138 %% Commercial at \@ Left bracket \[ Backslash \\
2139 %% Right bracket \] Circumflex \^ Underscore \_
2140 %% Grave accent \` Left brace \{ Vertical bar \|
2141 %% Right brace \} Tilde \~}
2142 %
2143 %%% ^^A Local Variables:
2144 %%% ^^A mode: docTeX
2145 %%% ^^A TeX-master: t
2146 %%% ^^A mode: flyspell
2147 %%% ^^A ispell-local-dictionary: "english"
2148 %%% ^^A End:
2149 %
2150 % end of listings-ext.dtx