verbments (22aug11)

git-svn-id: svn://tug.org/texlive/trunk@23670 c570f23f-e606-0410-a88d-b1316a301751

4 files changed, 178 insertions, 59 deletions

diff --git a/Master/texmf-dist/doc/latex/verbments/README b/Master/texmf-dist/doc/latex/verbments/README
index 46723a18afe..d96c1705504 100644
--- a/Master/texmf-dist/doc/latex/verbments/README
+++ b/Master/texmf-dist/doc/latex/verbments/README
@@ -1,4 +1,4 @@
-verbments (v1.1) -- syntax highlighting of source code in LaTeX documents
+verbments (v1.2) -- syntax highlighting of source code in LaTeX documents
 
 The verbments package provides an environment for syntax highlighting
 of source code in LaTeX documents. The highlighted source code output is
diff --git a/Master/texmf-dist/doc/latex/verbments/verbments.pdf b/Master/texmf-dist/doc/latex/verbments/verbments.pdf
index 5465b5ef5eb..a3d2cfd1f98 100644
--- a/Master/texmf-dist/doc/latex/verbments/verbments.pdf
+++ b/Master/texmf-dist/doc/latex/verbments/verbments.pdf
diff --git a/Master/texmf-dist/doc/latex/verbments/verbments.tex b/Master/texmf-dist/doc/latex/verbments/verbments.tex
index 069220b6e38..b2f6958dd23 100644
--- a/Master/texmf-dist/doc/latex/verbments/verbments.tex
+++ b/Master/texmf-dist/doc/latex/verbments/verbments.tex
@@ -1,6 +1,7 @@
 % This file requires Pygments and Python installed on the computer,
-% as well as the --shell-escape LaTeX compiler option
+% as well as the -shell-escape LaTeX compiler option
 %
+\PassOptionsToPackage{svgnames}{xcolor}
 \documentclass{article}
 
 \usepackage{doc}
@@ -48,7 +49,7 @@
 \title{The \vmPackage{} package:\\Pretty printing source code in \LaTeX\thanks{This work has been supported by the Serbian Ministry of Education and Science (project III44006).}}
 \author{Dejan \v{Z}ivkovi\'{c}\\{\small Singidunum University, Serbia}\\[-1mm]{\footnotesize\href{mailto:dzivkovic@singidunum.ac.rs}
                {\nolinkurl{dzivkovic@singidunum.ac.rs}}}}
-\date{Version 1.1\\ July 7, 2011}
+\date{Version 1.2\\ August 20, 2011}
 
 \maketitle
 
@@ -71,14 +72,14 @@ Pygments is written in Python and provides far superior syntax highlighting comp
 
 \section{Installation}
 
-Installation of the \vmPackage{} package itself is simple\Dash the \vmPackage{}.\texttt{sty} file only needs to be on the path where \LaTeX{} can find it. However, \vmPackage{} additionally requires that the Python language and its Pygments library are installed on the computer. 
+Installation of the \vmPackage{} package itself is simple\Dash the \vmPackage{}.\texttt{sty} file only needs to be on the path where \LaTeX{} can find it. However, \vmPackage{} package additionally requires that the Python language and its Pygments library are installed on the computer. 
 
 Python and Pygments are free software and can be downloaded from their web sites. Bear in mind that Windows support is sketchy at the moment, but instructions to properly configure the software may be found elsewhere on the Internet. (For example, good starting point is the documentation of the \texttt{minted} package.)
 
-\section{Usage}
+\section{Basic usage}
 
-\DescribeEnv{{-}{-}shell-escape}
-First of all, don't forget to call the \LaTeX{} complier (\texttt{latex}, \texttt{pdflatex}, or \texttt{xelatex}) by passing it the \texttt{{-}{-}shell-escape} option. 
+\DescribeEnv{{-}shell-escape}
+First of all, don't forget to call the \LaTeX{} complier (\texttt{latex}, \texttt{pdflatex}, or \texttt{xelatex}) by passing it the \texttt{{-}shell-escape} option. 
 
 \DescribeEnv{pyglist}
 Using \vmPackage{} in a \LaTeX{} document is straightforward\Dash you simply enclose a source code in the \texttt{pyglist} environment:
@@ -87,7 +88,7 @@ Using \vmPackage{} in a \LaTeX{} document is straightforward\Dash you simply enc
 \def\rb{\}}
 \begin{Verbatim}[commandchars=+\{\},gobble=1,fontsize=\MacroFont]
 \begin+lb{pyglist}+rb[+meta{options}]
