summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/texments
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/texments
Initial commit
Diffstat (limited to 'macros/latex/contrib/texments')
-rw-r--r--macros/latex/contrib/texments/README69
-rw-r--r--macros/latex/contrib/texments/texments.dtx321
-rw-r--r--macros/latex/contrib/texments/texments.ins69
-rw-r--r--macros/latex/contrib/texments/texments.pdfbin0 -> 101140 bytes
4 files changed, 459 insertions, 0 deletions
diff --git a/macros/latex/contrib/texments/README b/macros/latex/contrib/texments/README
new file mode 100644
index 0000000000..6be7023012
--- /dev/null
+++ b/macros/latex/contrib/texments/README
@@ -0,0 +1,69 @@
+ +-------------------------------------------+
+ | TEXMENTS |
+ | |
+ | Access the Pygments syntax highlighter |
+ | from inside LaTeX. |
+ | |
+ | By Marek Kubica, <marek@xivilization.net> |
+ +-------------------------------------------+
+
+
+Description
+-----------
+
+Ever wanted to include a source file into your LaTeX code? Code gets
+easier to read when it is colored so many people use the ``listings''
+package that can syntax-color (highlight) your source files. Not
+every language is supported, though. This is where ``texments''
+comes in handy. ``texments'' is an alternative to ``listings'' and
+uses the Pygments syntax highlighter which provides highlighting
+for more languages than ``listings'' itself. Especially when a
+language is rather recent, Pygments often supports it already like
+for example Scala and Clojure.
+``texments'' also supports multiple color schemes, so almost everyone
+can find a setting that pleases him.
+
+
+Installation
+------------
+
+As ``texments'' is only glue between several packages, it has some
+dependencies. The dependencies on the LaTeX-side are ``fancyvrb'',
+``color'' and ``ifthen'' which should be all included in basically
+any notable TeX distribution, so no problems are to be expected.
+The documentation also uses the ``hyperref'' package which is also
+part of any self-respecting TeX distribution.
+The other dependency is the ``pygmentize'' command, which is part
+of the Pygments (<http://pygments.org/>) library. Pygments is
+provided by many Linux distributions in the package
+``python-pygments'' (Debian, Ubuntu, Fedora, openSUSE),
+``pygments'' (Gentoo, Arch Linux AUR) or similar. Users of other
+systems can install it using ``easy_install Pygments'' (provided
+that setuptools are installed) or simply by downloading the Pygments
+tarball and running ``python setup.py install'' inside of it.
+
+To create the ``texments.sty'' file, call ``latex texments.ins''.
+Then you need to move the file into a place where TeX can find it,
+probably into your TEXMF tree. To generate the documentation,
+call ``pdflatex -shell-escape texments.dtx'' which will generate
+the ``texments.pdf'' file which includes some examples and hints
+how to use it. Note that the ``-shell-escape'' parameter is
+(unfortunately) mandatory, as the macro package needs to call
+``pygmentize'' to highlight the content.
+
+
+Copyright and license
+---------------------
+
+Copyright (C) 2008 Marek Kubica, <marek@xivilization.net>
+
+This package 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.
+
diff --git a/macros/latex/contrib/texments/texments.dtx b/macros/latex/contrib/texments/texments.dtx
new file mode 100644
index 0000000000..1e89e35cf7
--- /dev/null
+++ b/macros/latex/contrib/texments/texments.dtx
@@ -0,0 +1,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
diff --git a/macros/latex/contrib/texments/texments.ins b/macros/latex/contrib/texments/texments.ins
new file mode 100644
index 0000000000..23da3022c6
--- /dev/null
+++ b/macros/latex/contrib/texments/texments.ins
@@ -0,0 +1,69 @@
+%%
+%% 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.
+%%
+
+\input docstrip.tex
+\keepsilent
+
+\usedir{tex/latex/texments}
+
+\preamble
+
+This is a generated file.
+
+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.
+
+\endpreamble
+
+\generate{\file{texments.sty}{\from{texments.dtx}{package}}}
+
+\obeyspaces
+\Msg{*************************************************************}
+\Msg{* *}
+\Msg{* To finish the installation you have to move the following *}
+\Msg{* file into a directory searched by TeX: *}
+\Msg{* *}
+\Msg{* texments.sty *}
+\Msg{* *}
+\Msg{* This package depends on pygmentize, be sure to install *}
+\Msg{* this tool via your packet management system, look for *}
+\Msg{* python-pygments or use easy_install Pygments *}
+\Msg{* *}
+\Msg{* To produce the documentation run the file texments.dtx *}
+\Msg{* through LaTeX with -shell-escape active. *}
+\Msg{* *}
+\Msg{* Happy TeXing! *}
+\Msg{* *}
+\Msg{*************************************************************}
+
+\endbatchfile
diff --git a/macros/latex/contrib/texments/texments.pdf b/macros/latex/contrib/texments/texments.pdf
new file mode 100644
index 0000000000..7afdf37a68
--- /dev/null
+++ b/macros/latex/contrib/texments/texments.pdf
Binary files differ