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

\typeout{niceverb.tex 2010/03/29 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.}%

}

% \listfiles 2010/03/19

{ \RequirePackage{makedoc} \ProcessLineMessage{} %% 2010/03/11

  \MakeJobDoc{19}{\SectionLevelThreeParseInput}  }

\documentclass{article}%% TODO paper dimensions!?

\input{makedoc.cfg} %% shared formatting settings

\begin{document}

\maketitle

\begin{abstract}\noindent

'niceverb.sty' provides very decent syntax (through active characters) 

for describing \LaTeX\ packages and the syntax of macros conforming to 

\LaTeX\ syntax conventions.

\end{abstract}

\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 WYSIWYG).\footnote{``What you see is what you 

  get." Novices are always warned that 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}

Three 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.

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



\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 

(as listed in the standard macro `\dospecials') verbatim in arguments 

(where `\verb' and the like fail). It just acts similarly as \TeX's 

 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

|\AddToMacro{\niceverbNoVerbList}{<macros>}|

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\---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 Harder's

'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 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