-  +meta{source code} 
+   +meta{source code} 
 \end+lb{pyglist}+rb
 \end{Verbatim}
 
@@ -108,7 +109,7 @@ public class Hello {
 \end{pyglist}
 \end{verbatim}
 
-This environment uses the default Pygments style and it is typeset as follows: 
+This environment uses the default Pygments style and the Java example code is typeset as follows: 
 
 \bigskip
 \begin{pyglist}[language=java,fontsize=\MacroFont]
@@ -124,18 +125,18 @@ public class Hello {
 }
 \end{pyglist}
 
-If the \texttt{texcl=true}, \texttt{style=vs} and \texttt{bgcolor=Moccasin} options are added to the option list of the previous \texttt{pyglist} environment for the similar Java code, i.e.,
+If the \texttt{texcl=true}, \texttt{style=vs} and \texttt{bgcolor=Moccasin} options are added to the option list of the previous \texttt{pyglist} environment for a similar Java code, i.e.,
 
 \begin{verbatim}
 \begin{pyglist}[language=java,texcl=true,style=vs,bgcolor=Moccasin]
 //  \fbox{Hello} Java program
-
-   . . .
-
+      .
+      .
+      .
 \end{pyglist}
 \end{verbatim}
 
-then the code is typeset with the Visual Studio style and Moccasin background color:
+then the source code is typeset with the Visual Studio style and Moccasin background color:
 
 \bigskip
 \begin{pyglist}[language=java,texcl=true,style=vs,bgcolor=Moccasin,fontsize=\MacroFont]
@@ -159,20 +160,88 @@ Since the option list of the \texttt{pyglist} environment may become lengthy, op
 \plset{language=java,texcl=true,style=vs,bgcolor=Moccasin}
 \end{verbatim}
 
-With these options set in this way then, to get the previous highlighted code it is enough to specify:
+With the options globally set in this way, now to get the previous highlighted example code it is enough to specify:
 
 \begin{verbatim}
 \begin{pyglist}
 // \fbox{Hello} Java program
+      .
+      .
+      .
+\end{pyglist}
+\end{verbatim}
+
+\section{Captions}
+
+Source code listings can containg captions. For example, 
+
+\begin{verbatim}
+\begin{pyglist}[language=java,caption={First Java program}]
+// Hello Java program
+      .
+      .
+      .
+\end{pyglist}
+\end{verbatim}
+
+produces the following result:
+
+\begin{pyglist}[language=java,caption={First Java program},fontsize=\MacroFont]
+// Hello Java program
+      .
+      .
+      .
+\end{pyglist}
+
+Caption label used as a prefix to the caption text of a listing is |Listing| by default. This can be changed using the |listingname| option. For example,
+
+\begin{verbatim}
+\begin{pyglist}[language=java,caption={First Java program},%
+                listingname=\textbf{Program}]
+// Hello Java program
+      .
+      .
+      .
+\end{pyglist}
+\end{verbatim}
+
+produces the following result:
 
-   . . .
+\begin{pyglist}[language=java,caption={First Java program},%
+                listingname=\textbf{Program},fontsize=\MacroFont]
+// Hello Java program
+      .
+      .
+      .
+\end{pyglist}
+
+It is also possible to specify the background color of the caption text and label of a listing, as well as their individual font (and possibly other) characteristics. For example,
 
+\begin{verbatim}
+\begin{pyglist}[language=java,caption={First Java program},%
+       listingnamefont=\sffamily\bfseries\color{yellow},%
+       captionfont=\sffamily\color{white},captionbgcolor=gray]
+// Hello Java program
+      .
+      .
+      .
 \end{pyglist}
 \end{verbatim}
 
+produces the following result:
+
+\begin{pyglist}[language=java,caption={First Java program},%
+       listingnamefont=\sffamily\bfseries\color{yellow},%
+       captionfont=\sffamily\color{white},captionbgcolor=gray,fontsize=\MacroFont]
+// Hello Java program
+      .
+      .
+      .
+\end{pyglist}
+
 \bigskip
 \DescribeMacro{\listofpyglistings}
-If source code listings in a document are decorated with captions, their list can be produced with the |\listofpyglistings| command. This is akin to list of figures, list of tables and other table-of-contents counterparts.
+If source code listings in a document are decorated with captions, their list can be produced with the |\listofpyglistings| command. This is akin to the list of figures, list of tables and other table-of-contents counterparts.
 
 \bigskip
 \DescribeMacro{\listofpyglistingsname}
@@ -182,10 +251,10 @@ Heading of the list of listings is |Listings| by default. This can be changed us
 \listofpyglistingsname{List of Programs}
 \end{verbatim}
 
+%\begin{center}*\quad*\quad*\end{center}\nopagebreak[4]
+\section{\texttt{fancyvrb} options}
 
-\begin{center}*\quad*\quad*\end{center}\nopagebreak[4]
-
-The \texttt{pyglist} environment is actualy typeset using the \texttt{Verbatim} environment of the \texttt{fancyvrb} package. That's why all \texttt{Verbatim} options are also in effect in the \texttt{pyglist} environment. For example,
+The \texttt{pyglist} environment is actualy typeset using the \texttt{Verbatim} environment of the \texttt{fancyvrb} package. That's why all \texttt{fancyvrb} options are also in effect in the \texttt{pyglist} environment. For a more detailed \texttt{fancyvrb} options description, please refer to the documentation of the \texttt{fancyvrb} package. For example,
 
 \begin{verbatim}
 \fvset{frame=single}
@@ -218,8 +287,34 @@ main()
 \end{pyglist}
 \fvset{frame=none}
 
-\medskip
-For a more detailed \texttt{Verbatim} option descriptions, please refer to the documentation of the \texttt{fancyvrb} package.
+\bigskip
+
+The \texttt{fancyvrb} options set with the |\fvset| command are  global. They can be also set locally using the |fvset| option of the |pyglist| environment. For example,
+
+\begin{verbatim}
+\begin{pyglist}[language=java,caption={First Java program},%
+       listingnamefont=\sffamily\bfseries\color{white},%
+       captionfont=\sffamily\color{white},captionbgcolor=gray,%
+       fvset={frame=bottomline,framerule=4pt,rulecolor=\color{gray}}]
+// Hello Java program
+      .
+      .
+      .
+\end{pyglist}
+\end{verbatim}
+
+produces the following result:
+
+\begin{pyglist}[language=java,caption={First Java program},%
+       listingnamefont=\sffamily\bfseries\color{white},%
+       captionfont=\sffamily\color{white},captionbgcolor=gray,%
+       fvset={frame=bottomline,framerule=4pt,rulecolor=\color{gray}},%
+       fontsize=\MacroFont]
+// Hello Java program
+      .
+      .
+      .
+\end{pyglist}
 
 \section{Options}
 
@@ -234,11 +329,16 @@ The following is a full list of available options for the \texttt{pyglist} envir
     Background color of the listing (default: |white|).
   \item[caption (string)]
     Caption text of the listing (default: \emph{none}).
+  \item[captionbgcolor (color name)]
+    Background color of the caption text and label of the listing (default: \emph{none}).
+  \item[captionfont (font spec)]
+    Font (and possibly other) specifications prepended to the caption text of the listing (default: |{}|).
   \item[encoding (string)]
     Encoding of intermediate input and output files with syntax markup used by Pygments (default: |latin1|). For more information, please refer to the Pygments documentation.
   \item[fontsize (font size)]
-    Font size to use for the listing (default: |auto|\Dash the same as the
-current font).
+    Font size to use for the listing (default: |auto|\Dash the same as the current font).
+  \item[fvset (options)]
+    The |fancyvrb| package options to use locally for the listing (default: \emph{none}). For more information, please refer to the |fancyvrb| documentation.
   \item[gobble (integer)]
     Removes the first $n$ characters from each input line of the source code (default: |0|).
   \item[language (string)]
@@ -247,6 +347,8 @@ current font).
     Label that makes the listing referable via |\ref{label}| (default: \emph{none}).
   \item[listingname (string)]
     Caption label to use as a prefix to the caption text of the listing (default: |Listing|).
