\ProvidesFile{niceverb.tex}[2009/02/23 documenting niceverb.sty]
\title{\textsf{niceverb.sty}\\---\\Minimizing 
  Markup\\for Documenting \LaTeX\ packages\thanks{This 
    manual describes package version
    version 0.1 as of February 23, 2009%%%\fileversion\ as of \filedate\ 
    .}}%%%of the package.}}
\author{Uwe L\"uck\\{\tt http://contact-ednotes.sty.de.vu}}
\input{makedoc}
\documentclass[12pt,a4paper]{article}
\usepackage{niceverb} 
\usepackage{moreverb}
% \usepackage{verbatim} 
\newenvironment{packagecode}
  {\PackageCode}
  {\endPackageCode}
  \gdef\PackageCode{\listing[5]{1}}
  \gdef\endPackageCode{%
    \endlisting
    \global\let\PackageCode\listingcont
    \global\let\endPackageCode\endlistingcont}
\begin{document}
\maketitle

\tableofcontents

\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}
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.

The package 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' may also help to generate without much effort documentations 
of nowadays commonly expected typographical quality for packages that 
so far only had ASCII 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.''

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 replacing &\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---containing 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{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 with 
parentheses. (You can correct spacing by \lq`\ '\rq.)
\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\ should be active and provide a 
version of the `decl' environment of 'ltxguide.cls'.
\end{enumerate}

\section{Implementation of the Markup Syntax}
% \verbatiminput{niceverb.sty}
% \listinginput[5]{1}{niceverb.sty}
\input{niceverb.doc}

\section{Code Preparing Source for Typesetting}
This is at present in a file `makedoc.tex'.
\listinginput[5]{1}{makedoc}
\end{document}
