From ee53eac199e12fb91859fd18a43dd506ff75e3a9 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Mon, 20 Apr 2009 22:50:28 +0000 Subject: nicetext update (20apr09) git-svn-id: svn://tug.org/texlive/trunk@12766 c570f23f-e606-0410-a88d-b1316a301751 --- .../texmf-dist/source/latex/nicetext/niceverb.tex | 331 +++++++++++++++++++++ 1 file changed, 331 insertions(+) create mode 100644 Master/texmf-dist/source/latex/nicetext/niceverb.tex (limited to 'Master/texmf-dist/source/latex/nicetext/niceverb.tex') diff --git a/Master/texmf-dist/source/latex/nicetext/niceverb.tex b/Master/texmf-dist/source/latex/nicetext/niceverb.tex new file mode 100644 index 00000000000..629d240c458 --- /dev/null +++ b/Master/texmf-dist/source/latex/nicetext/niceverb.tex @@ -0,0 +1,331 @@ +\ProvidesFile{niceverb.tex}[2009/04/15 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.}% +} +\author{Uwe L\"uck\\{\tt http://contact-ednotes.sty.de.vu}} +\listfiles + \begingroup %% build niceverb.doc + \RequirePackage{makedoc} + \LaTeXresultFile{niceverb.doc} + \HeaderLines{19} + \MainDocParser{\SectionLevelTwoParseInput} + \MakeDoc{niceverb.sty} + \CloseResultFile + \endgroup +% \input{mknvdoc.tex} +\documentclass{article}%% TODO paper dimensions!? +\input{makedoc.cfg}\MakeOther\|%% TODO \verb| 2009/04/09 +%% removed 2009/04/09 for makedoc.sty: +% \usepackage{niceverb} +% \usepackage{moreverb} +% \usepackage{verbatim} +% \newenvironment{packagecode} +% {\PackageCode} +% {\endPackageCode} +% \gdef\PackageCode{\small \listing[5]{1}} +% \gdef\endPackageCode{% +% \endlisting +% \global\def\PackageCode{\small \listingcont}% +% \global\let\endPackageCode\endlistingcont} +% \renewcommand*{\listinglabel}[1]{% +% \llap{\footnotesize\rmfamily\the#1}\hskip\listingoffset\relax} + +\begin{document} +\maketitle + +\begin{abstract}\noindent\hspace{1sp}%% exemplifies a problem +'niceverb.sty' provides very decent syntax for describing \LaTeX\ +packages and the syntax of macros conforming to \LaTeX\ syntax +conventions. +\end{abstract} +\tableofcontents + + %% TODO table listing active characters +\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.} +% 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 (typically in a `.sty' file), you just ``{`latex'}'' the +manual file (maybe some `.tex' file) and get instantly the corresponding +refreshed 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 'lineno.sty' +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 them in the source). +\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'} + +Single quotes \verb|`|, \verb|'|, ``less than'' \verb|<| (accompanied +with \verb|>|), the hash mark \verb|#|, ampersand \verb|&|, and in an +extended ``auto mode'' even backslash \verb|\| become &\active +characters with ``special effects.'' \lq`|'\,.\,.\,.\,`|'\rq\ +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 (`['.\,.\,.`]') or +curly braces (\verb'{'.\,.\,.\verb'}'), +where those pairs contain strings indicating the typical +kinds of contents for the respective arguments of that command. +A typical example is this: +\[&\foo*[]{}\] +This was achieved by typing \[\verb'&\foo*[]{}'\] +In ``auto mode'' of the package, even typing +\[\verb|\foo*[]{}|\] + %% angle brackets feature to be suppressed here! +would have sufficed---WYSIWYG! (I call such mixtures of +\emph{verbatim} and ``meta-variables'' \textit{\lq meta-code\rq}.) + +Now for the details: +\begin{description} + +\item[``Meta-variables:''] {\sloppy The package supports the ``angle +brackets'' style of ``meta-variables'' (as with ). +You just type \lq\verb''\rq\ to get \lq\rq.\par} + +This works due to a sloppy variant &\SimpleVerb 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. \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:''] +{\sloppy The package ``assumes'' that \emph{quoting} refers to +\emph{code}, therefore \lq\verb|`foo'|\rq\ is typeset as +\lq`foo'\rq. This somewhat resembles the &\MakeShortVerb feature of +'doc.sty'.\par} + +It will typically fail 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 so. +\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. + +Double quotes and apostrophes should still work the usual way; +otherwise you could control the parsing mechanisms using curly braces +(outside and inside don't interact). +To get usual single quotes, you can use their standard substitutes +`\lq' and `\rq'. +You can ``abuse'' this ``single quotes'' feature just to get typewriter +typeface.\footnote{In macro arguments this requires that the right +single quote &' is &\active.} +For difficult cases, you can still use the standard `\verb' +command from \LaTeX. + +\item[Single right quotes for &\textsf:] +{\sloppy Package names are (by some unwritten convention!?) +typeset with `\textsf'; +it was natural to use a remaining case of using single quotes +for abbreviating &\textsf{} by \SimpleVerb|''|.\footnote{% +Font switching by sequences of single quotes is a feature of the +syntax for editing Wikipedia pages and of 'wiki.sty'.}\par} +%% TODO fails in parentheses due to preserving apostrophes + +This idea of switching fonts continues font switching of 'wiki.sty' +which uses the syntax for editing Wikipedia pages. + +\item[Ampersand \lq&&\rq\ typesets command syntax 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, `&' 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.!} + +\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 \verb|\MakeAlign\&| and turn the present special meaning on again by +$$\verb|\MakeActiveLet\&\CmdSyntaxVerb|.$$ +You could also +redefine (&\renewcommand) &\descriptionlabel using `\CmdSyntaxVerb' +(the ``normal command'' equivalent to `&') so \verb|\item[\foo]| works +as wanted. +\end{sloppypar} + +\item[``Auto mode'' typesets commands verbatim unless .\,.\,.] +{\sloppy +\hfil 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. +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.\par} + +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 &# comes verbatim.] +No macro definitions are expected in the `document' +environment.\footnote{This idea recently appeared on the 'latex-l' +mailing list. It may be wrong, not sure at the moment, think of +'latexa.ltx' .\,.\,.} +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!). +\end{description} + +\subsection{Examples} +The local configuration file 'mdcorr.cfg' documents itself using +'niceverb' syntax. Its code and the documentation that is typeset from +it are at the end of the \lq examples\rq\ section of 'makedoc.pdf'. +(2009/04/15) + +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. + +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. +\item Font switching or horizontal spacing may fail in certain situations + (parentheses, titles, footnotes; you can correct spacing by + \lq`\ '\rq). + %% TODO 2009/04/10 redefine \noindent, \footnote ... + %% or use correcting function with 'fifinddo' +% \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 \lq&|\rq\ was planned to be active + and provide a version of the `decl' environment of + 'ltxguide.cls'. Currently 'makedoc.cfg' installs inline, + coloured\slash framed boxes instead (2009/04/09). They have + their merits! See 'fifinddo.pdf' and 'makedoc.pdf'. However, + they badly deal with long command names and many arguments + .\,.\,. (They could also issue an `\index' command!)---Doubled + verticals could make the difference, calling a `decl' table + indeed. +\item ``Auto mode'' has not been tested on a serious application yet. +\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 might better help with weird errors, + some syntax checks might intercept earlier. + + Similarly, some choices reflect a + personal style and should be modifiable, especially by package + options.\footnote{Please sponsor the project or support it + otherwise!} +\end{enumerate} + +\pagebreak[3] %% 2009/04/15 +\section{Implementation of the Markup Syntax} +% \verbatiminput{niceverb.sty} +% \listinginput[5]{1}{niceverb.sty} +\input{niceverb.doc} + +%% removed 2009/04/09 for makedoc.sty: +% \section{Code Preparing Source for Typesetting} +% This is at present in a file `mknvdoc.tex'. +% \listinginput[5]{1}{mknvdoc} +\end{document} + +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 -- cgit v1.2.3