+  \item[listingnamefont (font spec)]
+    Font (and possibly other) specifications prepended to the caption label of the listing (default: |{}|).
   \item[mathescape (boolean)]
     Enables \LaTeX{} math mode inside comments (default: |false|).
   \item[numbers (none$\mid$left$\mid$right)]
@@ -254,7 +356,7 @@ current font).
   \item[numbersep (dimension)]
    Gap between numbers and start of the listing lines (default: |12pt|).
   \item[showspaces (boolean)]
-    Enables visible spaces. The space character is printed as the symbol \verb*/ / (default: |false|).
+    Enables visible spaces. The space character is printed as the symbol \verb*/ / (default: \emph{none}).
   \item[style (string)]
     Style for Pygments to use for the source code highlighting (default: |default|). For more information, please refer to the Pygments documentation.
   \item[texcl (boolean)]
@@ -265,20 +367,25 @@ current font).
 
 \begin{itemize}
 \item Implement package distribution file. (Problems: (1) the \% sign in the Pygments style file is gobbled up by |\DocStrip| in examples; (2) spurious blanks appear in the highlighted example code.)
-\item Implement escape sequences. (This is probably more suitable task for Pygments lexers and formatters?)
-\item More testing.
+\item Implement escape sequences. (This is probably more suitable task for the Pygments lexers and formatters?)
+%\item More testing.
 \end{itemize}
 
 \section{Version history}
 
 \begin{verlist}
