summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/nicetext/niceverb.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/nicetext/niceverb.tex')
-rw-r--r--Master/texmf-dist/doc/latex/nicetext/niceverb.tex427
1 files changed, 427 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/nicetext/niceverb.tex b/Master/texmf-dist/doc/latex/nicetext/niceverb.tex
new file mode 100644
index 00000000000..b1c1addef88
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/nicetext/niceverb.tex
@@ -0,0 +1,427 @@
+\typeout{niceverb.tex 2010/03/23 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.3 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. This is the first application of
+'niceverb''s ``auto mode" to a third-party package
+(without manual modification).
+
+%% 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 $$\mbox{|''<text>''|}$$ 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