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 | 453 |
1 files changed, 0 insertions, 453 deletions
diff --git a/Master/texmf-dist/doc/latex/nicetext/docsrc/niceverb.tex b/Master/texmf-dist/doc/latex/nicetext/docsrc/niceverb.tex deleted file mode 100644 index f4b380b985f..00000000000 --- a/Master/texmf-dist/doc/latex/nicetext/docsrc/niceverb.tex +++ /dev/null @@ -1,453 +0,0 @@ -\ProvidesFile{niceverb.tex}[2011/01/26 documenting niceverb.sty] -\title{\textsf{niceverb.sty}\\---\\Minimizing - Markup\\for Documenting \LaTeX\ packages\thanks{This - document describes version - \textcolor{blue}{\UseVersionOf{niceverb.sty}} - of \pkgnamefmt{niceverb.sty} as of \UseDateOf{niceverb.sty}.} -} -% \listfiles 2010/03/19 -{ \RequirePackage{makedoc} \ProcessLineMessage{} %% 2010/03/11 - \MakeJobDoc{19}{\SectionLevelThreeParseInput} } -\documentclass{article}%% TODO paper dimensions!? -\input{makedoc.cfg} %% shared formatting settings -\usepackage{color} -\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} -\emph{Four} %% 2011/01/26 -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. -\item %% 2011/01/26 -\lq\HardNVerb+<meta-variable>+\rq\ produces \lq<meta-variable>\rq. -(\qtd{&\lessthan} stores the original \qtd{&<}.) -\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\ '. -To get single quotes around some verbatim <verb>, -often `\qtd{&<verb>}' works. -It is for this reason that I have refrained from different -solutions as in \ctanpkgref{newverbs} (so far). - -\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 -|\AddToNoVerbList}{<macros>}| %% 2010/12/29 -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 Harders' -'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 ``auto mode" seems not to work in section titles. (2011/01/26) - %% <- noted with edtnotesc -\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 -2010/04/05 Harder -> Harders -2010/11/27 \ProvidesFile for myfilist -2010/12/29 \AddToNoVerbList -2011/01/26 using color.sty and readprov.sty; - ack. Stephan B. for <...>; auto headings issue - |