\ProvidesFile{niceverb.tex}[2014/03/28 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[fleqn]{article}%% TODO paper dimensions!? \input{makedoc.cfg} %% shared formatting settings \newcommand*{\secref}[1]{Sec.~\ref{sec:#1}} %% 2014/03/27 %% 2011/08/22: \MDkeywords{literate programming, syntactic sugar, .txt to .tex enhancement, macro programming} \hypersetup{%% was `syntacic' 2011/10/07: % pdftitle=syntactic sugar for LaTeX documentation by niceverb.sty, %% <- 2011/11/05 -> pdftitle=niceverb.sty: syntactic sugar for LaTeX documentation, pdfsubject=documenting niceverb.sty }%% /2011/08/22 \begin{document} \maketitle \begin{MDabstract} % \tracingmacros=1 \tracingonline=1 'niceverb.sty' provides very decent syntax (through active characters) for describing \LaTeX\ packages and the syntax of macros conforming to \LaTeX\ syntax conventions. \end{MDabstract} \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 \acro{WYSIWYG}).\footnote{``What you see is what you get." Novices are always warned that \acro{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 %% 2010/02/28: (typically in a `.sty' file---`.sty'), you just ``{`latex'}" the manual file (maybe some `.tex' file---`.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++\rq\ produces \lq\rq. (\qtd{&\lt} stores the original \qtd{&<}.) %% was \lessthan 2014/03/28 \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+||+) 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`['`]'\rq) or curly braces (\lq`{'`}'\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*[]{}}\] This was achieved by typing \[\HardVerbBox+&\foo*[]{}+\] In ``auto mode" of the package, even typing % \tracingmacros=1 \tracingonline=1 \[\HardVerbBox+\foo*[]{}+\] would have sufficed---\acro{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*[]{}'+\] \[\HardVerbBox+`\foo*[]{}'+\] Details: \begin{description} \item[``Meta-variables:"] The package supports the ``angle brackets" style of ``meta-variables" (as with ). You just type \lq\verb''\rq\ to get \lq\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++'\rq, by contrast, just yields \lq\verb''\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) |`'| turns 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}) 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{}| in place of `\lq \rq'---or even `\lq \rq\ '. To get single quotes around some verbatim , often `\qtd{&}' works. It is for this reason that I have refrained from different solutions as in \ctanpkgref{newverbs} (so far). %% 2012/10/10: v0.44 provides |\AddQuotes| after which single quotes \emph{both} turn their content into metacode \emph{and print} single quotes around them \emph{automatically.} This can be turned off again by |\DontAddQuotes|. \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{}$$ by |''|. % \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+||+ works like \qtd{&`&'} 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||+. \item[Ampersand shows command syntax \&c. even in arguments:] \hfil E.g., type \lq\verb+&\foo{}+\rq\ to get \lq`\foo{}'\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{}| or |\cstx{}|.%%% % `&' 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 %% undoubled lines 2011/05/09 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 to it by |\AddToNoVerbList}{}| %% 2010/12/29 There is also a command |\NormalCommand{}| \emph{issuing} the command `\' 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{}| 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\---\acro{WYSIWYG} indeed! (So the general syntax is |#|.) \item[Escaping from 'niceverb' (generally).] To get rid of the functionality of some active character (\qtd{&&}, single quote, ampersand, hash mark---not ``auto mode," see above) here, use |\MakeNormal\|---may be within a group. To revive it again, use |\MakeActive\|. This may fail when a different package overtook the active (but I expect more failures then), in this case |\MakeActiveLet\\| revives the 'niceverb' meaning of where `\' is the ``permanent alias" for that active 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} \strong{Right Quotes:} Disabling\slash reviving replacement of `\textsf' by single right quotes requires \[|\nvRightQuoteNormal| \mbox{\quad or\quad } |\nvRightQuoteSansSerif|\] %% 2014/03/27: respectively.---The feature fails in certain occasions because a single right quote must not always be interpreted as `\textsf', and deciding this by macros became quite laborious for me and is most likely still not perfect. There is a command |\nvAllRightQuotesSansSerif| to be used with care that interpretes \emph{all} single right quotes as `\textsf', which, e.g., means that you must use `\rq' for apostrophes. \strong{``Moving" arguments:} %% 2014/03/27 |\NiceVerbMove{}| with v0.6 is for ``moving" arguments so that 'niceverb' syntax operates \emph{locally} at the destination (table of contents or page headings). It is automatically used by 'niceverb''s variant of \LaTeX's sectioning commands; while with `\markboth', `\markright', `\addcontentsline' etc.\ you must it include yourself (currently, \TODO?). \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|''''|\egroup\] %% <- failed with \mbox as of 2010/03/23, first two rq missing %% 2010/03/29 replacing `\textit{}' or `\emph{}' 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 `""' should typeset \textit{verbatim}. There might be a package option for this. If ordinary \qtd{\NVerb'``"'} 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} \newpage %% 2014/03/28 \section{The Package File} %% 2014/03/19 % \section{The ``Package" File} %% test for page heading 2014/03/24 % \section{`nicetext.sty'} %% tests for pageheadings 2014/03/27 \subsection{Preliminaries} %% 2014/03/19 \subsubsection{File Header} %% 2014/03/19 \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 2011/05/09 undoubled lines about `&' 2011/08/22 using new makedoc.cfg features 2011/10/07 `syntacic' 2011/11/05 modified pdftitle 2012/10/10 \AddQuotes, \DontAddQuotes FOR V0.6: 2014/03/19 subsec. Preliminaries, subsubsec. Header, `Implementation of the Markup Syntax' -> `The Package File' 2014/03/24 experiment with former 2014/03/25 debugging in abstract 2014/03/26 trying class option `fleqn' / debugging again 2014/03/27 \secref; |\NiceVerbMove|, |\nvAllRightQuotesSansSerif|; tests 2014/03/28 debugging; \lessthan -> \lt; \newpage