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