From 6a84b544833458d78cf2c9b428d604415a238cb9 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Tue, 16 Aug 2022 20:58:54 +0000 Subject: pygmentex (16aug22) git-svn-id: svn://tug.org/texlive/trunk@64131 c570f23f-e606-0410-a88d-b1316a301751 --- .../doc/latex/pygmentex/pygmentex_demo.pdf | Bin 585220 -> 668777 bytes .../doc/latex/pygmentex/pygmentex_demo.tex | 120 +++++++++++++-------- .../doc/latex/pygmentex/pygmentex_demo_2.pdf | Bin 0 -> 37310 bytes .../doc/latex/pygmentex/pygmentex_demo_2.tex | 23 ++++ .../texmf-dist/tex/latex/pygmentex/pygmentex.sty | 22 +++- 5 files changed, 119 insertions(+), 46 deletions(-) create mode 100644 Master/texmf-dist/doc/latex/pygmentex/pygmentex_demo_2.pdf create mode 100644 Master/texmf-dist/doc/latex/pygmentex/pygmentex_demo_2.tex (limited to 'Master/texmf-dist') diff --git a/Master/texmf-dist/doc/latex/pygmentex/pygmentex_demo.pdf b/Master/texmf-dist/doc/latex/pygmentex/pygmentex_demo.pdf index a444bffd44d..73b3171514e 100644 Binary files a/Master/texmf-dist/doc/latex/pygmentex/pygmentex_demo.pdf and b/Master/texmf-dist/doc/latex/pygmentex/pygmentex_demo.pdf differ diff --git a/Master/texmf-dist/doc/latex/pygmentex/pygmentex_demo.tex b/Master/texmf-dist/doc/latex/pygmentex/pygmentex_demo.tex index 5a07f49bedf..1b6888022c4 100644 --- a/Master/texmf-dist/doc/latex/pygmentex/pygmentex_demo.tex +++ b/Master/texmf-dist/doc/latex/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 \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 + #include 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 + #include 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 #import - + 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} diff --git a/Master/texmf-dist/doc/latex/pygmentex/pygmentex_demo_2.pdf b/Master/texmf-dist/doc/latex/pygmentex/pygmentex_demo_2.pdf new file mode 100644 index 00000000000..b824f9695fb Binary files /dev/null and b/Master/texmf-dist/doc/latex/pygmentex/pygmentex_demo_2.pdf differ diff --git a/Master/texmf-dist/doc/latex/pygmentex/pygmentex_demo_2.tex b/Master/texmf-dist/doc/latex/pygmentex/pygmentex_demo_2.tex new file mode 100644 index 00000000000..fc684fa615e --- /dev/null +++ b/Master/texmf-dist/doc/latex/pygmentex/pygmentex_demo_2.tex @@ -0,0 +1,23 @@ +\documentclass{article} +\usepackage[T1]{fontenc} +\usepackage[scaled=0.85]{beramono} +\usepackage[force]{pygmentex} + +\begin{document} + +This is my C program: + +\begin{pygmented}[lang=c] +#include +int main(void) +{ + int a, b, c; + printf("Enter two numbers to add: "); + scanf("%d%d", &a, &b); + c = a + b; + printf("Sum of entered numbers = %d\n", c); + return 0; +} +\end{pygmented} + +\end{document} diff --git a/Master/texmf-dist/tex/latex/pygmentex/pygmentex.sty b/Master/texmf-dist/tex/latex/pygmentex/pygmentex.sty index 60e7bcda30b..4e072114905 100644 --- a/Master/texmf-dist/tex/latex/pygmentex/pygmentex.sty +++ b/Master/texmf-dist/tex/latex/pygmentex/pygmentex.sty @@ -2,13 +2,19 @@ \NeedsTeXFormat{LaTeX2e} -\ProvidesPackage{pygmentex}[2020/12/21 v0.10 A Pygmentex layer for LaTeX] +\ProvidesPackage{pygmentex}[2022/08/15 v0.11 A Pygmentex layer for LaTeX] + +\newif\ifpygmented@opt@force\pygmented@opt@forcefalse +\DeclareOption{force}{\pygmented@opt@forcetrue} + +\ProcessOptions\relax \RequirePackage{fancyvrb} \RequirePackage{color} \RequirePackage{ifthen} %\RequirePackage[font=small,format=plain,labelfont=bf,up,textfont=it,up]{caption} \RequirePackage{caption} +\RequirePackage{shellesc} \RequirePackage{pgfkeys} \RequirePackage{efbox} \RequirePackage[framemethod=tikz]{mdframed} @@ -117,6 +123,7 @@ colback/.store in = \pygmented@opt@colback, font/.store in = \pygmented@opt@font, % + force/.default = false, texcomments/.default = true, mathescape/.default = true, linenos/.default = true, @@ -383,7 +390,18 @@ } \AtEndDocument{% - \closeout\pygmented@outfile% + \immediate\closeout\pygmented@outfile% + \ifpygmented@opt@force + \typeout{>>>> running pygmentex (option force=true) ...}% + \ShellEscape{pygmentex \jobname.snippets}% + \typeout{>>>> ... done.}% + \else + \IfFileExists{\jobname.pygmented}% + {\typeout{>>>> file \jobname.pygmented exists, not running pygmentex}}% + {\typeout{>>>> no file \jobname.pygmented, running pygmentex ...}% + \ShellEscape{pygmentex \jobname.snippets}% + \typeout{>>>> ... done.}}% + \fi } \endinput -- cgit v1.2.3