path: root/Master/texmf-dist/source/latex/nicetext/niceverb.tex

\ProvidesFile{niceverb.tex}[2011/10/07 documenting niceverb.sty]
\title{\textsf{niceverb.sty}\\---\\Minimizing 
  Markup\\for Documenting \LaTeX\ packages\thanks{This 
    document describes version 
    \textcolor{blue}{\UseVersionOf{niceverb.sty}}
    of \pkgnamefmt{niceverb.sty} as of \UseDateOf{niceverb.sty}.}
}
% \listfiles 2010/03/19
{ \RequirePackage{makedoc} \ProcessLineMessage{} %% 2010/03/11
  \MakeJobDoc{19}{\SectionLevelThreeParseInput}  }
\documentclass{article}%% TODO paper dimensions!?
\input{makedoc.cfg} %% shared formatting settings
%% 2011/08/22:
\MDkeywords{literate programming, syntactic sugar,
            .txt to .tex enhancement, macro programming}
\hypersetup{%% was `syntacic' 2011/10/07:
    pdftitle=syntactic sugar for LaTeX documentation by niceverb.sty,
    pdfsubject=documenting niceverb.sty
}%% /2011/08/22
\begin{document}
\maketitle
\begin{MDabstract}
'niceverb.sty' provides very decent syntax (through active characters) 
for describing \LaTeX\ packages and the syntax of macros conforming to 
\LaTeX\ syntax conventions.
\end{MDabstract}
\tableofcontents

  %% TODO table listing of active characters
%% Were tests 2010/03/08:
% \section{Presenting Nasty's `Nasty' ``Nasty'' &\NVerb\ 'niceverb'}
% \section{Presenting \cs{NVerb} 'niceverb'}
\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 \acro{WYSIWYG}).\footnote{``What you see is what you 
  get." Novices are always warned that \acro{WYSIWYG} is essentially 
  impossible with \LaTeX.} %% TODO UK FAQ 2010/03/11
