summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/nicetext/docsrc/niceverb.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/nicetext/docsrc/niceverb.tex')
-rw-r--r--Master/texmf-dist/doc/latex/nicetext/docsrc/niceverb.tex453
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
-