showexpl update

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

1 files changed, 124 insertions, 23 deletions

diff --git a/Master/texmf-dist/source/latex/showexpl/showexpl.dtx b/Master/texmf-dist/source/latex/showexpl/showexpl.dtx
index de5e77937b7..45184ab676a 100644
--- a/Master/texmf-dist/source/latex/showexpl/showexpl.dtx
+++ b/Master/texmf-dist/source/latex/showexpl/showexpl.dtx
@@ -1,6 +1,6 @@
 % \iffalse meta-comment
 %
-% Copyright (C) 2004, 2005 by Rolf Niepraschk <Rolf.Niepraschk@ptb.de>
+% Copyright (C) 2004 -- 2006 by Rolf Niepraschk <Rolf.Niepraschk@ptb.de>
 % --------------------------------------------------------------------
 % 
 % This file may be distributed and/or modified under the
@@ -22,11 +22,11 @@
 %<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
 %<package>\ProvidesPackage{showexpl}
 %<*package>
-    [2005/12/06 v0.3d Typesetting example code (RN)]
+    [2006/09/18 v0.3g Typesetting example code (RN)]
 %</package>
 %
 %<*driver>
-\documentclass{ltxdoc}
+\documentclass[a4paper]{ltxdoc}
 \usepackage{showexpl}
 \EnableCrossrefs
 \CodelineIndex
@@ -39,7 +39,7 @@
 %</driver>
 % \fi
 %
-% \CheckSum{797}
+% \CheckSum{836}
 %
 % \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
@@ -97,19 +97,100 @@
 %
 % \title{The \textsf{showexpl} package\thanks{This document
 %   corresponds to \textsf{showexpl}~\fileversion, dated \filedate.}}
-% \author{Rolf Niepraschk\thanks{\texttt{Rolf.Niepraschk@ptb.de}}}
+% \author{Rolf Niepraschk (\texttt{Rolf.Niepraschk@ptb.de})}
 % \date{\filedate}
 %
 % \maketitle
 %
 % \section{Introduction}
 %
-% Put text here.
+% The documentation of a \LaTeX{} package is by far more readable if there
+% are examples of the commands' and environments' usage. The best way to do
+% that is to give a comparison of the \LaTeX{} code and the formatted
+% output. \textsf{showexpl} is a package for doing that comparison, it is
+% based on the package \textsf{listings} which provides a good typesetted
+% source code with emphasised keywords and so on.
 %
 % \section{Usage}
 %
-% Put text here.
+% You can use \textsf{showexpl} like every other package by putting the
+% line 
+% \begin{verbatim}
+% \usepackage{showexpl} 
+% \end{verbatim}
+% \vspace{-\baselineskip}
+% in your source code. \textsf{showexpl} doesn't know any options by
+% itself, but all options for the underlying packages 
+% (\textsf{listings} and \textsf{graphicx}) will be passed to the 
+% respective packages.
 %
+% \textsf{showexpl} provides one command and one environment:
+% \begin{itemize}
+% \item |\LTXinputExample| and
+% \item \textsf{LTXexample}
+% \end{itemize} 
+%
+% \DescribeMacro{\LTXinputExample}
+% The syntax of |\LTXinputExample| is given by
+% \begin{quote}
+% |\LTXinputExample[|\meta{key val list}|]{|\meta{file}|}|    
+% \end{quote}
+% 
+% \DescribeEnv{LTXexample}
+% The syntax of the environment \textsf{LTXExample} is given by
+% \begin{quote}
+% |\begin{LTXExample}[|\meta{key val list}|]|\ldots|\end{LTXExample}|    
+% \end{quote}
+%
+% The set of options represented by \meta{key val list} is the same for
+% both the command and the environment, the options are described in the
+% following:
+% \begin{description}
+%   \item[attachfile] Boolean valued key, default value: false. If set to
+%   true the sourcecode will be attached to the \textsf{.pdf}
+%   file---presumed that the document is processed by |pdflatex|.
+%   \item[codefile] Name of the (temporary) file that contains the code
+%   which will be formatted as source code. The default value is |\jobname.tmp|.
+%   \item[explpreset] A \meta{key val list} which serves for presetting the
+%   properties of the formatting of the source code, for values see the
+%   documentation of the \textsf{listings} package. The default value is
+%   
+%   \item[graphic] Name of a (graphic) file. This file---if present---will
+%   be included and displayed instead of the formatted code. The default value is empty.
+%   \item[hsep] Defines the horizontal distance between the source code and the
+%   formatted text.
+%   \item[justification] Defines the justification of the formatted text:
+%   reasonable values are |\raggedleft|, |\raggedright|, |\centering|. The
+%   default value is |\raggedright|.
+%   \item[overhang] A \textit{dimen}-value that defines the amount by which
+%   the formatted text and the source code can overlap the print space. The
+%   default value is 0\,pt.
+%   \item[pos:] Defines the relative position of the formatted text
+%   relating to the source code. Allowed values are |a|, |b|, |l|, |r|,
+%   |o|, and |i| for above, below, left, right, outer, and inner. The last
+%   values give sense only for two-sided printing, where there are outer
+%   and inner margins of a page. The default value is |l|.
+%   \item[preset] Any \TeX\ code executed before the sample code but 
+%   not visible in the listings area.
+%   \item[rangeaccept] Boolean valued key, default value is false. If set
+%   to  true, one can define ranges of lines that will be excerpted from
+%   the source code.
+%   \item[rframe] Defines the form of the frame around the formatted
+%   text. With a non-empty value (e.\,g. ``single'') a simple frame 
+%   will be drawn. In the future more kinds of frames will be supported.
+%   The default value is empty (no frame).
+%   \item[varwidth] Boolean valued key, default value is false. If set to
+%   true, the formatted text is set with its ``natural'' width instead of a
+%   fixed width as given by the value of the option |width|.
+%   \item[hsep] Defines the vertical distance between the source code and the
+%   formatted text.
+%   \item[wide] Boolean valued key, default value is false. If set to
+%   true, the source code and the formatted text overlap the print space
+%   and the margin area.
+%   \item[width] A \meta{dimen} value that defines the width of the
+%   formatted text. The default value depends of the relative positions of
+%   the source code and the formatted text.
+% \end{description}
 %
 % \StopEventually{}
 %
