path: root/macros/latex/contrib/texments/texments.dtx

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