From ee53eac199e12fb91859fd18a43dd506ff75e3a9 Mon Sep 17 00:00:00 2001
From: Karl Berry <karl@freefriends.org>
Date: Mon, 20 Apr 2009 22:50:28 +0000
Subject: nicetext update (20apr09)

git-svn-id: svn://tug.org/texlive/trunk@12766 c570f23f-e606-0410-a88d-b1316a301751
---
 .../texmf-dist/source/latex/nicetext/niceverb.tex  | 331 +++++++++++++++++++++
 1 file changed, 331 insertions(+)
 create mode 100644 Master/texmf-dist/source/latex/nicetext/niceverb.tex

(limited to 'Master/texmf-dist/source/latex/nicetext/niceverb.tex')

diff --git a/Master/texmf-dist/source/latex/nicetext/niceverb.tex b/Master/texmf-dist/source/latex/nicetext/niceverb.tex
new file mode 100644
index 00000000000..629d240c458
--- /dev/null
+++ b/Master/texmf-dist/source/latex/nicetext/niceverb.tex
@@ -0,0 +1,331 @@
+\ProvidesFile{niceverb.tex}[2009/04/15 documenting niceverb.sty]
+\title{\textsf{niceverb.sty}\\---\\Minimizing 
+  Markup\\for Documenting \LaTeX\ packages%%% \thanks{This 
+%     manual describes package version
+%     version 0.2 as of April 09, 2009%%%\fileversion\ as of \filedate\ 
+%     .}}%%%of the package.}%
+}
+\author{Uwe L\"uck\\{\tt http://contact-ednotes.sty.de.vu}}
+\listfiles
+  \begingroup %% build niceverb.doc
+    \RequirePackage{makedoc}
+    \LaTeXresultFile{niceverb.doc} 
+    \HeaderLines{19}
+    \MainDocParser{\SectionLevelTwoParseInput}
+    \MakeDoc{niceverb.sty}
+    \CloseResultFile
+  \endgroup
+% \input{mknvdoc.tex}
+\documentclass{article}%% TODO paper dimensions!?
+\input{makedoc.cfg}\MakeOther\|%% TODO \verb| 2009/04/09
+%% removed 2009/04/09 for makedoc.sty:
+% \usepackage{niceverb} 
+% \usepackage{moreverb}
+% \usepackage{verbatim} 
+% \newenvironment{packagecode}
+%   {\PackageCode}
+%   {\endPackageCode}
+% \gdef\PackageCode{\small \listing[5]{1}}
+% \gdef\endPackageCode{%
+%   \endlisting
+%   \global\def\PackageCode{\small \listingcont}%
+%   \global\let\endPackageCode\endlistingcont}
+% \renewcommand*{\listinglabel}[1]{%
+%   \llap{\footnotesize\rmfamily\the#1}\hskip\listingoffset\relax}
+
+\begin{document}
+\maketitle
+
+\begin{abstract}\noindent\hspace{1sp}%% exemplifies a problem
+'niceverb.sty' provides very decent syntax for describing \LaTeX\ 
+packages and the syntax of macros conforming to \LaTeX\ syntax 
+conventions. 
+\end{abstract}
+\tableofcontents
+
+  %% TODO table listing active characters
+\section{Presenting 'niceverb'}
+\subsection{Purpose}
+% \begin{abstract}\noindent
+% The 'nicetext' bundle provides ``minimal'' markup 
+The 'niceverb' package provides ``minimal'' markup for documenting \LaTeX\ 
+packages, reducing the number of keystrokes/visible characters needed
+% .\,.\,. %%% ... %% TODO nicedots 
+(kind of poor man's WYSIWYG).\footnote{``What you see is what you 
+get.'' Novices are always warned that WYSIWYG is essentially 
+impossible with \LaTeX.}
+% One feature---\verb'&\foo'%%% badly self-documenting, `&' fails
+It conveniently handles command names in arguments of macros 
+such as &\footnote or even of sectioning commands. 
+% (`.aux'/`.toc' entries).
+% 
+% This is done by making some characters active. 
+% 'niceverb.sty' thus resembles 'wiki.sty'; both are siblings. 
+% \end{abstract}
+If you use 'makedoc.sty' additionally, commands for typesetting a 
+package's code are inserted automatically (just using \TeX). 
+%%% \footnote{Stephan I. B\"ottcher used
+%%% 'awk' instead to typeset the documentation of his 'lineno.sty'.} 
+As opposed to tools that are rather common on UNIX/Linux, this 
+operation should work at any \TeX\ installation, irrespective of 
+platform.
+
+Both packages may at least be useful while working at a very new package 
+and may suffice with small, simple packages. After having edited your 
+package's code (typically in a `.sty' file), you just ``{`latex'}'' the 
+manual file (maybe some `.tex' file) and get instantly the corresponding 
+refreshed documentation.
+
+'niceverb' and 'makedoc' may also help to generate without much effort 
+documentations of nowadays commonly expected typographical quality for 
+packages that so far only had plain text documentations.
+
+\subsection{Acknowledgement/Basic Ideas}
+Three ideas of Stephan I. B\"ottcher's in documenting his 'lineno.sty' 
+inspired the present work: 
+\begin{enumerate}
+\item 
+The markup and its definitions are short and simple, 
+markup commands are placed at the right ``margin'' 
+of the ASCII file, 
+so you hardly see them in reading the source file, 
+you rather just read the text that will be printed. 
+\item 
+An 'awk' script removes the `%'s starting \emph{documentation} lines 
+and inserts the commands for typesetting the package's \emph{code} 
+(you don't see them in the source).
+\item 
+An active character (\lq&|\rq) issues a `\string' \emph{and} switches 
+to typewriter typeface for typesetting a command verbatim---so this 
+works without changing category codes (which is the usual idea of 
+typesetting code), therefore it works even in macro arguments.
+\end{enumerate}
+
+\subsection{The Commands and Features of 'niceverb'}
+
+Single quotes \verb|`|, \verb|'|, ``less than'' \verb|<| (accompanied 
+with \verb|>|), the hash mark \verb|#|, ampersand \verb|&|, and in an 
+extended ``auto mode'' even backslash \verb|\| become &\active 
+characters with ``special effects.'' \lq`|'\,.\,.\,.\,`|'\rq\
+should highlight descriptions of user commands and their syntax. 
+
+The package mainly aims at typesetting commands and descriptions of their 
+syntax \emph{if the latter is ``standard \LaTeX-like''}, 
+using ``meta-variables.'' A string to be 
+typeset ``verbatim'' thus is assumed to start with a single command like 
+&\foo, maybe followed by stars (\lq`*'\rq) and pairs of 
+square brackets (`['.\,.\,.`]') or 
+curly braces (\verb'{'.\,.\,.\verb'}'), 
+where those pairs contain strings indicating the typical 
+kinds of contents for the respective arguments of that command.
+A typical example is this: 
+\[&\foo*[<opt-arg>]{<mand-arg>}\]
+This was achieved by typing \[\verb'&\foo*[<opt-arg>]{<mand-arg>}'\]
+In ``auto mode'' of the package, even typing 
+\[\verb|\foo*[<opt-arg>]{<mand-arg>}|\]
+  %% angle brackets feature to be suppressed here!
+would have sufficed---WYSIWYG! (I call such mixtures of 
+\emph{verbatim} and ``meta-variables'' \textit{\lq meta-code\rq}.)
+
+Now for the details:
+\begin{description}
+
+\item[``Meta-variables:''] {\sloppy The package supports the ``angle 
+brackets'' style of ``meta-variables'' (as with <meta-variable>). 
+You just type \lq\verb'<foo>'\rq\ to get \lq<foo>\rq.\par}
+
+This works due to a sloppy variant &\SimpleVerb of &\verb 
+which doesn't care about possible ligatures and definitions of active 
+characters. Instead, it assumes that the ``verbatim'' font doesn't 
+contain ligatures anyway. \lq\verb'\verb|<foo>|'\rq, by contrast, just 
+yields \lq\verb'<foo>'\rq.
+
+Almost the same feature is offered by 'ltxguide.cls' which formats the 
+basic guides from the \LaTeX\ Project Team. The present feature, 
+however, also works in plain text outside verbatim mode. 
+% On the other hand: without << feature
+
+\item[Single quotes (left/right) for ``short verb:'']
+{\sloppy The package ``assumes'' that \emph{quoting} refers to 
+\emph{code}, therefore \lq\verb|`foo'|\rq\ is typeset as 
+\lq`foo'\rq. This somewhat resembles the &\MakeShortVerb feature of 
+'doc.sty'.\par}
+
+It will typically fail when you try to typeset commands (and their 
+syntax) in \emph{macro arguments}---e.g., 
+$$\verb|\footnote{`\bar' is a celebrated fake example!}|$$
+will try to \emph{execute} &\bar instead of typesetting it, giving 
+an ``undefined'' error so.
+\verb|\verb| fails in the same situation, for the same reason. 
+\lq\verb|&|\rq\ (&\footnote{&&&\bar<remaining>}) or 
+``auto mode'' (see below) may then work better.
+
+Double quotes and apostrophes should still work the usual way; 
+otherwise you could control the parsing mechanisms using curly braces 
+(outside and inside don't interact).
+To get usual single quotes, you can use their standard substitutes 
+`\lq' and `\rq'. 
+You can ``abuse'' this ``single quotes'' feature just to get typewriter 
+typeface.\footnote{In macro arguments this requires that the right 
+single quote &' is &\active.}
+For difficult cases, you can still use the standard `\verb' 
+command from \LaTeX.
+
+\item[Single right quotes for &\textsf:]
+{\sloppy Package names are (by some unwritten convention!?) 
+typeset with `\textsf'; 
+it was natural to use a remaining case of using single quotes 
+for abbreviating &\textsf{<text>} by \SimpleVerb|'<text>'|.\footnote{%
+Font switching by sequences of single quotes is a feature of the 
+syntax for editing Wikipedia pages and of 'wiki.sty'.}\par}
+%% TODO fails in parentheses due to preserving apostrophes
+
+This idea of switching fonts continues font switching of 'wiki.sty'
+which uses the syntax for editing Wikipedia pages. 
+
+\item[Ampersand \lq&&\rq\ typesets command syntax even in arguments:] 
+\hfil e.g., type \lq\verb|&\foo{<arg>}|\rq\ to get 
+\lq`\foo{<arg>}'\rq. This may be even more convenient for typing than 
+the single quotes method, although looking somewhat strange.
+However, `&' may terminate \textit{verbatim} unexpectedly, being 
+designed for displaying ``\LaTeX-like command syntax'' in the first
+instance.\footnote{Moreover, && currently has a limited 'xspace' 
+functionality only.}\footnote{You can even use && for referring to 
+  active characters like && in footnotes etc.!}
+
+\begin{sloppypar}
+This choice of `&' rests on the assumption that there won't be many 
+tables in the documenation. You can restore the usual meaning of `&' 
+by \verb|\MakeAlign\&| and turn the present special meaning on again by 
+$$\verb|\MakeActiveLet\&\CmdSyntaxVerb|.$$ 
+You could also 
+redefine (&\renewcommand) &\descriptionlabel using `\CmdSyntaxVerb' 
+(the ``normal command'' equivalent to `&') so \verb|\item[\foo]| works 
+as wanted.
+\end{sloppypar}
+
+\item[``Auto mode'' typesets commands verbatim unless .\,.\,.]
+{\sloppy 
+\hfil In~``auto mode'', the backslash \lq`\'\rq\ is an active character that 
+builds a command name from the ensuing letters and typesets the 
+command (and its syntax, allowing meta-variables) verbatim. 
+However, there are some exceptions, which are collected in a macro 
+&\niceverbNoVerbList. &\begin, &\end, and &\item belong to this list, 
+you can redefine (`\renewcommand') it.
+There is also a command &\NormalCommand{<letters>} \emph{issuing} the 
+command `\<letters>' instead of typesetting it.
+Since auto mode is somewhat dangerous, you have to start it explicitly 
+by &\AutoCmdSyntaxVerb. You can end it by &\EndAutoCmdSyntaxVerb.\par}
+
+Auto mode is motivated by the observation that there are package files 
+containing their documentation as pure (well-readable) ASCII 
+text---contain\-ing the names of the new commands without any kind of 
+quotation marks or verbatim commands. 
+Auto mode should typeset such documentation just from the same ASCII 
+text.
+
+\item[Hash mark &# comes verbatim.]
+No macro definitions are expected in the `document' 
+environment.\footnote{This idea recently appeared on the 'latex-l' 
+mailing list. It may be wrong, not sure at the moment, think of 
+'latexa.ltx' .\,.\,.} 
+Rather, \lq`#'\rq\ is an active character for taking the next 
+character (assuming it is a digit) to form a reference to a 
+\emph{macro parameter}---\lq`#1'\rq\ becomes \lq#1\rq\ (WYSIWYG 
+indeed!). 
+\end{description}
+
+\subsection{Examples}
+The local configuration file 'mdcorr.cfg' documents itself using 
+'niceverb' syntax. Its code and the documentation that is typeset from 
+it are at the end of the \lq examples\rq\ section of 'makedoc.pdf'.
+(2009/04/15)
+
+Moreover, the documentation 'niceverb.pdf' of 'niceverb.sty' was 
+typeset from 'niceverb.tex' and 'niceverb.sty' using 'niceverb' 
+syntax, likewise 'fifinddo.pdf' and 'makedoc.pdf'. 
+The example of 'niceverb' shows the most frequent use of the `&' 
+feature. 
+
+It seems to me that I could type so many pages on 'fifinddo' and 
+'makedoc' in little more than a week 
+% (2009/04/12, much of which was needed for debugging and reworking concepts) 
+only due to the ``minimal'' \emph{verbatim} and syntax-display syntax. 
+
+\subsection{What is Wrong with the Present Version}
+\begin{enumerate}
+\item 'niceverb.sty' should be an extension of 'wiki.sty'; 
+      yet their font selection mechanisms are currently not compatible. 
+\item Font switching or horizontal spacing may fail in certain situations
+      (parentheses, titles, footnotes; you can correct spacing by 
+      \lq`\ '\rq).
+  %% TODO 2009/04/10 redefine \noindent, \footnote ... 
+  %%                 or use correcting function with 'fifinddo'
+% \item 
+% The feature of mixing high-quality-typeset comments into the 
+% package code listing is implemented in a very rudimentary way only. 
+% % just allowing for `\subsection's. 
+% The ``comment detector'' detects Wikipedia-style subsection titles 
+% instead of lines beginning with percent characters.\footnote{%
+% Percent characters will definitely not be ``ignored'' as with &\DocInput, 
+% rather they will hide rests of \emph{documentation} lines as usually, 
+% while they will be typeset verbatim in \emph{package code} lines.} 
+% Switching between plain and verbatim typesetting in the package 
+% listings isn't settled yet, since there are different styles of using 
+% percent symbols. I have sometimes used double percent symbols 
+% (\lq\verb|%%|\rq) 
+% for commenting text and single ones just for ``reversible deletion of 
+% code,'' while usually single percent symbols indicate commenting text 
+% indeed. Double percent symbols may, by contrast, mean that the text remains 
+% visible in the `.sty' file only, suppressed in the typeset 
+% documentation ('lineno.sty').
+% For a while, it may be necessary to provide replacing macros for each 
+% package separately instead of providing a single macro package 
+% managing all of them. 
+% \item 
+% The code listing currently uses the `listing' and `listingcont' 
+% environments of 'moreverb.sty'; 
+% the code font and the line numbers may be too large. 
+\item The ``vertical'' character \lq&|\rq\ was planned to be active 
+      and provide a version of the `decl' environment of 
+      'ltxguide.cls'. Currently 'makedoc.cfg' installs inline, 
+      coloured\slash framed boxes instead (2009/04/09). They have 
+      their merits! See 'fifinddo.pdf'  and 'makedoc.pdf'. However, 
+      they badly deal with long command names and many arguments 
+      .\,.\,. (They could also issue an `\index' command!)---Doubled 
+      verticals could make the difference, calling a `decl' table 
+      indeed. 
+\item ``Auto mode'' has not been tested on a serious application yet. 
+\item 'niceverb''s font switching tricks sometimes turn against their 
+      inventor (and other users?). There must be some switching 
+      ``off'' (and ``on'' again).%
+        \footnote{\hspace{1sp}'fifinddo'\slash\hspace{1sp}'makedoc'
+          %% <- TODO oh, oh! 2009/04/11
+          allow inserting such commands from a driver script, 
+          invisible in the file that contains the ``contentual'' 
+          documentation.}
+      Also, there might better help with weird errors, 
+      some syntax checks might intercept earlier. 
+
+      Similarly, some choices reflect a 
+      personal style and should be modifiable, especially by package 
+      options.\footnote{Please sponsor the project or support it 
+        otherwise!}
+\end{enumerate}
+
+\pagebreak[3] %% 2009/04/15
+\section{Implementation of the Markup Syntax}
+% \verbatiminput{niceverb.sty}
+% \listinginput[5]{1}{niceverb.sty}
+\input{niceverb.doc}
+
+%% removed 2009/04/09 for makedoc.sty:
+% \section{Code Preparing Source for Typesetting} 
+% This is at present in a file `mknvdoc.tex'.
+% \listinginput[5]{1}{mknvdoc}
+\end{document}
+
+2009/04/09: adjusted to new doc-generation method
+2009/04/12: examples, 'awk' lower-case
+2009/04/15: example 'mdcorr.cfg', abstract, 
+            \pagebreak to implementation
-- 
cgit v1.2.3

