Debian Codegraph @

texmf-dist/source/latex/texments/texments.dtx

raw
1 % \iffalse meta-comment
2 %
3 % Copyright 2008 Marek Kubica, <[email protected]>
4 %
5 % This work may be distributed and/or modified under the
6 % conditions of the LaTeX Project Public License, either version 1.3c
7 % of this license or (at your option) any later version.
8 % The latest version of this license is in
9 % http://www.latex-project.org/lppl.txt
10 % and version 1.3c or later is part of all distributions of LaTeX
11 % version 2008/05/04 or later.
12 %
13 % This work has the LPPL maintenance status `maintained'.
14 %
15 % The Current Maintainer of this work is Marek Kubica.
16 %
17 % This work consists of the files textments.dtx and texments.ins
18 % and the derived file texments.sty.
19 %
20 % \fi
21 %
22 % \iffalse
23 %<*driver>
24 \ProvidesFile{texments.dtx}
25 %</driver>
26 %<package>\NeedsTeXFormat{LaTeX2e}
27 %<package>\ProvidesPackage{texments}
28 %<*package>
29 [2008/12/27 0.2.0 The Pygments source code highligher integrated into LaTeX documents]
30 %<package>\RequirePackage{fancyvrb}
31 %<package>\RequirePackage{color}
32 %<package>\RequirePackage{ifthen}
33 %</package>
34 %
35 %<*driver>
36 \documentclass{ltxdoc}
37 \usepackage{texments}[2008/12/27]
38 \usepackage{hyperref}
39 \EnableCrossrefs
40 \CodelineIndex
41 \RecordChanges
42 \hypersetup{
43 pdftitle={texments manual},
44 pdfsubject={Documentation of the texments LaTeX package},
45 pdfauthor={Marek Kubica},
46 pdfkeywords={pygments texments sourcecode highlight color},
47 }
48
49 \begin{document}
50 \DocInput{texments.dtx}
51 \PrintChanges
52 \PrintIndex
53 \end{document}
54 %</driver>
55 % \fi
56 %
57 % \CheckSum{57}
58 %
59 % \CharacterTable
60 % {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
61 % 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
62 % Digits \0\1\2\3\4\5\6\7\8\9
63 % Exclamation \! Double quote \" Hash (number) \#
64 % Dollar \$ Percent \% Ampersand \&
65 % Acute accent \' Left paren \( Right paren \)
66 % Asterisk \* Plus \+ Comma \,
67 % Minus \- Point \. Solidus \/
68 % Colon \: Semicolon \; Less than \<
69 % Equals \= Greater than \> Question mark \?
70 % Commercial at \@ Left bracket \[ Backslash \\
71 % Right bracket \] Circumflex \^ Underscore \_
72 % Grave accent \` Left brace \{ Vertical bar \|
73 % Right brace \} Tilde \~}
74 %
75 %
76 % \changes{v0.0.1}{2008/10/10}{Initial version}
77 % \changes{v0.1.0}{2008/10/10}{Properly repackaged}
78 % \changes{v0.2.0}{2008/12/23}{More documentation, commands, environments}
79 %
80 % \GetFileInfo{texments.dtx}
81 %
82 % \DoNotIndex{\newcommand,\newenvironment}
83 %
84 %
85 % \title{The \textsf{texments} package\thanks{This document
86 % corresponds to \textsf{texments}~\fileversion, dated \filedate.}}
87 % \author{Marek Kubica \\ \texttt{[email protected]}}
88 %
89 % \maketitle
90 %
91 % ^^A define gobble to yank the first char out, which is a '%'
92 % ^^A because of DocStrip
93 % \fvset{gobble=1}
94 %
95 % \section{Introduction}
96 %
97 % \textsf{texments} is a package that is used to connect the not-yet
98 % award winning source code colorizer library Pygments
99 % (\url{http://pygments.org/}) with \LaTeX{} documents. That means that
100 % it is neccessary to have Pygments installed and that the
101 % \texttt{pygmentize} command is available.
102 %
103 % \section{Usage}
104 %
105 % This package does not provide many fancy features, it is just meant
106 % as an easy bridge between the highlighter and LaTeX. It calls
107 % internally the \texttt{pygmentize} command, so you need to start it
108 % with \texttt{-shell-escape} activated. \texttt{-shell-escape}
109 % allows the \LaTeX{} processor to call arbitary shell commands which
110 % can be a security problem if compiling untrusted source, but
111 % unfortunately this is unavoidable because \texttt{pygmentize} is
112 % an external command.
113 %
114 % Using \textsf{texments} is simple: you only need to add
115 % \texttt{\textbackslash{}usepackage\{texments\}} to your document
116 % and can already use the \textsf{texments} commands described below.
117 %
118 % A typical compilation of a document that uses \textsf{texments}
119 % looks like this:
120 %
121 % \texttt{\$ pdflatex -shell-escape yourdocument.tex}
122 %
123 % Pygments supports many languages, to see which languages your
124 % version of Pygments supports, tell \texttt{pygmentize} to list
125 % all supported languages use the command:
126 %
127 % \texttt{\$ pygmentize -L lexer}
128 %
129 % it will return a rather long list with the names of the supported
130 % languages. Pygments is in constant development, so expact this list
131 % to grow over time.
132 %
133 % Note that if you use the \textsf{texments} commands to highlight
134 % text inside of \textsf{beamer} presentations, you need to mark
135 % the frames with the code ``fragile'', like this:
136 %
137 % \texttt{\textbackslash{}begin\{frame\}[fragile] ... \textbackslash{}end\{frame\}}
138 %
139 % So in case you get strange errors, try setting the containers
140 % ``fragile''.
141 %
142 % \DescribeMacro{\usestyle\marg{stylename}}
143 %
144 % This macro needs to be called at least once to set the style that
145 % pygments should use to highlight all code. Internally it calls
146 % \texttt{pygmentize} to get all the color-codes that the style uses.
147 % Every language can be highlighted using every style so the style
148 % choice is purely for aesthetical reasons.
149 %
150 % One quite useful style is the ``bw'' style which is, as the name
151 % somehow implies, black and white and therefore useful for printing
152 % documents that can only be black and white like books that should
153 % be published (black and white is usually cheaper) or printing on
154 % laser printers so that the printer does not have to guess which
155 % shade of grey to use.
156 %
157 % To change the style, \texttt{usestyle} can be called more than once,
158 % so that the following source codes get highlighted with a different
159 % style.
160 %
161 % For this document, we'll use the \texttt{default} style only.
162 %
163 % \usestyle{default}
164 %
165 % \DescribeMacro{\pygment\marg{language}\marg{code}}
166 %
167 % For simple one-line snippets the \texttt{pygment} command can be
168 % used. It will be rendered using the current selected style.
169 % Note that it will be put inside of a \texttt{Verbatim} environment.
170 %
171 % An example for this is the following Python code which displays
172 % the typical beginner program, with fancy coloring.
173 %
174 % \pygment{python}{print "Hello World"}
175 %
176 % This command won't be used very often, because most of the time
177 % it is more useful to use the provided environment to directly
178 % include bigger chunks of source code.
179 %
180 % \DescribeMacro{\includecode\oarg{language}\marg{filename}}
181 %
182 % Includes an external file that will be highlighted according to
183 % the syntax rules of the language. It has an optional argument,
184 % the language which can be set or not. If the argument is not set,
185 % Pygments tries to guess the language by looking at the file
186 % extension. The language specified can be, as always, any language
187 % that Pygments supports.
188 %
189 % Let's try this with a new file, called ``\jobname.py'' that we'll
190 % create. It will be a one-liner, and should print
191 % ``Hello TeXmented world''.
192 %
193 % \immediate\begin{VerbatimOut}{\jobname.py}
194 % print "Hello TeXmented world"
195 % \end{VerbatimOut}
196 %
197 % First we specify the language explicitly, using
198 % \texttt{\textbackslash{}includecode[python]{\jobname.py}}:
199 %
200 % \includecode[python]{\jobname.py}
201 %
202 % As you see this worked rather fine. Now, as the file has the proper
203 % ``.py'' extension, we can also leave out the language and write
204 % \texttt{\textbackslash{}includecode{\jobname.py}}:
205 %
206 % \includecode{\jobname.py}
207 %
208 % which again, renders the code correctly.
209 %
210 % \DescribeEnv{pygmented\marg{language}}
211 % For longer snippets of code it is usually better to use the
212 % \texttt{pygmented} environment. The parameter is the
213 % language that the snippet is in, so it can be highlighted
214 % properly. Everything inside the environment will be highlighted
215 % according to the syntax of the selected language.
216 %
217 % The first and only parameter describes the language that the
218 % snippet is in. It highlights the code to the specified rules.
219 %
220 % \begin{pygmented}{python}
221 % class FancyColoredStuff(object):
222 % def __init__(self, language):
223 % self.language = language
224 %
225 % def highlight(self):
226 % print "This is colorful code in %s" % self.language
227 %
228 % colorthing = FancyColoredStuff("Python")
229 % colorthing.highlight()
230 % \end{pygmented}
231 %
232 % Of course Python is not the only supported language, how about
233 % something more exotic? Let's try some Scheme code:
234 %
235 % \begin{pygmented}{scheme}
236 % (define frequencies
237 % (foldl (lambda (word hash)
238 % (let ((current-value (hash-ref hash word 0)))
239 % (hash-set hash word (add1 current-value))))
240 % (make-immutable-hash '())
241 % ; feed in the separated words
242 % (string-tokenize (port->string (current-input-port)))))
243 % \end{pygmented}
244 %
245 % \StopEventually{}
246 %
247 % \section{Implementation}
248 %
249 % \begin{macro}{\usestyle}
250 % This macro calls \texttt{pygmentize} with the appropriate style
251 % name and gets the color definitions that will be used in all
252 % subsequent code listings.
253 % \begin{macrocode}
254 \newcommand{\usestyle}[1]{
255 \immediate\write18{pygmentize -S #1 -f latex > \jobname.pyg}
256 \input{\jobname.pyg}
257 }
258 % \end{macrocode}
259 % \end{macro}
260 %
261 % \begin{macro}{\pygment}
262 % This macro takes the code in the second argument and feeds it
263 % to \texttt{pygmentize}, so that it outputs code highlighted
264 % to the rules of the first argument.
265 % \begin{macrocode}
266
267 \newwrite\code
268 \newcommand{\pygment}[2]{
269 \immediate\openout\code\jobname.pyg
270 \immediate\write\code{#2}
271 \immediate\closeout\code
272
273 \immediate\write18{pygmentize -l #1 -f latex -o \jobname.out.pyg \jobname.pyg}
274 \input{\jobname.out.pyg}
275 }
276 % \end{macrocode}
277 % \end{macro}
278 %
279 % \begin{macro}{\includecode}
280 % This macro has two parameters: language and file name. The language can be
281 % omitted in which case it will be set to \texttt{auto} and causes
282 % \texttt{pygmentize} to guess the language. The highlighted source is
283 % being written in an external file and imported automatically into the main
284 % document.
285 % \begin{macrocode}
286
287 \newcommand{\lexercommand}[1]{}
288
289 \newcommand{\includecode}[2][auto]{
290 \ifthenelse{\equal{#1}{auto}}
291 {\renewcommand{\lexercommand}[1]{}}
292 {\renewcommand{\lexercommand}[1]{-l #1}}
293 \immediate\write18{pygmentize \lexercommand{} -f latex -o #2.out.pyg #2}
294 \input{#2.out.pyg}
295 }
296
297 % \end{macrocode}
298 % \end{macro}
299 %
300 % \begin{environment}{pygmented}
301 % An environment that highlights the code that is contained inside using
302 % the currently selected style. It uses \texttt{VerbatimOut} from the
303 % \textsf{fancyvrb} package to write the contents into a file, calls
304 % \texttt{pygmentize} on it and imports the highlighted source.
305 % \begin{macrocode}
306
307 \newcommand{\proglang}[1]{}
308
309 \newenvironment{pygmented}[1]%
310 {\VerbatimEnvironment
311 \renewcommand{\proglang}[1]{#1}
312 \begin{VerbatimOut}{\jobname.pyg}}%
313 {\end{VerbatimOut}
314 \immediate\write18{pygmentize -l \proglang{} -f latex -o \jobname.out.pyg \jobname.pyg}
315 \input{\jobname.out.pyg}}
316
317 % \end{macrocode}
318 % \end{environment}
319 %
320 % \Finale
321 \endinput