+\item[v1.2\quad 2011/08/20] \mbox{}\\
+Added |captionbgcolor|, |captionfont|, |listingnamefont|, and |fvset| options.\\
+Did minor code cleaning.\\
+Revised documentation to include the new options.
+
 \item[v1.1\quad 2011/07/07] \mbox{}\\
-Added the |\listofpyglistingsname| user command\\
-Changed handling of the list of listings\\
-Revised documentation and examples
+Added the |\listofpyglistingsname| user command.\\
+Changed handling of the list of listings.\\
+Revised documentation and examples.
 
 \item[v1.0\quad 2011/06/07] \mbox{}\\
-Initial public release
+Initial public release.
 \end{verlist}
 
 \end{document}
diff --git a/Master/texmf-dist/tex/latex/verbments/verbments.sty b/Master/texmf-dist/tex/latex/verbments/verbments.sty
index cbcb8c64661..05c83f18c8c 100644
--- a/Master/texmf-dist/tex/latex/verbments/verbments.sty
+++ b/Master/texmf-dist/tex/latex/verbments/verbments.sty
@@ -1,4 +1,4 @@
-% verbments.sty   v1.1   2011/07/07
+% verbments.sty   v1.2   2011/08/20
 %
 % Copyright (C) 2011 by Dejan Zivkovic
 % -----------------------------------
@@ -14,13 +14,13 @@
 % version 1999/12/01 or later.
 %
 \NeedsTeXFormat{LaTeX2e}
