From e0c6872cf40896c7be36b11dcc744620f10adf1d Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Mon, 2 Sep 2019 13:46:59 +0900 Subject: Initial commit --- macros/latex/contrib/texments/README | 69 +++++++ macros/latex/contrib/texments/texments.dtx | 321 +++++++++++++++++++++++++++++ macros/latex/contrib/texments/texments.ins | 69 +++++++ macros/latex/contrib/texments/texments.pdf | Bin 0 -> 101140 bytes 4 files changed, 459 insertions(+) create mode 100644 macros/latex/contrib/texments/README create mode 100644 macros/latex/contrib/texments/texments.dtx create mode 100644 macros/latex/contrib/texments/texments.ins create mode 100644 macros/latex/contrib/texments/texments.pdf (limited to 'macros/latex/contrib/texments') 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, | + +-------------------------------------------+ + + +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 () 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, + +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, +% +% 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} +% +%\NeedsTeXFormat{LaTeX2e} +%\ProvidesPackage{texments} +%<*package> + [2008/12/27 0.2.0 The Pygments source code highligher integrated into LaTeX documents] +%\RequirePackage{fancyvrb} +%\RequirePackage{color} +%\RequirePackage{ifthen} +% +% +%<*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} +% +% \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, +%% +%% 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, + +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 Binary files /dev/null and b/macros/latex/contrib/texments/texments.pdf differ -- cgit v1.2.3