@@ -197,6 +278,11 @@
 \newcommand*\SX@rframe{}
 \newcommand\SX@preset{}
 \newcommand*\SX@explpreset{}
+%    \end{macrocode}
+% \changes{v0.3g}{2006/09/05}{Missing \cmd{\newcommand} for 
+%   \cmd{\SX@@explpreset} added (RN).}
+%    \begin{macrocode}
+\newcommand*\SX@@explpreset{}
 \newcommand*\SX@codefile{}\edef\SX@codefile{\jobname.tmp}
 \newcommand*\SX@justification{\raggedright}
 %    \end{macrocode}
@@ -205,6 +291,7 @@
 % nothing. \cmd{\SX@@preset} will be called just before 
 % typesetting the result of the example code. More can be added with 
 % the user key ``|preset=...|''.
+% \changes{v0.3e}{2006/04/05}{More redefinitions added (RN).}
 %    \begin{macrocode}  
 \newcommand*\SX@@preset{%
   \renewcommand\documentclass[2][]{\SX@eat@version}%
@@ -213,15 +300,19 @@
   \renewenvironment{figure}[1][]{\def\@captype{figure}}{}%
   \renewenvironment{table}[1][]{\def\@captype{table}}{}%
   \renewcommand\cite[1][]{}%
-  \let\tableofcontens\relax
-  \let\listoffigures\relax
-  \let\listoftables\relax
-  \let\printindex\relax
-  \let\listfiles\relax
-  \let\nofiles\relax
-  \let\index\@gobble
-  \let\label\@gobble
+  \let\tableofcontens\relax \let\listoffigures\relax
+  \let\listoftables\relax \let\printindex\relax
+  \let\listfiles\relax \let\nofiles\relax
+  \let\index\@gobble \let\label\@gobble
   \let\bibliography\@gobble
+  \let\pagestyle\@gobble \let\thispagestyle\@gobble
+  %%\let\immediate\relax \let\write\@gobbletwo
+  %%\let\closeout\@gobble \let\@@input\@gobble
+  \renewcommand\marginpar[2][]{}%
+  \renewcommand\footnote[2][]{}%
+  \let\@footnotetext\@gobble
+  %%\abovedisplayskip=\z@
+  %%\abovedisplayshortskip=\z@
 }
 \newcommand*\SX@eat@version[1][]{}
 %    \end{macrocode}
@@ -444,10 +535,16 @@
     \gdef\SX@@explpreset{}%
   \endgroup
 }
+%    \end{macrocode}
+% \changes{v0.3g}{2006/09/05}{\cmd{\SX@ProcessResult} is now working 
+% correctly
+% using \cmd{\readline} and \cmd{\scantokens}. Thanks to Ulrich Diez 
+% for help (RN).}
+%    \begin{macrocode}
 \newcommand\SX@SkipToFirst{%
   \ifeof\@inputcheck\else
     \ifnum \lst@lineno=\lst@firstline\else
-      \read\@inputcheck to\SX@tempa
+      \readline\@inputcheck to\SX@tempa
       \typeout{IGNORE (\the\lst@lineno)}%
       \global\advance\lst@lineno\@ne
       \SX@SkipToFirst
@@ -455,9 +552,11 @@
   \fi
 }
 \newcommand\SX@ProcessResult{%
-  \ifeof\@inputcheck\else
+  \ifeof\@inputcheck
+    \let\SX@tempb\relax
+  \else
     \let\SX@tempb\SX@ProcessResult
-    \ifnum \lst@lineno>\lst@lastline
+    \ifnum \lst@lineno>\lst@lastline\relax
       \ifx\lst@linerange\@empty
         \let\SX@tempb\relax
       \else
@@ -465,13 +564,14 @@
         \SX@SkipToFirst
       \fi
     \else
-      \read\@inputcheck to\SX@tempa
+      \readline\@inputcheck to\SX@tempa
       \typeout{READ (\the\lst@lineno)}%
-      \expandafter\g@addto@macro\expandafter\SX@lines\expandafter{\SX@tempa}%
+      \expandafter\g@addto@macro
+        \expandafter\SX@lines\expandafter{\SX@tempa^^J}%
       \global\advance\lst@lineno\@ne
     \fi
-    \expandafter\SX@tempb
   \fi
+  \SX@tempb
 }
 %    \end{macrocode}
 % \begin{macro}{\SX@input}
@@ -483,7 +583,7 @@
     {%
       \filename@parse{#1}%
       \ifx\filename@ext\relax \def\filename@ext{tex}\fi
-      \@latexerr{File 
+      \@latexerr{File
         `\filename@area\filename@base.\filename@ext' not found.^^J^^J}\@ehd%
     }%
     \openin\@inputcheck#1
@@ -494,10 +594,11 @@
     \fi
     \lst@GetLineInterval
     \SX@Info
+    \newlinechar=`\^^J\relax
     \SX@SkipToFirst\let\SX@lines\@empty
     \SX@ProcessResult
     \closein\@inputcheck
-    \SX@lines
+    \scantokens\expandafter{\SX@lines}%
   \endgroup
 }
 %    \end{macrocode}