summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/showexpl
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/showexpl')
-rw-r--r--Master/texmf-dist/source/latex/showexpl/showexpl.dtx147
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}
generated by cgit v1.2.3 (git 2.39.1) at 2024-12-28 18:39:05 +0000