% 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 
%% <jobname> 2010/02/28:
(typically in a `.sty' file---<jobname>`.sty'), 
you just ``{`latex'}" the manual file 
(maybe some `.tex' file---<jobname>`.tex') 
and get instantly the corresponding updated 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}
\emph{Four}                                         %% 2011/01/26
ideas of Stephan I. B\"ottcher's in documenting his 
\ctanpkgref{lineno} 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 these commands in the source).\footnote{The 
  corresponding part of the ``present work" is 'makedoc.sty'.} 
  %% <- clarified 2010/03/11
\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.
\item                                               %% 2011/01/26
\lq\HardNVerb+<meta-variable>+\rq\ produces \lq<meta-variable>\rq. 
(\qtd{&\lessthan} stores the original \qtd{&<}.)
\end{enumerate}

\subsection{The Commands and Features of 'niceverb'}
Actually, it is the main purpose of 'niceverb' to save you from 
``commands" $\dots$\par
Single quotes &`, &', ``less than" &< (accompanied 
with `>'), the ``vertical" &|, the hash mark `#', ampersand `&', 
and in an extended ``auto mode" even backslash `\' become `\active'
characters with ``special effects." 
% \qtd{&|$\dots$&|} (i.e., \GenCmdBox+|<code>|+) in general
% 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 (\lq`['<opt-arg>`]'\rq) 
or curly braces (\lq`{'<mand-arg>`}'\rq), 
where those pairs contain strings indicating the typical 
kinds of contents for the respective arguments of that command.
A typical example is this: 
\[\InlineCmdBox{&\foo*[<opt-arg>]{<mand-arg>}}\]
This was achieved by typing 
\[\HardVerbBox+&\foo*[<opt-arg>]{<mand-arg>}+\]
In ``auto mode" of the package, even typing 
\[\HardVerbBox+\foo*[<opt-arg>]{<mand-arg>}+\]
would have sufficed---\acro{WYSIWYG}! I call such mixtures of 
\emph{verbatim} and ``meta-variables" \textit{\qtd{meta-code}}.

Outside macro arguments, you obtain the same by typing 
% \[\verb+`\foo*[<opt-arg>]{<mand-arg>}'+\]
\[\HardVerbBox+`\foo*[<opt-arg>]{<mand-arg>}'+\]

Details:
\begin{description}

\item[``Meta-variables:"] The package supports the ``angle 
brackets" style of ``meta-variables" (as with <meta-variable>). 
You just type \lq\verb'<bar>'\rq\ to get \lq<bar>\rq.

This works due to a sloppy variant `\NVerb' 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.\footnote{On the other hand, &\NVerb is more 
  \emph{careful} with 'niceverb''s special characters.}
\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:"]
The package ``assumes" that \emph{quoting} refers to 
\emph{code}, therefore \lq\verb+`foo'+\rq\ is typeset as 
\lq`foo'\rq, or (generally) |`<content>'| turns <content> 
into meta-code with the meta-variable feature as above. 
This somewhat resembles the &\MakeShortVerb feature of 'doc.sty'.
%% Moved up here 2010/02/28:
You can ``abuse" our %%% ``single quotes" 
feature just to get typewriter 
typeface.{\sloppy\par}%% not so useful here 2010/02/28:
% \footnote{In macro arguments this requires that the right 
% single quote &' is &\active.}

Problems with this feature will typically arise %%% fail %% 2010/02/28
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 or so. %% TODO try! 2010/02/28
\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.\footnote{&\bar indeed!} 
More generally, the quoting feature still works in macro arguments in 
the sense that you then have to mark difficult characters with `&' 
(simply as short for `\string'). However, it still won't work with 
curly braces that don't follow a command name 
(such \emph{pairs} of braces will simply get lost, 
 \emph{single} braces will give errors or so).%%%\footnote{`{group}'}

Double quotes and apostrophes should still work the usual way.
% %% TODO doesn't work, inside runs into `}' 2010/02/28:
% otherwise you could control the parsing mechanisms using curly braces 
% (outside and inside don't interact: `Harry{'}s' for \qtd{Harry's}).
For difficult cases, you can still use the standard `\verb' 
command from \LaTeX.
To get \emph{usual} single quotes, you can use their standard substitutes 
`\lq' and `\rq', or for pairs of them, 
|\qtd{<text>}| in place of `\lq <text>\rq'---or even `\lq <text>\rq\ '. 
To get single quotes around some verbatim <verb>,
often `\qtd{&<verb>}' works. 
It is for this reason that I have refrained from different 
solutions as in \ctanpkgref{newverbs} (so far).

\item[Single right quotes for &\textsf:]
Package names are (by some convention I often yet not always 
 see working) 
typeset with `\textsf'; 
it was natural to use a remaining case of using single quotes 
for abbreviating $$&\textsf{<text>}$$ by |'<text>'|.
% \footnote{%
% Font switching by sequences of single quotes is a feature of the 
% syntax for editing \textit{Wikipedia} pages and of 'wiki.sty'.}
%% <- undoubled 2010/02/28 ->
This idea of switching fonts continues font switching of 'wiki.sty'
which uses the syntax for editing {\it Wikipedia} pages 
(font switching by sequences of right single quotes).

\item[Verticals for setting-off command descriptions:]%%%
\hskip0pt plus 2em
\GenCmdBox+|<code>|+ works like \qtd{&`<code>&'} except putting 
the result into a \emph{framed box} (just as all around 
here)---or something else that you can achieve using some \emph{hooks} 
described with the implementation. There are variants like 
\GenCmdBox+\cmdboxitem|<code>|+.

\item[Ampersand shows command syntax \&c. 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, in macro arguments this does not work with 
\emph{private letters} (`@' and `_' here), for this case, 
use |\cs{<characters>}| or |\cstx{<characters>}<parameters>|.%%%
% `&' 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.!}
%% <- said elsewhere now 2010/03/07

\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 `\MakeNormal\&' and turn the present special meaning on again by 
\[`\MakeActive\&' \mbox{\quad or\quad } 
  `\MakeActiveLet\&\CmdSyntaxVerb'\]
You could also 
redefine (&\renewcommand) &\descriptionlabel using `\CmdSyntaxVerb' 
(the ``normal command" that is equivalent to `&', its ``permanent 
 alias") 
so \verb+\item[\foo]+ works as wanted.
\end{sloppypar}

\textbf{Another} feature of 'niceverb''s `&' is getting 
(some of the) special characters    %% 2010/03/20
(as listed in the standard macro `\dospecials') verbatim in arguments 
(where `\verb' and the like fail). It just acts similarly as \TeX's 
    %% undoubled lines 2011/05/09
 primitive `\string' (which it actually invokes---cf. discussion on the 
 left quote feature above). 

\item[``Auto mode" typesets commands verbatim unless .\,.\,.]
\begin{sloppypar}
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, or add <macros> to it by
|\AddToNoVerbList}{<macros>}|                           %% 2010/12/29
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|.
|\AutoCmdInput{<file>}| is probably most important. 
\end{sloppypar}

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 \lq&#\rq\ comes verbatim.]
No macro definitions are expected in the `document' 
environment.\footnote{This idea appeared 2009 on the 'LATEX-L' 
                      mailing list. It may be wrong, 
                      as I have sometimes experienced $\dots$}
                      %% <- changed 2010/03/11
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\---\acro{WYSIWYG} 
indeed! (So the general syntax is |#<digit>|.)
\item[Escaping from 'niceverb' (generally).] 
     To get rid of the functionality of some active character <char> 
     (\qtd{&&}, single quote, ampersand, hash mark---not 
      ``auto mode," see above) here, use |\MakeNormal\<char>|---may 
     be within a group. To revive it again, use |\MakeActive\<char>|. 
     This may fail when a different package overtook the active <char> 
     (but I expect more failures then), in this case 
     |\MakeActiveLet\<char>\<perm-alias>| 
     revives the 'niceverb' meaning of <char>
     where `\<perm-alias>' is the ``permanent alias" for that active 
     <char> according to the documentation below. 
     E.g., `\LQverb' is the ``permanent alias" for active single left 
     quote, 'niceverb' activates it by 
     \NVerb+\MakeActiveLet\'\LQverb+.---You can turn off 'niceverb' 
     syntax \emph{alltogether} by |\noNiceVerb| and revive it 
     by |\useNiceVerb| (without ``auto mode").{\sloppy\par}

     \textbf{Right Quotes:} Disabling\slash reviving replacement 
     of `\textsf' by single right quotes requires 
     \[|\nvRightQuoteNormal| \mbox{\quad or\quad } |\nvRightQuoteSansSerif|\] 
     respectively.
\end{description}

\subsection{Examples}
The file 'mdoccorr.cfg' providing some `.txt'$\to$\LaTeX\ 
functionality---i.e., typographical corrections---documents itself 
using 'niceverb' syntax. Its code and the documentation that is 
typeset from it are in the \qtd{examples} section of 
'makedoc.pdf'.---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.{\sloppy\par}

'nicetext' bundle release v0.4 contains a file 'substr.tex' 
that should typeset the documentation of the version of 
Harald Harders'
'substr.sty'\footnote{\url{http://ctan.org/pkg/substr}}
that your \TeX\ finds first, as well as 'arseneau.tex' 
typesetting a few packages by Donald Arseneau. 
The outcomes (with me) are 'substr.pdf' and 'arseneau.pdf'.
These are the first applications of 'niceverb''s ``auto mode" to 
(unmodified) third-party package files.
(I also made a more ambitious documentation of Donald Arseneau's 
 'import.sty v3.0' before I found that CTAN already has a nicely 
 typeset documentation of 'import.sty v5.2'.)

%% removed 2010/03/11:
% 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. 
      %% 2010/02/28:
      Especially, the feature of \[\hbox\bgroup|''<text>''|\egroup\] 
      %% <- failed with \mbox as of 2010/03/23, first two rq missing 
      %%    2010/03/29
      replacing 
      `\textit{<text>}' or `\emph{<text>}' may be considered missing. 
\item Font switching or horizontal spacing may fail in certain 
      situations.
%       (parentheses, titles, footnotes; 
      You can correct spacing by \lq`\ '\rq. 
        %% <- \qtd{`&\ '}.
% \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 \qtd{&|} produces inline boxes 
      only at present. It might as well provide a version of the 
      `decl' tabular environment of 'ltxguide.cls'. 
%% changes 2010/03/10
%       coloured\slash framed boxes instead (2009/04/09). They have 
%       their merits! See 'fifinddo.pdf'  and 'makedoc.pdf'. However, 
%       they 
      The inline boxes
      badly deal with long command names and many arguments.
      Doubled verticals could ensure the `decl' mode. 
      Moreover, such a box might issue an \emph{index} entry.
\item One may have \emph{opposite} ideas about using quotes---maybe 
      rather `"<code>"' should typeset <code> \textit{verbatim}.
      There might be a package option for this. If ordinary 
      \qtd{\NVerb'``<text>"'} still should work, awful tricks as now with 
      the right quote feature would be needed. %% TODO 2010/03/06
% \item ``Auto mode" has \emph{not} been tested on a serious application yet. 
%% partially improved 2010/02/28:
% \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 
%       There
%       might better help with weird errors, 
%       some syntax checks might intercept earlier. 
% 
%       Similarly, some choices reflect a %% rather OK 2010/02/28
%       personal style and should be modifiable, especially by package 
%       options.\footnote{Please sponsor the project or support it 
%         otherwise!}
\item ``auto mode" seems not to work in section titles. (2011/01/26)
      %% <- noted with edtnotesc
\item Certain difficulties with typesetting code in macro arguments 
      may be overcome easily using $\varepsilon$\mbox{-}\TeX\ 
      features, I need to find out $\dots$
\end{enumerate}

\section{Implementation of the Markup Syntax}
\input{niceverb.doc}
\end{document}

HISTORY

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
2010/02/27  replaced `|' by `+' with \verb 
            so `|' works as announced
2010/02/28  "Missing:" ''...'' 'wiki' feature, 
            somethings aren't missing anymore 
            (or otherwise removed); more on quotes; 
            applying |...| 
2010/03/05  \SimpleVerb -> \NVerb; after intro on `&' quotes as well
2010/03/06  typo in ``examples''; removed makedoc.cfg sample; 
            more on `&'
2010/03/07  without \listfiles
2010/03/09  hyperref ... \input{mdcorr.cfg}!, |...| settled
2010/03/10  moved pdf stuff to 'makedoc.cfg'; 
            do use 'mdcorr.cfg' for demo; future of |
2010/03/11  applied \MakeJobDoc and shortened preamble; 
            various minor doc changes
2010/03/12  ``Ampersand" improved; \noNiceVerb + \useNiceVerb
2010/03/14  use \InlineCmdBox and \HardVerbBox; |...| described
2010/03/18  \AddToMacro; ``auto mode" tested seriously (substr.sty) 
            - \AutoCmdInput
2010/03/19  line break changes; '' -> " 
2010/03/20  testing niceverb v0.31
2010/03/23  `mdoccorr.cfg' example again
2010/03/27  ``auto mode,"
2010/03/29  \mbox -> \hbox in display; arseneau.tex/pdf
2010/04/05  Harder -> Harders
2010/11/27  \ProvidesFile for myfilist
2010/12/29  \AddToNoVerbList
2011/01/26  using color.sty and readprov.sty; 
            ack. Stephan B. for <...>; auto headings issue
2011/05/09  undoubled lines about `&'
2011/08/22  using new makedoc.cfg features 
2011/10/07  `syntacic'