diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/nicetext/niceverb.tex')
| -rw-r--r-- | Master/texmf-dist/doc/latex/nicetext/niceverb.tex | 427 |
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 |