\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*[]{}$$ This was achieved by typing \verb'&\foo*[]{}'. In ``auto mode'' of the package, even typing $$\verb|\foo*[]{}|$$ %% 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 ). You just type \lq\verb''\rq\ to get \lq\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||'\rq, by contrast, just yields \lq\verb''\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}) 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{} by \SimpleVerb|''|.\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{}|\rq\ to get \lq`\foo{}'\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{} \emph{issuing} the command `\' 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}