summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/texments/texments.dtx
blob: 1e89e35cf77f63879cb14510484caa6bbe9b59d0 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
% \iffalse meta-comment
%
% Copyright 2008 Marek Kubica, <marek@xiviliation.net>
%
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3c
% of this license or (at your option) any later version.
% The latest version of this license is in
%   http://www.latex-project.org/lppl.txt
% and version 1.3c or later is part of all distributions of LaTeX
% version 2008/05/04 or later.
%
% This work has the LPPL maintenance status `maintained'.
% 
% The Current Maintainer of this work is Marek Kubica.
%
% This work consists of the files textments.dtx and texments.ins
% and the derived file texments.sty.
%
% \fi
%
% \iffalse
%<*driver>
\ProvidesFile{texments.dtx}
%</driver>
%<package>\NeedsTeXFormat{LaTeX2e}
%<package>\ProvidesPackage{texments}
%<*package>
    [2008/12/27 0.2.0 The Pygments source code highligher integrated into LaTeX documents]
%<package>\RequirePackage{fancyvrb}
%<package>\RequirePackage{color}
%<package>\RequirePackage{ifthen}
%</package>
%
%<*driver>
\documentclass{ltxdoc}
\usepackage{texments}[2008/12/27]
\usepackage{hyperref}
\EnableCrossrefs
\CodelineIndex
\RecordChanges
\hypersetup{
  pdftitle={texments manual},
  pdfsubject={Documentation of the texments LaTeX package},
  pdfauthor={Marek Kubica},
  pdfkeywords={pygments texments sourcecode highlight color},
}

\begin{document}
  \DocInput{texments.dtx}
  \PrintChanges
  \PrintIndex
\end{document}
%</driver>
% \fi
%
% \CheckSum{57}
%
% \CharacterTable
%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%   Digits        \0\1\2\3\4\5\6\7\8\9
%   Exclamation   \!     Double quote  \"     Hash (number) \#
%   Dollar        \$     Percent       \%     Ampersand     \&
%   Acute accent  \'     Left paren    \(     Right paren   \)
%   Asterisk      \*     Plus          \+     Comma         \,
%   Minus         \-     Point         \.     Solidus       \/
%   Colon         \:     Semicolon     \;     Less than     \<
%   Equals        \=     Greater than  \>     Question mark \?
%   Commercial at \@     Left bracket  \[     Backslash     \\
%   Right bracket \]     Circumflex    \^     Underscore    \_
%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%   Right brace   \}     Tilde         \~}
%
%
% \changes{v0.0.1}{2008/10/10}{Initial version}
% \changes{v0.1.0}{2008/10/10}{Properly repackaged}
% \changes{v0.2.0}{2008/12/23}{More documentation, commands, environments}
%
% \GetFileInfo{texments.dtx}
%
% \DoNotIndex{\newcommand,\newenvironment}
% 
%
% \title{The \textsf{texments} package\thanks{This document
%   corresponds to \textsf{texments}~\fileversion, dated \filedate.}}
% \author{Marek Kubica \\ \texttt{marek@xivilization.net}}
%
% \maketitle
%
% ^^A define gobble to yank the first char out, which is a '%'
% ^^A because of DocStrip
% \fvset{gobble=1}
%
% \section{Introduction}
%
% \textsf{texments} is a package that is used to connect the not-yet 
% award winning source code colorizer library Pygments 
% (\url{http://pygments.org/}) with \LaTeX{} documents. That means that 
% it is neccessary to have Pygments installed and that the 
% \texttt{pygmentize} command is available.
%
% \section{Usage}
%
% This package does not provide many fancy features, it is just meant
% as an easy bridge between the highlighter and LaTeX. It calls
% internally the \texttt{pygmentize} command, so you need to start it
% with \texttt{-shell-escape} activated. \texttt{-shell-escape} 
% allows the \LaTeX{} processor to call arbitary shell commands which
% can be a security problem if compiling untrusted source, but
% unfortunately this is unavoidable because \texttt{pygmentize} is
% an external command.
%
% Using \textsf{texments} is simple: you only need to add 
% \texttt{\textbackslash{}usepackage\{texments\}} to your document
% and can already use the \textsf{texments} commands described below.
%
% A typical compilation of a document that uses \textsf{texments} 
% looks like this:
%
% \texttt{\$ pdflatex -shell-escape yourdocument.tex}
%
% Pygments supports many languages, to see which languages your
% version of Pygments supports, tell \texttt{pygmentize} to list
% all supported languages use the command:
%
% \texttt{\$ pygmentize -L lexer}
%
% it will return a rather long list with the names of the supported
% languages. Pygments is in constant development, so expact this list
% to grow over time.
%
% Note that if you use the \textsf{texments} commands to highlight
% text inside of \textsf{beamer} presentations, you need to mark
% the frames with the code ``fragile'', like this:
%
% \texttt{\textbackslash{}begin\{frame\}[fragile] ... \textbackslash{}end\{frame\}}
%
% So in case you get strange errors, try setting the containers
% ``fragile''.
%
% \DescribeMacro{\usestyle\marg{stylename}}
%
% This macro needs to be called at least once to set the style that
% pygments should use to highlight all code. Internally it calls
% \texttt{pygmentize} to get all the color-codes that the style uses.
% Every language can be highlighted using every style so the style
% choice is purely for aesthetical reasons.
%
% One quite useful style is the ``bw'' style which is, as the name
% somehow implies, black and white and therefore useful for printing
% documents that can only be black and white like books that should
% be published (black and white is usually cheaper) or printing on
% laser printers so that the printer does not have to guess which
% shade of grey to use.
%
% To change the style, \texttt{usestyle} can be called more than once,
% so that the following source codes get highlighted with a different
% style.
%
% For this document, we'll use the \texttt{default} style only.
%
% \usestyle{default}
%
% \DescribeMacro{\pygment\marg{language}\marg{code}}
%
% For simple one-line snippets the \texttt{pygment} command can be
% used. It will be rendered using the current selected style.
% Note that it will be put inside of a \texttt{Verbatim} environment.
%
% An example for this is the following Python code which displays
% the typical beginner program, with fancy coloring.
%
% \pygment{python}{print "Hello World"}
%
% This command won't be used very often, because most of the time
% it is more useful to use the provided environment to directly
% include bigger chunks of source code.
%
% \DescribeMacro{\includecode\oarg{language}\marg{filename}}
%
% Includes an external file that will be highlighted according to
% the syntax rules of the language. It has an optional argument,
% the language which can be set or not. If the argument is not set,
% Pygments tries to guess the language by looking at the file
% extension. The language specified can be, as always, any language
% that Pygments supports.
%
% Let's try this with a new file, called ``\jobname.py'' that we'll
% create. It will be a one-liner, and should print 
% ``Hello TeXmented world''.
%
% \immediate\begin{VerbatimOut}{\jobname.py}
% print "Hello TeXmented world"
% \end{VerbatimOut}
%
% First we specify the language explicitly, using 
% \texttt{\textbackslash{}includecode[python]{\jobname.py}}:
%
% \includecode[python]{\jobname.py}
%
% As you see this worked rather fine. Now, as the file has the proper
% ``.py'' extension, we can also leave out the language and write
% \texttt{\textbackslash{}includecode{\jobname.py}}:
%
% \includecode{\jobname.py}
%
% which again, renders the code correctly.
%
% \DescribeEnv{pygmented\marg{language}}
% For longer snippets of code it is usually better to use the
% \texttt{pygmented} environment. The parameter is the
% language that the snippet is in, so it can be highlighted
% properly. Everything inside the environment will be highlighted
% according to the syntax of the selected language.
%
% The first and only parameter describes the language that the
% snippet is in. It highlights the code to the specified rules.
%
% \begin{pygmented}{python}
% class FancyColoredStuff(object):
%     def __init__(self, language):
%         self.language = language
%
%     def highlight(self):
%         print "This is colorful code in %s" % self.language
%
% colorthing = FancyColoredStuff("Python")
% colorthing.highlight()
% \end{pygmented}
%
% Of course Python is not the only supported language, how about
% something more exotic? Let's try some Scheme code:
%
% \begin{pygmented}{scheme}
% (define frequencies
%   (foldl (lambda (word hash)
%          (let ((current-value (hash-ref hash word 0)))
%            (hash-set hash word (add1 current-value))))
%        (make-immutable-hash '())
%        ; feed in the separated words
%        (string-tokenize (port->string (current-input-port)))))
% \end{pygmented}
%
% \StopEventually{}
%
% \section{Implementation}
%
% \begin{macro}{\usestyle}
% This macro calls \texttt{pygmentize} with the appropriate style
% name and gets the color definitions that will be used in all
% subsequent code listings.
%    \begin{macrocode}
\newcommand{\usestyle}[1]{
  \immediate\write18{pygmentize -S #1 -f latex > \jobname.pyg}
  \input{\jobname.pyg}
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\pygment}
% This macro takes the code in the second argument and feeds it
% to \texttt{pygmentize}, so that it outputs code highlighted
% to the rules of the first argument.
%    \begin{macrocode}

\newwrite\code
\newcommand{\pygment}[2]{
  \immediate\openout\code\jobname.pyg
  \immediate\write\code{#2}
  \immediate\closeout\code

  \immediate\write18{pygmentize -l #1 -f latex -o \jobname.out.pyg \jobname.pyg}
  \input{\jobname.out.pyg}
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\includecode}
% This macro has two parameters: language and file name. The language can be
% omitted in which case it will be set to \texttt{auto} and causes 
% \texttt{pygmentize} to guess the language. The highlighted source is
% being written in an external file and imported automatically into the main
% document.
%    \begin{macrocode}

\newcommand{\lexercommand}[1]{}

\newcommand{\includecode}[2][auto]{
  \ifthenelse{\equal{#1}{auto}}
    {\renewcommand{\lexercommand}[1]{}}
    {\renewcommand{\lexercommand}[1]{-l #1}}
  \immediate\write18{pygmentize \lexercommand{} -f latex -o #2.out.pyg #2}
  \input{#2.out.pyg}
}

%    \end{macrocode}
% \end{macro}
%
% \begin{environment}{pygmented}
% An environment that highlights the code that is contained inside using
% the currently selected style. It uses \texttt{VerbatimOut} from the
% \textsf{fancyvrb} package to write the contents into a file, calls
% \texttt{pygmentize} on it and imports the highlighted source.
%    \begin{macrocode}

\newcommand{\proglang}[1]{}

\newenvironment{pygmented}[1]%
  {\VerbatimEnvironment
   \renewcommand{\proglang}[1]{#1}
   \begin{VerbatimOut}{\jobname.pyg}}%
  {\end{VerbatimOut}
   \immediate\write18{pygmentize -l \proglang{} -f latex -o \jobname.out.pyg \jobname.pyg}
   \input{\jobname.out.pyg}}

%    \end{macrocode}
% \end{environment}
%
% \Finale
\endinput