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