summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/nicetext/docsrc/niceverb.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/nicetext/docsrc/niceverb.tex')
-rw-r--r--Master/texmf-dist/doc/latex/nicetext/docsrc/niceverb.tex874
1 files changed, 874 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/nicetext/docsrc/niceverb.tex b/Master/texmf-dist/doc/latex/nicetext/docsrc/niceverb.tex
new file mode 100644
index 00000000000..0bcddd9ae04
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/nicetext/docsrc/niceverb.tex
@@ -0,0 +1,874 @@
+\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
+