summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/pygmentex/pygmentex_demo.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/pygmentex/pygmentex_demo.tex')
-rw-r--r--macros/latex/contrib/pygmentex/pygmentex_demo.tex120
1 files changed, 76 insertions, 44 deletions
diff --git a/macros/latex/contrib/pygmentex/pygmentex_demo.tex b/macros/latex/contrib/pygmentex/pygmentex_demo.tex
index 5a07f49bed..1b6888022c 100644
--- a/macros/latex/contrib/pygmentex/pygmentex_demo.tex
+++ b/macros/latex/contrib/pygmentex/pygmentex_demo.tex
@@ -1,5 +1,4 @@
\documentclass[10pt,a4paper]{article}
-
%\usepackage[margin=13mm]{geometry}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
@@ -24,7 +23,10 @@
\begin{document}
\title{Testing the Pygmen\TeX{} package}
-\author{José Romildo Malaquias}
+\author{José Romildo Malaquias\\
+\href{mailto:malaquias@ufop.edu.br}{malaquias@ufop.edu.br}\\
+\href{https://bitbucket.org/romildo/pygmentex/src/master/}{bitbucket.org/romildo/pygmentex}
+}
\maketitle
\section{The Pygmen\TeX{} package}
@@ -42,7 +44,7 @@ listings in a \LaTeX{} document:
\begin{itemize}
\item the \verb|pygmented| environment typesets its contents as a
source code listing,
- \item the \verb|includepygmented| command typesets the contents of a
+ \item the \verb|\inputpygmented| command typesets the contents of a
file, including the result in the \LaTeX{} document, and
\item the \verb|\pyginline| command typesets its contents, keeping the
result in the same line.
@@ -53,35 +55,49 @@ many ways.
Read the remaining of this document to have an idea of what the package
is capable of.
+\section{Requirements}
+
+Current versions of Pygmen\TeX require Python version 3. Earlier versions
+required Python version 2. All versions require the Python Pygments library.
+
\section{How to use the package}
-In order to use the package, start by putting
+\paragraph{1.} Add the package to the document preamble.
\begin{verbatim}
\usepackage{pygmentex}
\end{verbatim}
-in the preamble of the document.
-Use the environment or commands mentioned previously to include source
+\paragraph{2.} Use the environment or commands mentioned previously to include source
code listings on your document.
-When compiling the document (with \texttt{pdflatex}, for instance), all
-the source code listings in the document wil be collected and saved in a
-temporary file with the extension \texttt{.snippets} in its name. Then
-the auxiliary program \texttt{pygmentex} (a Python application
-distributed with the Pygmen\TeX{} package) should be run taking this
-file as input. It will produce another temporary file with the extension
+\paragraph{3.} Compile using \texttt{pdflatex}.\footnote{Other \LaTeX compilers
+may also work but have not been tested by the author.}
+All the source code listings in the document wil be collected and saved in a
+temporary file with the extension \texttt{.snippets} in its name.
+
+\paragraph{4.} Run \texttt{pygmentex documentname.snippets}.
+The python application \texttt{pygmentex} is
+distributed with the Pygmen\TeX{} package).
+It will produce another temporary file with the extension
\texttt{.pygmented}, containing \LaTeX{} code for the code listings
previously collected. The next time the document is compiled, they are
included to produce the final typeset document.
-The programming language of the listing code can be specified using the
-\verb|lang| option.
+\paragraph{5.} Rerun \texttt{pdflatex} as usual.
-To get a list of all available languages, execute the following command
-on the command line:
+\paragraph{Note.} Running the external python application
+\texttt{pygmentex} can be done automatically from withing \LaTeX{} if
+the optional argument \texttt{--shell-escape} is used.
+
+With
\begin{verbatim}
-$ pygmentize -L lexers
+pdflatex --shell-escape <file>
\end{verbatim}
+the external run of \texttt{pygmentex} is not needed. It will be run
+automatically at the end of the document compilation.
+
+There is a package option \texttt{force} that will force running
+\texttt{pygmentex} every time the document is compiled.
\section{First examples}
@@ -122,7 +138,18 @@ Next you can see a Java program to calculate the factorial of a number.
\inputpygmented[lang=java]{Factorial.java}
\end{Example}
-\section{Choosing different Pygments styles}
+\section{Options}
+\subsection{\texttt{lang}}
+The programming language of the listing code can be specified using the
+\verb|lang| option.
+
+To get a list of all available languages, execute the following command
+on the command line:
+\begin{verbatim}
+$ pygmentize -L lexers
+\end{verbatim}
+
+\subsection{\texttt{sty}}
Instead of using the default style you may choose another stylesheet
provided by Pygments by its name using the \verb|sty| option.
@@ -142,7 +169,7 @@ As examples you can see a C program typeset with different styles.
\noindent
\begin{minipage}[t]{0.49\linewidth}
\begin{pygmented}[lang=c,gobble=4,sty=murphy]
- #include<stdio.h>
+ #include<stdio.h>
main()
{ int n;
printf("Enter a number: ");
@@ -158,7 +185,7 @@ As examples you can see a C program typeset with different styles.
\hfil
\begin{minipage}[t]{0.49\linewidth}
\begin{pygmented}[lang=c,gobble=4,sty=trac]
- #include<stdio.h>
+ #include<stdio.h>
main()
{ int n;
printf("Enter a number: ");
@@ -173,7 +200,7 @@ As examples you can see a C program typeset with different styles.
\end{minipage}
\end{Example}
-\section{Choosing a font}
+\subsection{\texttt{font}}
The value of the option \verb|font| is typeset before the content of the
listing. Usualy it is used to specify a font to be used. See the
@@ -193,23 +220,23 @@ object bigint extends Application {
\end{pygmented}
\end{Example}
-\section{Changing the background color}
+\subsection{\texttt{colback}}
The option \verb|colback| can be used to choose a background color, as
is shown in the folowing example.
\begin{Example}
\begin{pygmented}[lang=fsharp,colback=green!25]
-let rec factorial n =
- if n = 0
- then 1
+let rec factorial n =
+ if n = 0
+ then 1
else n * factorial (n - 1)
System.Console.WriteLine(factorial anInt)
\end{pygmented}
\end{Example}
-\section{Supressing initial characters}
+\subsection{\texttt{gobble}}
The option \verb|gobble| specifies the number of characters to suppress
at the beginning of each line (up to a maximum of 9). This is mainly
@@ -232,7 +259,7 @@ A code snippet inside a minipage:
\end{Example}
-\section{Size of tabulator}
+\subsection{\texttt{tabsize}}
The option \verb|tabsize| specifies the number of of spaces given by a
tab character (Default: 8).
@@ -254,7 +281,7 @@ tab character (Default: 8).
\end{pygmented}
-\section{Numbering lines}
+\subsection{\texttt{linenos}, \texttt{linenostart}, \texttt{linenostep}, \texttt{linenosep}}
The lines of a listing can be numbered. The followig options control
numbering of lines.
@@ -277,7 +304,7 @@ factorial of a number.
;; Building a list of squares from 0 to 9.
;; Note: loop is simply an arbitrary symbol used as
;; a label. Any symbol will do.
-
+
(define (list-of-squares n)
(let loop ((i n) (res '()))
(if (< i 0)
@@ -286,7 +313,7 @@ factorial of a number.
\end{pygmented}
\end{Example}
-\section{Captioning}
+\subsection{\texttt{caption} and \texttt{label}}
The option \verb|caption| can be used to set a caption for the listing.
The option \verb|label| allows the assignment of a label to the listing.
@@ -314,7 +341,7 @@ int main()
Listing \ref{lst:test} is a C++ program.
\end{Example}
-\section{Escaping to \LaTeX{} inside a code snippet}
+\subsection{\texttt{texcomments}, \texttt{mathescape} and \texttt{escapeinside}}
The option \verb|texcomments|, if set to \texttt{true}, enables \LaTeX{}
comment lines. That is, LaTex markup in comment tokens is not escaped
@@ -364,13 +391,13 @@ else
\end{Example}
-\section{Enclosing command and environment}
+\subsection{\texttt{inline method} and \texttt{boxing method}}
After being prettified by Pygments, the listings are enclosed in a
command (for \verb|\pyginline|) or in an environment (for
-\verb|pygmented| and \verb|includepygmented|). By default
+\verb|pygmented| and \verb|inputpygmented|). By default
\verb|\pyginline| uses the command \verb|\efbox| from the \texttt{efbox}
-package, and \verb|pygmented| and \verb|includepygmented| use the
+package, and \verb|pygmented| and \verb|inputpygmented| use the
environment \verb|mdframed| from the \texttt{mdframed} package.
The enclosing command or environment should be configurable using a list
@@ -388,7 +415,7 @@ The enclosing command for
\end{Example}
The enclosing environment for \verb|pygmented| and
-\verb|includepygmented| can be changed with the option
+\verb|inputpygmented| can be changed with the option
\verb|boxing method|. For instance, here is a hello world program in
C\#, enclosed in a \verb|tcolorbox| environment:
@@ -461,7 +488,7 @@ END
\begin{pygmented}[test, lang=vbnet]
Module Module1
- Sub Main()
+ Sub Main()
Console.WriteLine("Hello, world!")
End Sub
End Module
@@ -595,7 +622,7 @@ def qsort(xs: List[Int]): List[Int] =
}
\end{pygmented}
\lipsum[32]
-
+
\item[Another item] \lipsum[33]
\begin{pygmented}[lang=lua,colback=yellow]
function entry0 (o)
@@ -704,9 +731,9 @@ int main(int argc, char** argv) {
/* This program prints a
hello world message
to the console. */
-
+
import std.stdio;
-
+
void main()
{
writeln("Hello, World!");
@@ -725,7 +752,7 @@ The followig example uses \texttt{mdframed} to typeset the code listing.
\begin{pygmented}[boxing method=mdframed,lang=ada,style=exampledefault]
with Ada.Text_IO;
-
+
procedure Hello_World is
use Ada.Text_IO;
begin
@@ -739,7 +766,7 @@ end;
\begin{pygmented}[boxing method=mdframed,lang=pascal,style=exampledefault,frametitle={Saying \emph{hello} from Pascal}]
program HelloWorld;
-
+
begin
WriteLn('Hello, world!');
end.
@@ -814,9 +841,9 @@ END Hello.
\begin{pygmented}[boxing method=mdframed,lang=go,style=exercisestyle]
// hello world in 'go'
package main
-
+
import "fmt"
-
+
func main() {
fmt.Println("Hello, world!")
}
@@ -827,7 +854,7 @@ func main() {
#import <stdio.h>
#import <Foundation/Foundation.h>
-
+
int main(void)
{
NSLog(@"Hello, world!\n");
@@ -853,6 +880,11 @@ int main(int argc, char **argv) {
}
\end{pygmented}
+\section{Debugging}
+Paths given to \verb|\inputpygmented| should be relative to the top level project
+directory, not to the file that contains the command (if that file is in a
+subdirectory). Pygmen\TeX generates only a single top-level \texttt{.snippets} file,
+and paths are not munged to account for code in subdirectories.
\section{Conclusion}