-\ProvidesPackage{verbments}[2011/07/07 v1.1 Pygments/fancyvrb source code highlighting for LaTeX]
-\RequirePackage[svgnames]{xcolor}
-\RequirePackage{xkeyval,fancyvrb,framed}
+\ProvidesPackage{verbments}[2011/08/20 v1.2 Pygments/fancyvrb source code highlighting for LaTeX]
+\RequirePackage{xkeyval,fancyvrb,framed,xcolor,calc}
 %
 \newcommand{\@listofpyglistingsname}{Listings}%
 \newcommand{\listofpyglistingsname}[1]{%
-\renewcommand\@listofpyglistingsname{#1}}
+  \renewcommand\@listofpyglistingsname{#1}
+}
 \newcommand{\listofpyglistings}{%
   \begingroup
     \let\contentsname\@listofpyglistingsname
@@ -37,14 +37,14 @@
 %
 \newlength{\@tmpwidth}
 %
-\newskip\@tmpskipa
+\newskip\@tmpvskip
 \def\max@vskip #1{%
-   \@tmpskipa = #1\relax
-   \ifdim\lastskip < \@tmpskipa
+   \@tmpvskip = #1\relax
+   \ifdim\lastskip < \@tmpvskip
      \ifdim\lastskip = 0pt
      \else \vskip -\lastskip
      \fi
-     \vskip \@tmpskipa
+     \vskip \@tmpvskip
    \fi%
 }
 
@@ -52,9 +52,12 @@
 \setlength{\FrameRule}{0pt}
 %
 \define@cmdkey{pyglist}[pl@]{caption}{}
+\define@cmdkey{pyglist}[pl@]{captionfont}[{}]{}
 \define@cmdkey{pyglist}[pl@]{abovecaptionskip}[\bigskipamount]{}
 \define@cmdkey{pyglist}[pl@]{belowcaptionskip}[0pt]{}
 \define@cmdkey{pyglist}[pl@]{listingname}[Listing]{}
+\define@cmdkey{pyglist}[pl@]{listingnamefont}[{}]{}
+\define@cmdkey{pyglist}[pl@]{captionbgcolor}{}
 \define@cmdkey{pyglist}[pl@]{label}{}
 %
 \define@cmdkey{pyglist}[pl@]{bgcolor}[white]{}
@@ -65,10 +68,11 @@
 \define@cmdkey{pyglist}[pl@]{style}[default]{}
 \define@cmdkey{pyglist}[pl@]{gobble}[0]{}
 %
-\define@cmdkey{pyglist}[pl@]{fontsize}{}
-\define@cmdkey{pyglist}[pl@]{numbers}{}
-\define@cmdkey{pyglist}[pl@]{numbersep}{}
-\define@boolkey{pyglist}[pl@]{showspaces}[false]{}
+\define@cmdkey{pyglist}[pl@]{fvset}{\fvset{#1}}
+\define@cmdkey{pyglist}[pl@]{fontsize}{\fvset{fontsize=#1}}
+\define@cmdkey{pyglist}[pl@]{numbers}{\fvset{numbers=#1}}
+\define@cmdkey{pyglist}[pl@]{numbersep}{\fvset{numbersep=#1}}
+\define@boolkey{pyglist}[pl@]{showspaces}{\fvset{showspaces=#1}}
 
 \newcommand\plset[1]{%
   \setkeys{pyglist}{#1}%
@@ -87,25 +91,32 @@
 %
   \partopsep = 0pt\parskip = 0pt\parindent = 0pt%
   \@ifundefined{pl@caption}%
-  {\setlength{\topsep}{-2pt}}%
+  {\setlength{\topsep}{0pt}}%
   {\par%
-   \allowbreak%
    \max@vskip{\pl@abovecaptionskip}%
+   \penalty -100% encourage page break
    \refstepcounter{pllisting}%
    \@ifundefined{pl@label}{}{\label{\pl@label}}%
-   \settowidth{\@tmpwidth}{\bfseries\pl@listingname~\thepllisting:\space}%
-   \mbox{\bfseries\pl@listingname~\thepllisting:\space}%
-   \parbox[t]{\linewidth-\@tmpwidth}{\pl@caption}%
-   \par\nobreak\vskip\pl@belowcaptionskip\nobreak%
+   \@tmpvskip=3\baselineskip%
+   \vskip \@tmpvskip\penalty 1000\vskip -\@tmpvskip\vskip \z@skip% prevent page break
+   \settowidth{\@tmpwidth}{\pl@listingnamefont\pl@listingname~\thepllisting:\space}%
+   \@ifundefined{pl@captionbgcolor}%
+   {\mbox{\pl@listingnamefont\pl@listingname~\thepllisting:\space}%
+    \parbox[t]{\linewidth-\@tmpwidth}%
+      {\leavevmode\pl@captionfont\pl@caption}%
+   }
+   {\setlength{\fboxrule}{0pt}\setlength{\fboxsep}{4pt}%
+    \colorbox{\pl@captionbgcolor}{%
+    \mbox{\pl@listingnamefont\pl@listingname~\thepllisting:\space}%
+    \parbox[t]{\linewidth-\@tmpwidth-2\fboxsep}%
+      {\leavevmode\pl@captionfont\pl@caption}%
+    }%
+   }%
+   \par\nobreak\vskip\pl@belowcaptionskip% 
    \setlength{\topsep}{\smallskipamount}%
    \lol@caption{\rlap{\thepllisting}\hskip5ex \pl@caption}
   }%
 %
-  \@ifundefined{pl@fontsize}{}{\fvset{fontsize=\pl@fontsize}}%
-  \@ifundefined{pl@numbers}{}{\fvset{numbers=\pl@numbers}}%
-  \@ifundefined{pl@numbersep}{}{\fvset{numbersep=\pl@numbersep}}%
-  \ifpl@showspaces\fvset{showspaces}\fi%
-%
   \definecolor{shadecolor}{named}{\pl@bgcolor}% 
   \begin{snugshade}
   \input{\jobname.pyg.vrb}
@@ -122,7 +133,7 @@
      -o \jobname.pyg.vrb \jobname.pyg.lst}
   \edef\pyg@style{pygmentize -S \pl@style\space -f latex > \jobname.pyg.sty}
   \VerbatimEnvironment
-  \begin{VerbatimOut}{\jobname.pyg.lst}% No char whatsoever to the next brace
+  \begin{VerbatimOut}{\jobname.pyg.lst}% NO char whatsoever to the next brace
 }
 
 \AtBeginDocument{
@@ -136,7 +147,8 @@
   }
 }
 
-\plset{abovecaptionskip,belowcaptionskip,listingname,%
-       bgcolor,language,encoding,mathescape,texcl,style,gobble,%
-       showspaces} % set default key values
+% Set default key values
+\plset{captionfont,abovecaptionskip,belowcaptionskip,listingname,listingnamefont,%
+       bgcolor,language,encoding,mathescape,texcl,style,gobble%
+}
 \endinput