summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/nicetext/docsrc
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2010-04-03 15:42:12 +0000
committerKarl Berry <karl@freefriends.org>2010-04-03 15:42:12 +0000
commit14b154c49df4af70e973eeafb54e2f31250aff0e (patch)
tree3d16bd3f92c8dd87c3475e212fca73e37ce370d7 /Master/texmf-dist/doc/latex/nicetext/docsrc
parent2a8bfdf220d7f65a85d288b2edef58e46dd9f654 (diff)
nicetext 0.4 (30mar10)
git-svn-id: svn://tug.org/texlive/trunk@17661 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/nicetext/docsrc')
-rw-r--r--Master/texmf-dist/doc/latex/nicetext/docsrc/fifinddo.tex650
-rw-r--r--Master/texmf-dist/doc/latex/nicetext/docsrc/makedoc.cfg58
-rw-r--r--Master/texmf-dist/doc/latex/nicetext/docsrc/makedoc.tex1286
-rw-r--r--Master/texmf-dist/doc/latex/nicetext/docsrc/mdoccheat.tex208
-rw-r--r--Master/texmf-dist/doc/latex/nicetext/docsrc/niceverb.tex874
-rw-r--r--Master/texmf-dist/doc/latex/nicetext/docsrc/wikicheat.tex296
6 files changed, 3372 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/nicetext/docsrc/fifinddo.tex b/Master/texmf-dist/doc/latex/nicetext/docsrc/fifinddo.tex
new file mode 100644
index 00000000000..59484968382
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/nicetext/docsrc/fifinddo.tex
@@ -0,0 +1,650 @@
+\ProvidesFile{fifinddo.tex}[2010/03/23 documentation for `fifinddo']
+
+\title{\textsf{fifinddo}\\---\\Filtering \TeX(t) Files by \TeX}
+
+\author{Uwe L\"uck\,---\,{\tt http://contact-ednotes.sty.de.vu}}
+
+% \listfiles
+
+\documentclass{article}
+
+\usepackage{makedoc}
+
+% \usepackage{substr} %% for failure examples TODO 2010/03/17
+
+\input{makedoc.cfg}
+
+\begin{document}
+
+\maketitle
+
+
+
+\begin{flushright}\small\it FIDO, FIND!\\or:\\FIND FIDO!\\oder:\\FIFI,
+
+ SUCH!\end{flushright}
+
+\begin{abstract}\noindent\hspace{1sp}%% for niceverb-apostrophe
+
+'fifinddo' starts implementing parsing of plain text or \TeX\ files
+
+using \TeX, generalizing the philosophy behind 'docstrip',
+
+based on how \TeX\ reads macro arguments.
+
+Rather than typsetting the edited input stream immediately,
+
+results are written to another file,
+
+in the first instance as input for \TeX.
+
+Rather than presenting a ``complete study" of a computer-scientific
+
+idea, it aims at practical applications.
+
+The main one at present is '\mbox{makedoc}' which removes certain comment
+
+marks from package files and inserts listing commands.
+
+Parsing macros are not defined anew at every input chunk,
+
+but once before a file is processed.
+
+This also allows for \emph{expandable} sequences of replacements,
+
+e.g., with `txt'$\to$\TeX\ functionality.
+
+The method of testing for substrings is carefully discussed,
+
+revealing an earlier mistake (then) shared with 'substr.sty'
+
+and \LaTeX's internal `\in@'.
+
+\end{abstract}
+
+\tableofcontents
+
+
+
+\section{Introduction: The Gnome of the Aim}
+
+\subsection{Parsing by \TeX---are you mad?}
+
+The package name 'fifinddo' is a &\listfiles-compatible abbreviation
+
+of \lq file-find-do\rq\footnote{\lq file\rq\ possibly for ``searching
+
+ \TeX(t) files" (I don't remember my thoughts!),
+
+ while there were requests for doing replacements on
+
+ \LaTeX\ \emph{environments} on 'texhax'. However, the package might
+
+ be enhanced in this direction $\dots$ so the name may be wrong
+
+ $\dots$ but now I like it so much .\,.\,. Or the reason was that
+
+ results are written to a \emph{separate file}, not typeset
+
+ immediately.---Let me also mention that \emph{\lq Fifi\rq} (as the
+
+ package name starts) is a kind of German equivalent to the
+
+ ``English" \emph{\lq Fido\rq}, or may have been.}
+
+(or think of \lq if found do\rq).
+
+'fifinddo' implements (or aims at) general parsing
+
+(extracting, replacing [converting], expanding, \dots)
+
+using \TeX\ where 'texhax' posters strongly urge to use 'sed',
+
+'awk', or 'Perl'.
+
+'fifinddo''s opposed rationales are:
+
+\begin{itemize}
+
+\item It works instantly on any \TeX\ installation.
+
+ (\emph{Restrictions:} Some \TeX\ versions &\write certain hex
+
+ codes for certain characters, cf.\ \TeX book p.~45,
+
+ I have seen this with PC\TeX. However, some applications of
+
+ 'fifinddo' are nothing but technical steps where you will read
+
+ the result files rarely anyway.
+
+ %% And I have not yet explored extended encodings.)
+
+ %% <- done meanwhile 2010/03/22
+
+\item You can apply and customize it like any \TeX\ macros, knowing
+
+ just \TeX\ (or even only the documentation of some user-friendly
+
+ extension of 'fifinddo'), without the need of learning any
+
+ additional script language.
+
+\item The syntax of usual utilities (e.g., ``wildcards")
+
+ is sometimes difficult with \emph{\TeX} files
+
+ with all their backslashes, square brackets, stars,
+
+ question marks \dots
+
+\end{itemize}
+
+%
+
+At least the first item is just the philosophy of the 'docstrip' program,
+
+standard for installing \TeX\ packages;
+
+and while I am typing this, I find at least 14 other similar packages
+
+in J\"urgen Fenn's \emph{Topic Index} of the \emph{\TeX\ Catalogue:}
+
+% \begin{quote}\small
+
+\[\texttt{%
+
+% \hbox\bgroup\url{% %% \url impossible!? 2010/03/19
+
+ http://mirror.ctan.org/help/Catalogue/bytopic.html\string#parsingfiles}%
+
+ \footnotemark
+
+% \egroup\]
+
+\]
+
+\footnotetext{%
+
+ \href{http://mirror.ctan.org/help/Catalogue/bytopic.html\string#parsingfiles}%
+
+ {Click here!}}
+
+% \end{quote}
+
+(Some of them may have been \emph{reactance} to 'texhax' and other
+
+postings urging not to try something like this; some seem just to be
+
+celebrations of the power of \TeX---yes, celebrate!)
+
+
+
+Actually, \TeX's mechanism of collecting macro arguments is hard-wired
+
+parsing at quite a high level. \LaTeX\ hides this from
+
+``simple-minded" users by a convention \emph{not} to use that full
+
+power of \TeX\ for \emph{end-user macros}.
+
+\emph{Internally}, \LaTeX\ \emph{does} use it in reading
+
+lists of options and file dates as well as to implement certain
+
+`FOR'- and `WHILE'-like loop programming structures.
+
+\LaTeX's `\in@'/`\ifin@' construction is an implementation of a
+
+``<string1> occurs in <string2>" test. More packages seem to use
+
+this idea for extracting file informations, like
+
+'texshade'.\footnote{\url{http://ctan.org/pkg/texshade}}
+
+
+
+
+
+However, such packages don't make much ado about parsing,
+
+there seems to be no general setup mechanism as are presented by
+
+'fifinddo'. Indeed, tayloring parsing macros to specific applications
+
+may often be more efficient than a general approach.
+
+
+
+\subsection{Useful for \dots}
+
+My main application of 'fifinddo' at present is typesetting
+
+documentations of packages using 'makedoc' which removes certain
+
+percent marks and inserts listing commands, so you edit a package file
+
+with as little documentation markup as possible.
+
+This may be extended to other kinds of documents as an alternative
+
+to 'easylatex' or 'wiki' (the approach of which is dangerous and
+
+incompatible with certain other things).
+
+
+
+I have used a similar own package 'txtproc' successfully,
+
+where more features were implemented for practical purposes
+
+than are here so far, yet I don't like its implementation, want to
+
+improve it here. This package also \emph{created batch files}, e.g.,
+
+to remove temporary files.
+
+This could be used for package handling:
+
+typset the documentation at the desired place in the tree,
+
+write the packages to another, write a batch file to remove
+
+files that are not needed any more after installation
+
+(cf.\ 'make'). %%% !? cf. Wiki `Make (software) 2009/04/11
+
+
+
+I used 'txtproc' also for \emph{large-scale substitutions}
+
+(it had been decided to change the orthography in a part of a book).
+
+Other large-scale substitutions may be:
+
+\begin{itemize}
+
+\item inserting &\index commands;
+
+\item inserting (soft) hyphenation commands near accents;
+
+\item manual umlaut-conversion.\footnote{If you know the ``names"
+
+ of the encodings, Heiko Oberdiek's
+
+ \ctanpkgref{stringenc}
+
+ may be preferable.}
+
+\item typographical (or even orthographical) corrections (same mistake
+
+ many times on each of hundreds of pages).
+
+ You may turn `...' into `$\dots$' and `etc.' into `etc.\'
+
+ etc.\footnote{But what when a new sentence is starting indeed?
+
+ Well, `cf.' is an easier example.---`etc.' even showed
+
+ a problem in 'niceverb'. 'mdoccorr.cfg' replaces `etc. '
+
+ only, so you can keep the extra space by a code line break.}
+
+ This could replace packages like
+
+ 'easylatex',\footnote{\url{http://ctan.org/pkg/easylatex}}
+
+ 'txt2latex',\footnote{\url{http://ctan.org/pkg/txt2latex}}
+
+ 'txt2tex'\footnote{\url{http://ctan.org/pkg/txt2tex}}
+
+ in a customizable way, using, e.g., the ``correct"
+
+ hook from 'makedoc.sty' as exemplified in 'mdoccorr.cfg'
+
+ (see examples section of 'makedoc.pdf').
+
+ You should find 'fdtxttex.tpl', a 'fifinddo' script
+
+ to try or apply `\MakeDocCorrectHook' from 'mdoccorr.cfg',
+
+ as well as 'fdtxttex.tex' that runs a dialogue for the
+
+ same purpose if you can manage to run it ('WinShell'?).
+
+ You can then try to create your own `\MakeDocCorrectHook'.
+
+ Section~\ref{sec:replchain} provides setup for macros
+
+ of this kind.
+
+\item as to 'easylatex' again, \emph{lists} could be detected and
+
+ transformed into \LaTeX\ list commands. This could re-implement
+
+ the lists functionality of 'wiki.sty' that is somewhat
+
+ dangerous. %% TODO 2009/04/15
+
+\item introduce your own \emph{shorthands} to be expanded not as \TeX\ macros,
+
+ but by text substitution;
+
+\end{itemize}
+
+%% % <- TODO present macros/"jobs" doing this.
+
+%% %% <- TOOD single quote tests could be used for
+
+%% double quote character as well
+
+%% to turn it into left quotes if ... 2010/03/19
+
+%
+
+In certain cases, insertions deteriorate readability, hyphenation
+
+corrections even make text search difficult.
+
+It is therefore suggested to
+
+\begin{enumerate}
+
+\item keep editing the file without the insertions,
+
+\item run the script (commands based on 'fifinddo') for insertions
+
+ in the preamble of the main file
+
+ (```\jobname.tex'", maybe &\input the script file) and
+
+\item &\input the result file within the `document' environment.
+
+\end{enumerate}
+
+
+
+In general, differences to ``manual" replacing by the substitution
+
+function of your \emph{text editor} is that
+
+\begin{itemize}
+
+\item you first keep the original version,
+
+\item you can check the resulting file before you replace the original
+
+ file by it,
+
+\item you can store the replacement script in order to check for
+
+ mistakes at a later stage of your work,
+
+\item you can do \emph{all} the replacements in \emph{one run}
+
+ (by \emph{one} script to check for mistakes),
+
+\item you can store replacement scripts for future applications,
+
+ so you needn't type the patterns and replacement strings anew.
+
+\end{itemize}
+
+
+
+
+
+\subsubsection{Comparisons} %% was `Missing' 2010/03/18
+
+% \subsection{To implement or not to implement \dots} %% TODO!? 2009/04/13
+
+% Actually, 'fifinddo' doesn't implement very much, and this possibly
+
+% won't change, even if I am lucky. ``Practical applications" tend to
+
+% show (in my view) that there is a very complex space of possibilities
+
+% what parsing macros could do. If I try to ``attack" 'Perl' or so,
+
+% cf.\ 'CPAN'\@. If I am lucky and become famous, 'fifinddo' will get many
+
+% extensions in separate packages, cf.\ 'pstricks'. I also like it when
+
+% you can choose among packages for similar purposes, and this may apply
+
+% to extensions of 'fifinddo' as well.
+
+%
+
+% What \emph{really} is missing very badly at present is matching
+
+% \emph{sequences} of strings. However, 'makedoc' contains a practical
+
+% application of this for the case that both strings appear \emph{in the same
+
+% line}. A better algorithm would have to read more lines from the input
+
+% file etc.
+
+%
+
+% As it just comes to my frightened mind, there is even a problem with
+
+% ``strings"/``patterns" that are \emph{phrases} of words, containing
+
+% spaces \dots
+
+%
+
+% Clearly much comfort concerning \emph{routine} jobs is missing now,
+
+% 'txtproc' has more. Please sponsor (or otherwise support) the work for
+
+% improving this.
+
+%
+
+It should be noted (perhaps here) that the present approach to parsing
+
+is a quite \emph{simple} one and in this respect much different to the
+
+string handling mechanisms of
+
+'stringstrings',\footnote{\url{http://ctan.org/pkg/stringstrings}}
+
+'ted',\footnote{\url{http://ctan.org/pkg/ted}}
+
+'xstrings'\footnote{\url{http://ctan.org/pkg/xstrings}}
+
+(as I understand them, perhaps also
+
+'coolstr'\footnote{\url{http://ctan.org/pkg/coolstr}})
+
+which are \emph{much more powerful} than what is offered here---but
+
+perhaps slow and for practical applications possibly replaceable by
+
+the present approach.
+
+\emph{Expandable replacement} seems not to exist outside 'fifinddo'
+
+(2009/04/13).
+
+
+
+Much is missing, I know.\footnote{There
+
+ is more in my badly implemented 'txtproc.sty'.}
+
+I am just implementing what I actually need
+
+and what could show that this approach is worth being pursued.
+
+ %% removed 2010/03/18:
+
+% It may need being sponsored or otherwise supported.
+
+
+
+\subsection{For insiders}
+
+
+
+\emph{Warning:} You may (at least at the present state of the work)
+
+have little success with this package, if you don't know about
+
+\TeX's category codes and how \TeX\ macros are defined.
+
+The package rather provides tools for package writers.
+
+You may, however, be able to run other packages which just load
+
+'fifinddo' as required background.
+
+
+
+That 'fifinddo' acts on ``\TeX(t)" files or so means that
+
+(at present) I think of applications on ``plain text" files which
+
+will usually be \TeX\ input files. ``At present" they are read
+
+without ``special characters," so essentially category codes of input
+
+characters are either 11 (``letter") or 12 (``other").
+
+This way some things are easier than with usual \TeX\ applications:
+
+\begin{enumerate}
+
+\item You can ``look into" curly braces and ``behind" comment characters.
+
+\item There are exact or safe tests especially of \emph{empty macro arguments}
+
+ that are ``expandable," i.e., they are ``robust,"
+
+ don't need assignments, can be executed in `\write'ing and in
+
+ `\edef' definitions. ``Usually," the safe way to test emptiness
+
+ is storing a macro argument as a macro, say `\tempo', in order
+
+ to test `\ifx\tempo\empty' where `\empty' has been defined
+
+ by `\def\empty{}' in the format. But this requires some
+
+ `\def\tempo{#<n>}' which breaks in ``mere expanding"
+
+ (\TeX\ \emph{evaluates} `\tempo' instead of defining it).
+
+ An \emph{expandable} test on emptiness is, e.g. `\ifx$#<n>$',
+
+ where we hope that it becomes `\iftrue' just if macro argument
+
+ `#<n>' is empty indeed. However, ``usually" it may \emph{also}
+
+ become `\iftrue' when `#<n>' starts with `$'---if the latter
+
+ has category code 3 (``math shift"). But 'fifinddo' does
+
+ not assign category code 3 to any character from the input file!
+
+ Therefore `\ifx$#<n>$' is `\iftrue' \emph{exactly} if `#<n>' is
+
+ empty.
+
+\item You can avoid interference with packages that are needed for
+
+ typesetting. You can do the ``preprocessing" in one run with
+
+ typesetting, but you should do the preprocessing before you
+
+ load packages needed for typesetting. One may even try to keep
+
+ the macros and settings for preprocessing local to a group.
+
+\end{enumerate}
+
+%
+
+Once there may be an option to read input with some usual \TeX\
+
+category codes as well, it may be useful to (some of)
+
+\begin{itemize}
+
+\item avoid matching substrings of control words,
+
+\item skip blank spaces as \TeX\ does it usually,
+
+\item catch \emph{balanced} input pieces,
+
+\item ignore comments,
+
+\item ignore certain characters.
+
+\end{itemize}
+
+
+
+The essential approach of 'fifinddo' to looking for single strings is
+
+described in some detail in section~\ref{sec:theory}.
+
+
+
+The implementation of 'fifinddo' is as follows.
+
+User commands are specially highlighted (boxed\slash coloured),
+
+together with their syntax description.
+
+
+
+% \end{document}
+
+
+
+\section{Preliminaries}
+
+\subsection{Head of file (Legalese)}
+
+\sloppy
+
+\ProcessLineMessage{}
+
+\MakeInputJobDoc{23}{\SectionLevelTwoParseInput}
+
+\end{document}
+
+
+
+TODO cf. Kastrup 'makematch' and others 2009/04/09
+
+
+
+2009/04/10: title break, by -> with(!?); `boxed/coloured'
+
+2009/04/12: useful: own shorthands
+
+2009/04/13: substr.sty, \emph{expandable}, w/o `implement'!?
+
+2009/04/15: same with \in@
+
+2010/03/08: EPS application removed
+
+2010/03/17: use \MakeInputJobDoc
+
+2010/03/18: `Missing' -> `Comparisons' etc.; \Require...
+
+2010/03/19: Catalogue \url; '' -> "
+
+2010/03/20: \ctanpkgref
+
+2010/03/22: debugging; done ...
+
+2010/03/23: more URLs; abstract "then shared";
+
+ removed dates from 2009, fdtxttex.tex/tpl
+
diff --git a/Master/texmf-dist/doc/latex/nicetext/docsrc/makedoc.cfg b/Master/texmf-dist/doc/latex/nicetext/docsrc/makedoc.cfg
new file mode 100644
index 00000000000..cd488b9b482
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/nicetext/docsrc/makedoc.cfg
@@ -0,0 +1,58 @@
+\ProvidesFile{makedoc.cfg}[2010/03/20
+
+ doc formatting settings]
+
+
+
+\RequirePackage{ifpdf}
+
+\ifpdf
+
+% \usepackage[bookmarksnumbered]{hyperref}
+
+% \usepackage[bookmarks=false]{hyperref}
+
+% \usepackage[bookmarks=false,pdfstartview=FitH]{hyperref}
+
+ %% <- 2010/03/12 ->
+
+ \usepackage[bookmarksnumbered,pdfstartview=FitH]{hyperref}
+
+% \usepackage[pdfpagemode=UseNone]{hyperref}
+
+\else
+
+ \usepackage[draft]{hyperref}
+
+ %% <- 2010/03/11 ->
+
+% \let\url\texttt \def\href#1#2{#2} %% \@secondoftwo
+
+\fi
+
+\author{Uwe L\"uck\thanks{\url{http://contact-ednotes.sty.de.vu}}}
+
+% \author{Uwe L\"uck---{\tt http://contact-ednotes.sty.de.vu}}
+
+
+
+\RequirePackage{niceverb}[2010/03/10]
+
+%% <- TODO move!? (\DeclareRobust...) ->
+
+\providecommand*{\ctanpkgref}[1]
+
+ {\href{http://ctan.org/pkg/#1}{\textsf{#1}}}
+
+
+
+\errorcontextlines=4
+
+\pagestyle{headings}
+
+
+
+\endinput
+
+
+
diff --git a/Master/texmf-dist/doc/latex/nicetext/docsrc/makedoc.tex b/Master/texmf-dist/doc/latex/nicetext/docsrc/makedoc.tex
new file mode 100644
index 00000000000..2007e41d3ac
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/nicetext/docsrc/makedoc.tex
@@ -0,0 +1,1286 @@
+\typeout{makedoc.tex 2010/03/30 documentation for `makedoc.sty'}
+
+\listfiles
+
+\RequirePackage{makedoc}
+
+\documentclass{article}
+
+\input{makedoc.cfg} %% with pdf stuff and 'niceverb'
+
+%% removed for niceverb v0.31 TODO!? 2010/03/20:
+
+\sfcode`/=1001 %% TODO makedoc.cfg!? 2010/03/21
+
+% \makeatletter %% TEST for hyperref compatibility 2010/03/11
+
+% \def\@testdef #1#2#3{%
+
+% \def\reserved@a{#3}%
+
+% \expandafter \ifx \csname #1@#2\endcsname
+
+% \reserved@a \else \@tempswatrue \fi
+
+% \if@tempswa
+
+% \typeout{^^J*** Type `r' <input> to get around
+
+% \string\label\space issues! ***^^J}
+
+% \errorcontextlines=0
+
+% \show\reserved@a
+
+% \expandafter \show \csname #1@#2\endcsname
+
+% \fi
+
+% }
+
+% \makeatother
+
+\begin{document}
+
+\title{'makedoc'---Preprocessing documentation by \TeX}
+
+ %% 2009/04/10: \\---\\\ breaks TOC
+
+\maketitle
+
+\begin{abstract}\noindent
+
+'makedoc' provides commands for generating \LaTeX\ input from a
+
+package file in order to typeset the latter's documentation
+
+(somewhat similar and opposite to 'docstrip')---with
+
+v0.3 \emph{a single one usually suffices}.
+
+Certain comment marks are removed, listing commands are inserted,
+
+and some (configurable) typographical `txt'$\to$\TeX\ corrections
+
+are applied.---This
+
+continues the policy of 'niceverb' to minimize documentation markup in
+
+package files. 'makedoc' extends and exemplifies the parsing package
+
+'fifinddo'. After an edit (and test) of your package, you get the new
+
+documentation in one run (or the usual number of runs) of the
+
+documentation driver file.---The present approach is meant to be an
+
+\emph{alternative} to the standard 'doc' package and its `\DocInput'.
+
+It provides \emph{less} than 'doc' does, rather deliberately. It may
+
+be helpful at least for the development of small packages, or at least
+
+at early stages.
+
+\end{abstract}
+
+\tableofcontents
+
+\section{Introduction}
+
+\emph{The abstract will not be repeated in this section.} Let me add
+
+instead that I was in dire need of such a package, I got stuck with my
+
+packages because I lost orientation in them, and I was unhappy with
+
+the forms of documentations of my other packages, and documenting them
+
+with the standard \LaTeX\ 'doc' system was not attractive for me
+
+(neither considered helpful). %% clarified 2010/03/13
+
+I also worked on \emph{Windows} until September 2008, and I
+
+find a system like the present one still more attractive then using
+
+(learning!\@) other filtering utilities (see below on 'awk'). And I
+
+may work on \emph{Windows} once again and don't want to depend on
+
+installing some $\dots$ there---\emph{I really would like to have
+
+powerful tools for everything depending on nothing but \TeX\slash
+
+\LaTeX!}
+
+
+
+\section{Prior work and what is new}
+
+It is, of course, not a new idea to get around comment marks `%' to
+
+typeset the documentation. 'doc''s `\DocInput' does this by making `%'
+
+an ``ignored" character. This way you cannot use `%' for commenting
+
+comments (so 'doc' offers a ``new comment mark"
+
+`^'`^'`A'). %% TODO `^^A' suddenly failed 2010/03/15 -- "ligature"!?
+
+You also cannot use `%' for commenting out code (that you are
+
+pondering---or using for debugging---only). %% clarified 2010/03/13
+
+
+
+Moreover, 'doc' requires enclosing package code explicitly by
+
+environment commands (behind comment marks). Stephan I. B\"ottcher
+
+with his '\href{http://ctan.org/pkg/lineno}{lineno.sty}'
+
+and Grzegorz Murzynowski in \ctanpkgref{gmdoc}
+
+aimed at doing away with this requirement.
+
+'lineno.sty' contains 'awk' scripts
+
+to remove starting comment marks and to insert listing commands.
+
+A file 'lineno.tex' is generated that typesets the documentation.
+
+By the way, 'lineno.sty' is full of discussions, but it is not
+
+'docstrip'ped---the maintainers never have received a complaint
+
+that inputting 'lineno.sty' were too slow.
+
+
+
+'gmdoc' seems to get around comment marks and insert listing commands
+
+\emph{while typesetting} by a refined version of `\DocInput',
+
+through some careful detecting and analysing comment marks,
+
+the approach resembles detection of lists in 'wiki.sty'.\footnote{See
+
+ 'gmdoc.pdf' on &\DocInput. You can learn a lot from this 220 pages
+
+ document! I also find
+
+ \ctanpkgref{pauldoc} and \ctanpkgref{xdoc} inspiring.}
+
+And this is a matter of principles---comparing the approaches of
+
+\emph{preprocessing} ('lineno.sty') and \emph{``smart typesetting"}
+
+('gmdoc', 'wiki'). Sometimes preprocessing seems to be simpler,
+
+sometimes detecting while typesetting.
+
+(Another example is the preprocessor
+
+\ctanpkgref{easylatex}
+
+of which 'wiki.sty' is a much reduced ``while typesetting" variant.)
+
+``While typesetting" may be easier when single characters or
+
+sequences of two or three encode markup
+
+information---but such detection can badly interfere with other
+
+packages etc. ``Preprocessing" may be easier when entire ``strings"
+
+of characters decide, which may be anywhere in a file line.
+
+
+
+'makedoc' chooses \emph{preprocessing}, as 'lineno.sty', but by
+
+\emph{\TeX}. There is a general discussion of this choice in the
+
+documentation of 'fifinddo'. Preprocessing here can be done in the
+
+same \LaTeX\ run as typesetting, though you can avoid
+
+incompatabilities with packages needed for typesetting
+
+(by inputting them only \emph{after} preprocessing).
+
+
+
+'lineno.sty' exemplifies why preprocessing with \emph{\TeX} may be
+
+preferable to preprocessing with other utilities:
+
+When I took over maintenance of 'lineno.sty',
+
+I needed hard work to get the 'awk' script running.
+
+The \emph{Munich} 'awk' seemed \emph{not} to behave as the \emph{Kiel}
+
+'awk' (I chose a Munich 'nawk' and reworked the script a little).
+
+\TeX\ seems to have better fixed functionality than other utilities!
+
+
+
+A different alternative to \LaTeX's 'doc' system is
+
+Paul Isambert's '\href{http://ctan.org/pkg/codedoc}{CodeDoc}'
+
+where the code environments extract package code in typesetting the
+
+documentation. %% added 2010/03/10
+
+
+
+\section{Styles supported (parsers provided)}\label{sec:styles}
+
+% \section{Styles of commenting '.sty's}
+
+We find different styles of documenting \LaTeX\ packages.
+
+As the main aspects I consider
+
+(i)~\emph{telling code from comments}
+
+and (ii)~\emph{markup in comments}.
+
+(You may find more details on the next matters in the
+
+ ``implementation" section.)
+
+
+
+\subsection{Telling code from comments}
+
+\emph{Comment marks} (usually \lq`%'\rq\ in the case of \TeX)
+
+probably were named so to mark \emph{``comments"} as opposed
+
+to code $\dots$ great, but actually, in ``daily practice,"
+
+they are so handy---and used---for ``commenting out" \emph{code},
+
+i.e., \emph{managing code versions} in a simple way:
+
+one does not actually want to \emph{delete} code,
+
+one might want to use it another time, maybe for debugging
+
+$\dots$ or to remind of earlier attempts that should not be tried
+
+again $\dots$
+
+
+
+This is a problem for \emph{high-quality typesetting} of
+
+documentation. \emph{Code} should be typeset about as you see it on
+
+the \emph{screen}---\emph{monospaced}, this allows structuring by
+
+indenting, it is common practice to use a typewriter typeface for
+
+this. Real \emph{comments} should be typeset in \emph{high quality} as
+
+usual with \LaTeX. Little dilemmas therefore occur with \emph{``hidden
+
+code"} (``commented-out"). A comment mark starts the line, but
+
+obviously it is not really a comment and rather should be typeset
+
+like code (and otherwise they may break). %% 2010/03/22
+
+Another problem are comments at the \emph{end} of a
+
+\emph{code} line. Sometimes they are ``real comments" ('gmdoc'
+
+supports this style). But sometimes
+
+this is only another version of ``version management," code
+
+``commented-out."
+
+
+
+I like the style of writing packages described before and use it all
+
+the time. I mark ``real comments" with \emph{two} adjacent comment
+
+marks and an ensuing space to distinguish them clearly from code
+
+commented out.
+
+%% Adapted to v0.4 2010/03/29:
+
+\emph{This style is presently the one supported by \textup{'makedoc'}
+
+ as default.}
+
+This way only a line starting with
+
+|%% | is considered a ``real" comment line. The first three
+
+characters are removed, and the rest is typeset in high quality.
+
+Any other lines are typeset verbatim. The 'makedoc' \emph{parser}
+
+doing this has an ``identifier" |PPScomment| (``percent, percent,
+
+space"). Another identifier |comment| is a placeholder for
+
+the comment parser to be used, by default it is an alias for
+
+`PPScomment'. Lines just containing |%%| (without the space) may be
+
+used to suppress empty code lines preceding section titles and for
+
+keeping some visual, relieving space between code and comment lines.
+
+
+
+The style I described previously may be considered ``unprofessional."
+
+The many \LaTeX\ packages documented using the 'doc'\slash'.dtx'
+
+system don't use comment marks for \emph{``commenting-out"}.
+
+Or one may mark code commented out by putting no space between the
+
+percent mark and the code.
+
+With v0.4 of 'makedoc', this style is supported as |PScomment|.
+
+You can directly call this as <main-parser> as described below,
+
+or you can switch to it by
+
+\[`\CopyFDconditionFromTo{PScomment}{comment}'\]
+
+
+
+\subsection{Markup in comments}
+
+Packages using the 'doc'\slash '.dtx' system as well as alternative
+
+highly developed systems mentioned above use (enhanced) usual
+
+\emph{\LaTeX} syntax for markup of comments. Other packages just use
+
+an \emph{ASCII} style \emph{without} any markup. My idea was to
+
+support the latter style by some `txt'$\to$\LaTeX\ functionality.
+
+'makedoc' does this using a file 'mdoccorr.cfg' which is very small
+
+right now.
+
+
+
+I also thought of introducing another sort of ``decent" markup not
+
+needing much more space than the ``ASCII kernel" of the comments.
+
+This is to some extent implemented in 'niceverb.sty'. I thought of the
+
+syntax of editing \textit{Wikipedia} pages; this is partially
+
+implemented in 'wiki.sty' which unfortunately is not yet compatible
+
+with 'niceverb'.
+
+
+
+But 'makedoc' implements one \textit{Wikipedia} feature in a different
+
+way than 'wiki.sty' (cf.~'wikicheat.pdf') that looks about as follows:
+
+\begin{eqnarray*}
+
+ \endcell\endcell`%% == Section =='\\
+
+ \endcell\endcell`%% === Subsection ==='\\
+
+ \endcell\endcell`%% ==== Subsubsection ===='
+
+\end{eqnarray*}
+
+i.e., you type `== <title> ==' in place of `\section{<title>}' etc.
+
+The parser must replace `====<title3>===' before `===<title2>===' and
+
+the latter before `==<title1>=='. In fact, 'makedoc' provides three
+
+parsers for these situations:
+
+\begin{description}
+
+\cmdboxitem|\SectionLevelThreeParseInput| is the most general parser
+
+ offered. If it does not find two strings \lq`===='\rq\ enclosing
+
+ \emph{something}, it passes to
+
+\cmdboxitem|\SectionLevelTwoParseInput| which unless finding
+
+ two strings `===' enclosing something passes to
+
+\cmdboxitem|\SectionLevelOneParseInput| $\dots$ passes to the comment
+
+ detector |comment|.
+
+\end{description}
+
+
+
+
+
+\section{Requirements}
+
+'makedoc' requires \LaTeXe\ (supporting star forms of `\newcommand'
+
+etc.)\ as \TeX-format, the package 'fifinddo.sty' from the same
+
+directory (on CTAN etc.)\ as where 'makedoc.sty' is, and the
+
+\LaTeX-package 'moreverb' by Robin Fairbairns (after others)---it
+
+should be installed anyway, or you can get its latest version
+
+(v2.3, 2008/06/03?) from CTAN.
+
+
+
+'makedoc''s `.txt'$\to$\TeX\ functionality moreover needs a file
+
+'mdoccorr.cfg' that should have come along with 'makedoc.sty' and
+
+'fifinddo.sty'. You may need to have a modified copy of it in the
+
+directory of your main `.tex' file `<jobname>.tex' fitting special
+
+needs of your project.
+
+
+
+\section{Using 'makedoc' the simplest way}
+
+In the most simple case, you are preparing documentation for a package
+
+file `<jobname>.sty' only, and you prepare a file `<jobname>.tex'
+
+containing
+
+\[`\title{\textsf{<jobname>}---a \LaTeX\ Package for <whatever>}'\]
+
+and `\maketitle' etc.\ about your package.\footnote{With 'niceverb'
+
+ and &\title\ after &\begin{document}, you may replace
+
+ \lq&\textsf{<jobname>}\rq\ by \lq&'<jobname>&'\rq.}
+
+The documentation will be produced by running `<jobname>.tex' with
+
+\LaTeX\ (e.g., \texttt{latex <jobname>.tex}).
+
+
+
+First, `<jobname>.tex' must have |\usepackage{makedoc}| in its preamble.
+
+There are no package options.
+
+
+
+Second, to typeset the commented implementation from `<jobname>.sty',
+
+include in <jobname>.tex's `document' environment a line
+
+\[|\MakeInputJobDoc{<header-lines>}{\SectionLevelThreeParseInput}|\]
+
+<header-lines> refers to a non-negative integer as follows:
+
+We think the most simple and useful way of typesetting the first lines
+
+of a package file including license and copyrights is ``depicting them
+
+as image," i.e., \textit{verbatim}. We could try to determine the
+
+number of these lines by parsing, but we won't do so soon. Please just
+
+count them and enter the number as <header-lines>---and change it
+
+until you can accept the outcome.
+
+
+
+\section{Steps of advanced usage}
+
+\subsection{Different main parsers (second mandatory argument)}
+
+
+
+`\MakeInputJobDoc''s mandatory syntax actually is
+
+\[|\MakeInputJobDoc{<header-lines>}{<main-parser>}|\]
+
+<main-parser> refers to the parsing macro that is applied to each
+
+input line whose number is greater than <header-lines>.
+
+Examples for <main-parser> are named in section~\ref{sec:styles} above.
+
+ %% TODO above/below macro 2010/03/15
+
+`\SectionLevelThreeParseInput' is just the most general one.
+
+For \emph{efficiency} (!? or also to avoid problems?) you may
+
+replace `Three' by `Two' or by `One', if the `====' or the `==='
+
+feature is not used in `<jobname>.sty'. If the ``\textit{Wikipedia}
+
+sectioning" feature is not used at all, use
+
+\[|\MakeInputJobDoc{<header-lines>}{\ProcessInputWith{comment}}|\]
+
+---provided you want to adopt the \lq`%% '\rq\ style of marking
+
+comments, cf.~section~\ref{sec:styles}. For the \lq`% '\rq style
+
+instead, use
+
+\[|\MakeInputJobDoc{<header-lines>}{\ProcessInputWith{PScomment}}|\]
+
+
+
+\subsection{Different extensions (optional arguments)}
+
+If your package to be documented is a \emph{class} `<jobname>.cls',
+
+a local configuration file `<jobname>.cfg' or something
+
+else---<jobname>.<ext-in>, e.g., <ext-in>=`cls' or <ext-in>=`cfg',
+
+use
+
+\[|\MakeInputJobDoc[<ext-in>]{<header>}{<parser>}|\]
+
+Moreover, `\MakeInputJobDoc' writes an intermediate file
+
+`<jobname>.doc' and then `\input's it. If you do not like `doc'
+
+as extension for the written file name (maybe you use
+
+`<jobname>.doc' for something different already), preferring extension
+
+<ext-out>, use
+
+\[|\MakeInputJobDoc[<ext-in>][<ext-out>]{<header>}{<parser>}|\]
+
+Yes, you must state <ext-in> then as well, I can't help $\dots$
+
+
+
+If even <jobname> is wrong in your view, see next step $\dots$
+
+
+
+\subsection{Commands modifying &\MakeInputJobDoc's behaviour}
+
+\label{sec:modimake}
+
+Already <jobname> may not be what you want. E.g., you may want
+
+to collect documentations of some other files <job-1>, <job-2>,
+
+$\dots$ in a single <jobname>. Then precede `\MakeInputJobDoc'
+
+with
+
+\[`\renewcommand*{\mdJobName}{<job-1>}'\]
+
+etc.\ (please reason yourself about additional requirements \dots)
+
+As a matter of fact, `\MakeInputJobDoc' reads
+
+\[`\mdJobName.<ext-in>' \mbox{\quad and writes\quad}
+
+ `\mdJobName.<ext-out>'\]
+
+Stated another way, <jobname> above referred to |\mdJobName|.
+
+
+
+`\MakeInputJobInput' moreover (by default) produces one dot
+
+per input line processed on screen to show progress.
+
+The reason is that `makedoc' issues the command
+
+|\ProcessLineMessage{\message{.}}|.
+
+Already this trivial thing seems to slow down processing considerably
+
+(nowadays). `\MakeInputJobInput' will run faster if preceded by
+
+\[|\ProcessLineMessage{}|\]
+
+which will suppress any message about processing.
+
+However, the message may be helpful in trouble-shooting.
+
+
+
+\subsection{Separating preprocessing from typesetting}
+
+ %% extended 2010/03/16
+
+To some surprise, I observe that `\MakeInputJobDoc' \emph{works.}
+
+This is quite a new discovery of mine (2010/03/13);
+
+before I thought that, for safety, preprocessing should happen
+
+inside a local group \emph{preceding} `\documentclass'.
+
+|\MakeJobDoc| works like `\MakeInputJobDoc' described above,
+
+yet it just \emph{preprocesses} the package to be documented,
+
+waiting for an
+
+\[`\input{<jobname>.<ext-out>}'\]
+
+in the `document' environment to \emph{typeset} the documentation.
+
+So 'makedoc.tex' once had in its preamble
+
+% \[`{\RequirePackage{makedoc} \MakeJobDoc{<header>}{<parser>}}'\]
+
+% at the top of `<jobname>.tex' and `\input{<jobname>.<out-ext>}' later.
+
+\begin{eqnarray*}\endcell\endcell
+
+ `{\RequirePackage{makedoc}'\cr \endcell\endcell
+
+ ` \ProcessLineMessage{}'\cr \endcell\endcell
+
+ ` \MakeJobDoc{22}{\ProcessInputWith{comment}}}'\cr
+
+ \endcell\endcell
+
+ `\documentclass{article}'
+
+\end{eqnarray*}
+
+I did experience some truth in my earlier safety policy:
+
+With 'niceverb' ``running," `\MakeJobDoc' cannot (easily) be used
+
+in the `document' environment. `\MakeInputJobDoc' in fact does some
+
+'niceverb' switching (provided 'niceverb' has been loaded)
+
+when making use of `\MakeJobDoc'.
+
+ %% <- verbose to improve line breaks 2010/03/16
+
+
+
+Thinking of this ``safety" approach, especially grouping (`{\code}'),
+
+I had not much cared for compatibility with other packages
+
+in choosing 'makedoc' macro names.
+
+
+
+\subsection{Other 'makedoc' (and 'fifindo') script commands}
+
+The next script commands may be considered of a lower level than
+
+`\MakeJobDoc' and `\MakeInputJobDoc', they underlie the latter
+
+commands. We also list commands from 'fifinddo.sty' that may be useful
+
+or, indeed, are needed for preparing package documentations.
+
+This may result in ideas on how do use the script commands for
+
+different purposes than for preparing package documentations---e.g.,
+
+apply `txt'$\to$\TeX\ preprocessing to arbitrary text files.
+
+
+
+\subsubsection{Choosing parameter values for next preprocessing run}
+
+
+
+This actually continues section~\ref{sec:modimake}.
+
+
+
+\begin{description}
+
+\cmdboxitem|\ResultFile{<output>}| (from 'fifinddo')
+
+ determines (and opens through the \TeX\ primitive `\openout')
+
+ the file <output> which will contain the result of
+
+ preprocessing the package file.
+
+\cmdboxitem|\LaTeXresultFile{<output>}|---see next section.
+
+\cmdboxitem|\Headerlines{<number>}| determines the <number> of lines
+
+ starting the input file to be copied \emph{verbatim}
+
+ (the first mandatory argument of `\MakeJobDoc').
+
+\cmdboxitem|\MainDocParser{<parser>}| determines the <parser>
+
+ as in the \emph{second} mandatory argument of `\MakeJobDoc'.
+
+\end{description}
+
+
+
+We are now describing some parameters which rather must be switched
+
+``manually" instead of being modifiable by comfortable 'makedoc'
+
+script commands.
+
+
+
+With the \emph{``Wikipedia sectioning"} feature, you may change the outcome
+
+regarding levels. Assume, e.g., the package file has titles along the
+
+scheme `== <title> ==' only, but these should become
+
+\emph{subsections} of the ``implementation" section of the
+
+corresponding `.tex' file. Then
+
+\[`\renewcommand*{\mdSectionLevelOne}{\string\subsection}'\]
+
+-- see the implementation of the sectioning feature for details.
+
+
+
+There is a command
+
+\[|\NoEmptyInputLines| \mbox{\quad and a parameter macro\quad}
+
+ |\OnEmptyInputLine|\]
+
+which is modified by the former. However, I cannot say much about them
+
+right now, I think they just were a difficult matter that I soon
+
+decided no longer to think about for a while (cf.\ the
+
+implementation). About the same holds for the hook |\EveryComment|.
+
+
+
+The `txt'$\to$\TeX\ functionality is implemented through a hook
+
+\[|\MakeDocCorrectHook{<characters>}|\]
+
+'makedoc' initializes it as an alias of \LaTeX's `\@firstofone', i.e.,
+
+it won't change <characters>. 'mdoccorr.cfg' should redefine it so it
+
+really ``corrects" <characters>. You might try other definitions of
+
+`\MakeDocCorrectHook' for different ``correcting" functions.
+
+It should be \emph{noted} that (currently)
+
+`\MakeDocCorrectHook' must be \emph{expandable}, 'fifinddo.sty'
+
+provides setup for (expandable) chains of expandable replacements.
+
+The ``Wikipedia" sectioning feature moreover uses expandable
+
+trimming (single) surrounding spaces, this might be provided in a more
+
+general way.\footnote{%% TODO 2010/03/16
+
+ The \ctanpkgref{trimspaces} package
+
+ has been a \emph{model} for this feature here. It cannot be used
+
+ directly here because it reads blank spaces as \TeX\ characters with
+
+ category code 10 while 'makedoc' reads blank spaces as ``other"
+
+ characters (category code 12) in order to \emph{keep} all blank spaces.}
+
+
+
+\subsubsection{``Manual" insertions to the output file}
+
+\begin{description}
+
+\cmdboxitem|\WriteResult{<balanced>}| (from 'fifinddo') writes
+
+ <balanced> to <output> according to the earlier command
+
+ `\ResultFile{<output>}'.
+
+\cmdboxitem|\WriteProvides| (from 'fifindo') writes a
+
+ `\ProvidesFile' line into <output> that declares the file
+
+ to be generated by 'fifindo'.
+
+\cmdboxitem|\LaTeXresultFile{<output>}| issues
+
+ `\ResultFile{<output>}' and then writes a
+
+ `\ProvidesFile' line into <output> that declares the file
+
+ to be generated by 'makedoc'.
+
+\end{description}
+
+
+
+\subsubsection{Processing input and closing output}
+
+\begin{description}
+
+\cmdboxitem|\MakeDoc{<input>}|\hskip 0pt plus 4em
+
+ reads 'mdoccorr.cfg'
+
+ (for `\MakeDocCorrectHook', see above),
+
+ %% removed \LaTeXresult... 2010/03/17
+
+ copies <number> according to `\HeaderLines' (see above)
+
+ from <input> into <output> (according to `\ResultFile'),
+
+ then processes the remaining lines of <input> according
+
+ to `\MainDocParser' (writing several things to <output>).
+
+ `\MakeDoc' invokes{\sloppy\par}
+
+\cmdboxitem|\ProcessFileWith{<input>}{<loop-body>}|
+
+ (from 'fifindo') reads <input> line by line---each one stored as
+
+ macro |\fdInputLine| and applies <loop-body> to it.
+
+ \TeX's ``special" character codes (of characters listed in
+
+ macro `\dospecials') are replaced by 12 (``other") by
+
+ default---see the 'fifinddo' documentation.
+
+\cmdboxitem|\CloseResultFile| (from 'fifinddo')
+
+ \hskip 0pt plus 1em
+
+ \emph{closes}
+
+ <output> (using \TeX's primitive `\closeout').
+
+\cmdboxitem|\MakeCloseDoc{<input>}| issues
+
+ `\MakeDoc{<input>}\CloseResultFile'.
+
+\end{description}
+
+%
+
+Using `\MakeDoc' \emph{instead} of `\MakeCloseDoc' allows processing
+
+additional <input> files writing into the same <output>. Or maybe you
+
+want to add some additional lines manually to <output> using
+
+`\WriteResult'.
+
+
+
+%% removed 2010/03/09:
+
+% At least in the long run, using 'makedoc' should not imply commitment
+
+% to a certain design or to certain \LaTeX\ packages for typesetting
+
+% listings and documentations. Therefore, 'makedoc.cfg' (currently)
+
+% contains \emph{local} or \emph{personal choices}, but also
+
+% \emph{experiments} with future features of 'niceverb'.
+
+% Especially, (at present) the `packagecode'
+
+% environment that 'makedoc' `\write's must be chosen.
+
+% Currently this is the `listing' environment from 'moreverb'
+
+% with some modifications or extra settings.
+
+% It may be vital to `\MakeOther' the active characters from 'niceverb'
+
+% in the setup of `packagecode'. See the \emph{example} in
+
+% section~\ref{sec:fifinddo}.
+
+%
+
+% Finally,
+
+% Each package file to be typeset needs its own little
+
+% \emph{script} of 'makedoc' commands.
+
+% With v0.3, one or two of these should suffice.
+
+
+
+% It should fit into the preamble
+
+% of the main file for documenting the package (currently %% 2009/04/09
+
+% just 5 commands seem to suffice, see the \emph{example} in
+
+% section~\ref{sec:fifinddo}).
+
+% The script commands are described
+
+% in the \dqtd{File handling} section of 'fifinddo.pdf' and in the
+
+% present section~\ref{sec:script} (and \ref{sec:emptylines}).
+
+% As an alternative, you may prefer to have ``content only" (as much as
+
+% possible) in the main typesetting file and in its preamble only
+
+% `\input' a separate script file.
+
+%% removed 2010/03/10:
+
+% Yes, the idea of documenting a package \emph{here} is to have a
+
+% separate ``driver" file for typsetting the documentation.
+
+% It may contain an introduction and a guide for users.
+
+% The documentation of the package code that has been prepared by the
+
+% 'makedoc' script will be `\input'. Alternatively, the ``driver file"
+
+% could have title etc.\ only, or preamble and a minimal `document'
+
+% environment only.
+
+%
+
+% So there may be many files, which may look confusing, especially as
+
+% compared with the 'doc' procedure. However,
+
+% \begin{enumerate}
+
+% \item ``One file distribution" still is possible thanks to the
+
+% `filecontents' environment.
+
+% \item The 'makedoc' script can create a batch file (fitting the
+
+% system, maybe using Will Robertson's 'ifplatform', or
+
+% 'texsys.cfg', or \dots)
+
+% that removes certain auxiliary files or moves them to a
+
+% certain directory.
+
+% \item I find it helpful to have rather little ``contentual" text
+
+% in the package file.
+
+% \item The procedure now runs very smoothly, once the stumbling blocks
+
+% have been overcome.\footnote{\hspace{1sp}%% TODO help in 'niceverb'!
+
+% 'niceverb' v0.1 was too sloppy with
+
+% some things, and self-documentation of 'makedoc.sty' was
+
+% difficult---its parsing and that from 'verbatim' cannot
+
+% distinguish between markup code and typeset code.}
+
+% \end{enumerate}
+
+
+
+\section{Examples}%%% (documentation of 'mdoccorr.cfg')}
+
+%% moved here 2010/03/23
+
+\subsection{'nicetext', especially 'mdoccorr.cfg'}
+
+The documentations of 'fifinddo', 'makedoc', and 'niceverb'
+
+themselves are typeset using 'makedoc'.
+
+'fifinddo.pdf' documents 'fifinddo.sty', typeset
+
+from 'fifinddo.tex', likewise 'makedoc.pdf' and 'niceverb.pdf'.
+
+% Section~\ref{sec:fifinddo} contains a listing of
+
+% 'makedoc.cfg' and
+
+% the 'makedoc' script file 'mkfddoc.tex'
+
+% especially made for 'fifinddo.pdf'.
+
+% 'fifinddo.doc', 'makedoc.doc', and 'niceverb.doc' are the \TeX\ input
+
+% files that were made with 'makedoc.sty'---I have only looked at them
+
+% when something was wrong (often syntax mistakes in typing).
+
+The Wikipedia syntax feature
+
+\begin{quote}
+
+ `%% === subsection ==='
+
+\end{quote}
+
+is used in 'fifinddo.sty' and 'niceverb.sty' only.
+
+
+
+Along with 'makedoc' should come files `makedoc.tpl'---a template
+
+'makedoc' script, and a file `fdtxttex.tex' that should start a dialogue
+
+on trying `\MakeDocCorrectHook' if you can manage to run it ('WinShell'?).
+
+With other definitions of `\MakeDocCorrectHook'---see below---you can
+
+use this dialogue for arbitrary replacement jobs (as an application of
+
+'fifinddo' rather than 'makedoc').{\sloppy\par}
+
+
+
+'fifinddo.pdf', 'makedoc.pdf', and 'niceverb.pdf' were typeset with the following
+
+typographical corrections in 'mdoccorr.cfg' that defines
+
+`\MakeDocCorrectHook':
+
+\strut\hrule
+
+\begingroup
+
+ \hfuzz=\textwidth \advance \hfuzz by 28pt
+
+ \MakeOther\|\MakeOther\`\MakeOther\'\MakeOther\<
+
+ \listinginput[5]{1}{mdoccorr.cfg}
+
+\endgroup
+
+\hrule\noindent\strut
+
+This code also exemplifies the syntax 'niceverb' provides for writing
+
+about \LaTeX\ macros. It is typeset here with 'makedoc.sty'
+
+and then looks thus:
+
+% \sloppy %% 2010/03/29
+
+\strut\hrule
+
+\renewcommand*{\mdJobName}{mdoccorr}
+
+\MakeInputJobDoc[cfg]{0}{\ProcessInputWith{comment}}
+
+\hrule \noindent\strut
+
+And this is the content of the intermediate generated file:
+
+\hrule
+
+\begingroup
+
+ \hfuzz=\textwidth \advance \hfuzz by 28pt
+
+ \MakeOther\|\MakeOther\`\MakeOther\'\MakeOther\<
+
+ \listinginput[5]{1}{mdoccorr.doc}
+
+\endgroup
+
+\hrule
+
+% \fussy %% 2010/03/29
+
+
+
+\subsection{Packages from other authors}
+
+`substr.tex' should typeset a nicely formatted documentation
+
+of Harald Har\-der's 'substr.sty', see my own result `substr.pdf'.
+
+'substr.sty' is a rare case of the \lq`%% '\rq\ commenting style
+
+that 'nicetext' has used itself.
+
+
+
+`arseneau.tex' should typeset nicely formatted documentations
+
+of a few packages by Donald Arseneau, see my own result `arseneau.pdf'.
+
+This demonstrates the usual \lq`% '\rq\ commenting style
+
+that 'makedoc' supports with v0.4.
+
+
+
+\pagebreak %% 2010/03/29
+
+\ResetCodeLineNumbers %% 2010/03/29
+
+\section{Implementation}
+
+\subsection{Preliminaries}
+
+Head of file (Legalese):
+
+\sloppy
+
+\renewcommand*{\mdJobName}{makedoc}
+
+\ProcessLineMessage{}
+
+\MakeInputJobDoc{22}{\ProcessInputWith{comment}}
+
+The previous empty code line is the one \TeX\ insists to add at every
+
+end of a file it writes. %% todo TeXbook where? 2009/04/08
+
+
+
+%% removed (TODO) 2010/03/15:
+
+% \section{Examples: documentation of 'fifinddo'}
+
+% \label{sec:fifinddo}
+
+%% removed 2010/03/10:
+
+% \subsection{'makedoc.cfg'}
+
+% 'fifinddo.pdf' and 'makedoc.pdf' were typeset with the following
+
+% configuration file 'makedoc.cfg':
+
+% \begingroup \MakeOther\|\MakeOther\`\MakeOther\'\MakeOther\<
+
+% %% <- TODO should be 'niceverb' command 2009/04/08
+
+% \listinginput[5]{1}{makedoc.cfg}
+
+% \endgroup
+
+%
+
+%% TODO 'niceverb' example---to 'niceverb.tex'!? 2010/03/15
+
+% \subsection{'mkfddoc.tex'}
+
+% 'fifinddo.pdf' was typeset with the following 'makedoc' script file
+
+% 'mkfddoc.tex':
+
+% \begingroup
+
+% \MakeOther\|\MakeOther\`\MakeOther\'\MakeOther\<
+
+% \listinginput[5]{1}{mkfddoc.tex}
+
+% \endgroup
+
+%
+
+%
+
+\end{document}
+
+
+
+2009/04/12 more on examples
+
+2009/04/15 exemplification of niceverb.sty by mdcorr.cfg
+
+2009/04/21 === subsubsection -> === subsection
+
+2010/03/08 moved `only' for better line break
+
+2010/03/09 removed something from "Basics"
+
+2010/03/10 more changes in "Basics", pdf stuff to makedoc.cfg,
+
+ makedoc.cfg no longer example; CodeDoc
+
+2010/03/11 use \MakeCloseDoc; \hfuzz with \listinginput;
+
+ tracing spurious `Label(s) may have changed'
+
+2010/03/12 tests for hyperref compatibility completed
+
+2010/03/13 use \MakeInputJobDoc; clarified ...; ctan.org/pkg
+
+2010/03/14 updated ``Examples" and abstract; \href...easylatex
+
+2010/03/15 ``styles supported"; abstract: txt->TeX; usage
+
+2010/03/16 more on usage; mdcorr -> mdoccorr
+
+2010/03/17 corr. mistake with \MakeDoc
+
+2010/03/19 '' -> "
+
+2010/03/20 for niceverb v0.31
+
+2010/03/21 for niceverb v0.32
+
+2010/03/22 "may break"
+
+2010/03/23 \noindent in example, moved, added mdoccorr.doc,
+
+ makedoc.tpl
+
+2010/03/29 \ResetCodeLineNumbers,
+
+ examples and explanations for v0.4
+
+2010/03/30 \listfiles test
+
diff --git a/Master/texmf-dist/doc/latex/nicetext/docsrc/mdoccheat.tex b/Master/texmf-dist/doc/latex/nicetext/docsrc/mdoccheat.tex
new file mode 100644
index 00000000000..bf191c53617
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/nicetext/docsrc/mdoccheat.tex
@@ -0,0 +1,208 @@
+\typeout{mdoccheat.tex 2010/03/30 cheat sheat for `makedoc.sty'}
+
+% \listfiles
+
+\documentclass{article}
+
+\input{makedoc.cfg} %% with pdf stuff and 'niceverb'
+
+\makeatletter
+
+ \def\today{\the\year/\two@digits\month/\two@digits\day}
+
+% \let\sofar@arraycr\@arraycr
+
+ \newenvironment*{displines}
+
+ {\def\ccr{\\&}%
+
+ \csname eqnarray*\endcsname&}
+
+ {\csname endeqnarray*\endcsname}
+
+ \def\@listi{\leftmargin\leftmargini
+
+ \parsep 3\p@ \@plus2\p@ \@minus\p@
+
+ \topsep 6\p@ \@plus2\p@ \@minus4\p@
+
+ \itemsep3\p@ \@plus2\p@ \@minus\p@}
+
+ \let\@listI\@listi
+
+\makeatother
+
+\newcommand*{\defto}[2]{$#1\to_{\mathit{default}}#2$}
+
+% \sfcode`/=1001 %% TODO makedoc.cfg!? 2010/03/15
+
+\sloppy
+
+\begin{document}
+
+ \enlargethispage{1\baselineskip} %% 2010/03/29
+
+% \null\kern-1\baselineskip
+
+\begin{center}
+
+ \bfseries \Large
+
+ 'makedoc' \& 'fifinddo'\footnote{\url{http://ctan.org/pkg/nicetext}}
+
+ File Handling Commands
+
+ \\[.4ex] \mdseries \large
+
+ Uwe L\"uck, \today
+
+ \\[10pt] \normalsize
+
+ |\usepackage{makedoc}|, see 'makedoc.pdf' for details
+
+\end{center}
+
+\thispagestyle{empty}
+
+ \par\kern5pt
+
+\noindent \textbf{Most simple:} |\MakeInputJobDoc|
+
+in `<jobname>.tex' \emph{after} &\begin{document}
+
+\begin{displines}
+
+ `\MakeInputJobDoc{<header-lines>}{<main-parser>}'
+
+ \ccr
+
+ `\MakeInputJobDoc[<in-ext>]{<header-lines>}{<main-parser>}'
+
+ \ccr
+
+ `\MakeInputJobDoc[<out-ext>][<in-ext>]{<header-lines>}{<main-parser>}'
+
+\end{displines}
+
+documents `\mdJobName.<in-ext>' via `\mdJobName.<out-ext>',
+
+\defto{<in-ext>}{`sty'}, \defto{&\mdJobName}{<jobname>},
+
+\defto{<out-ext>}{`doc'},
+
+ \par\kern-5pt
+
+\begin{center} %% Parsers:
+
+\begin{tabular}{@{}l@{\hskip4pt }l@{\hskip4pt }l@{}}
+
+<main-parser>\endcell detects\endcell involves\\\hline
+
+`\SectionLevelThreeParseInput'\endcell
+
+ `==== <title> ===='\endcell`\mdSectionLevelThree'\\
+
+`\SectionLevelTwoParseInput'\endcell
+
+ `=== <title> ==='\endcell`\mdSectionLevelTwo'\\
+
+`\SectionLevelOneParseInput'\endcell
+
+ `== <title> =='\endcell`\mdSectionLevelOne'\\
+
+%% 2010/03/29:
+
+`\ProcessInputWith{PPScomment}'\endcell
+
+ `%% <comment>'\endcell `%%<empty>', 'mdoccorr.cfg'\\
+
+`\ProcessInputWith{PScomment}'\endcell
+
+ `% <comment>'\endcell `%<empty>', 'mdoccorr.cfg'
+
+\end{tabular}
+
+\end{center}
+
+
+
+% \par\kern-2pt
+
+\noindent \textbf{Preprocessing before} &\begin{document}:
+
+|\MakeJobDoc| (same parameters)
+
+
+
+ \vskip10pt \raggedright
+
+\noindent \textbf{More fine-grained:}\\
+
+\textbf{a.~Choices for next preprocessing run:}
+
+\begin{description}
+
+\cmdboxitem|\ResultFile{<output>}| opens <output>
+
+% \cmdboxitem|\LaTeXresultFile{<output>}| see below
+
+\cmdboxitem|\Headerlines{<header-lines>}|
+
+ `\MakeJobDoc''s first mandatory argument
+
+\cmdboxitem|\MainDocParser{<main-parser>}|
+
+ `\MakeJobDoc''s second mandatory \rlap{argument}
+
+\cmdboxitem|\ProcessLineMessage{<message>}|
+
+ \defto{<message>}{&\message{.}}
+
+\cmdboxitem|\input{mdoccorr.cfg}| chooses `\MakeDocCorrectHook'
+
+\end{description}
+
+\textbf{b.~Manual insertions to <output>:}
+
+\begin{description}
+
+\cmdboxitem|\WriteResult{<balanced>}| writes <balanced> to <output>
+
+\cmdboxitem|\WriteProvides| writes `\ProvidesFile' line from 'fifindo'
+
+\cmdboxitem|\LaTeXresultFile{<output>}| issues
+
+ `\ResultFile{<output>}', writes `\ProvidesFile' line from 'makedoc'
+
+\end{description}
+
+\textbf{c.~Processing <input>, closing <output>:}
+
+\begin{description}
+
+\cmdboxitem|\ProcessFileWith{<input>}{<loop-body>}|
+
+ reads each <input> line to macro |\fdInputLine|,
+
+ applies <loop-body>
+
+\cmdboxitem|\MakeDoc{<input>}|
+
+ copies <header-lines> from <input> to <output>,
+
+ applies <main-parser>
+
+\cmdboxitem|\CloseResultFile| closes <output>
+
+\cmdboxitem|\MakeCloseDoc{<input>}| issues
+
+ `\MakeDoc{<input>}\CloseResultFile'
+
+\end{description}
+
+
+
+\end{document}
+
+
+
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
+
diff --git a/Master/texmf-dist/doc/latex/nicetext/docsrc/wikicheat.tex b/Master/texmf-dist/doc/latex/nicetext/docsrc/wikicheat.tex
new file mode 100644
index 00000000000..4f04ff16bce
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/nicetext/docsrc/wikicheat.tex
@@ -0,0 +1,296 @@
+\ProvidesFile{wikicheat}[2008/07/10 Cheatsheet for wiki.sty]
+
+% \def\title{Cheatsheet for the \textsf{wiki} Package}
+
+\def\title{\textbf{Cheatsheet} for the \textbf{\textsf{wiki}} Package}
+
+\def\author{Uwe L\"uck}
+
+\documentclass[12pt,a4paper]{article}
+
+\nofiles
+
+\pagestyle{empty}
+
+\makeatletter
+
+\@ifundefined{UndeclareTextCommand}{}{\usepackage{upquote}} %% 2008/07/02
+
+\makeatother
+
+\usepackage{wiki}
+
+% \let\WE\relax \let\WF\relax \let\WH\relax
+
+\let\WE\wikiEnvironments
+
+\let\WF\wikiFonts
+
+\let\WH\wikiHeadings
+
+\def\SP#1{\multicolumn{3}{\VR c\VR}{%
+
+% \parbox{11cm}{%
+
+ \parbox{13cm}{%
+
+ \footnotesize\it\sloppy\SU#1\SD}}}
+
+\def\SL{/\hskip.16667em}
+
+% \setbox0\hbox{(}\showthe\ht0\showthe\dp0 %% height = 3x depth
+
+\def\SU{\rule{0pt}{.99em}}%%%{1.1em}}
+
+\def\HSU{\rule{0pt}{.75em}}
+
+\def\SD{\rule[-.33em]{0pt}{0pt}}%%%45em]{0pt}{0pt}}
+
+% \def\CS#1{{\tt\textbackslash #1}} %% 2008/07/02
+
+{\makeatletter \gdef\CS#1{{\tt\@backslashchar#1}}}
+
+\let\VR| \catcode`\|\active \def|{\verb|}
+
+\begin{document}
+
+% \maketitle
+
+
+
+\enlargethispage{3\normalbaselineskip}
+
+\vspace*{-\topmargin} %% !?
+
+\vspace*{-\headheight}\vspace*{-\headsep}\vspace*{-\topsep}\vspace*{-\partopsep}
+
+\begin{center}
+
+\large \title\\[.4ex] \normalsize
+
+Some \LaTeX-Markup through some Wiki-Markup\\[.8ex]
+
+ \author, \today
+
+% \end{center}
+
+
+
+\vspace{\topsep}
+
+\vspace*{\partopsep}
+
+% \vspace{1.5ex}
+
+% \vspace{1ex}
+
+% \hrule
+
+% \vspace{1ex}
+
+
+
+% \begin{center}
+
+\leavevmode\kern-1em
+
+\begin{tabular}{\VR l\VR l\VR l\VR}
+
+\hline\hline
+
+\SU\SD\bf Code for \textsf{wiki.sty}&\bf What you get& \bf like \LaTeX-code\\
+
+\hline\hline
+
+|''italic''|&\WF ''italic''&|\textit{italic}|\SU\\
+
+|'''bold'''|&\WF '''bold'''&|\textbf{bold}|%%%\\
+
+\SD\\
+
+% |'''''bf+it'''''|&\WF '''''bf+it'''''
+
+% &|\textbf{\textit{bf+it}}|\SD\\
+
+% |'''''B+I'''''|&\WF '''''B+I''''' &|\textbf{\textit{B+I}}|\SD\\
+
+\hline
+
+\SP{``Italic'' and ``bold'' may be combined, nested, overlap.
+
+% Automatic italic correction cannot be suppressed by \CS{nocorr}.
+
+% Implementation uses \LaTeX\ internals; no groups are formed.
+
+Quotation marks
+
+% (even German)
+
+usually are not
+
+affected.---Turn
+
+% {\tt '\string{\string}''} may help with
+
+% apostrophes.---Turn
+
+font feature on/off by \CS{wikiFonts}\SL\CS{nowikiFonts}; disable feature
+
+entirely by package option {\tt noFonts}.}\\
+
+\hline\hline
+
+|== Level 1 ==|&\Large\bf\HSU 1\quad Level 1&|\section{Level 1}|\SU\\
+
+|=== Level 2 ===|&\large\bf 1.1\quad Level 2&|\subsection{Level 2}|\SU\\
+
+|==== Level 3 ====|&\bf 1.1.1\quad Level 3&|\subsubsection{Level 3}|\\
+
+|===== Level 4 =====|&\bf Level 4 &|\paragraph{Level 4}|\SD\\
+
+|====== Level 5 ======|&\bf Level 5 &|\subparagraph{Level 5}|\SD\\
+
+\hline
+
+\SP{Turn heading feature on/off by \CS{wikiHeadings}\SL\CS{nowikiHeadings};
+
+disable feature entirely by package option {\tt noHeadings}.}\\
+
+\hline\hline
+
+&&|\begin{itemize}|\SU\\
+
+|* One|&\textbullet\hspace\labelsep One &|\item One|\\[2\parsep]
+
+|* Two|&\textbullet\hspace\labelsep Two &|\item Two|\\
+
+&&|\end{itemize}|\SD\\
+
+\hline
+
+&&|\begin{enumerate}|\SU\\
+
+|# One|&1.\hspace\labelsep One &|\item One|\\[2\parsep]
+
+|# Two|&2.\hspace\labelsep Two &|\item Two|\\
+
+&&|\end{enumerate}|\SD\\
+
+\hline
+
+&&|\begin{description}|\SU\\
+
+|;[club] explain|&\textbf{club}\hspace\labelsep explain
+
+ &|\item[club] explain|\\[2\parsep]
+
+|;[widow] explain|&\textbf{widow}\hspace\labelsep explain
+
+ &|\item[widow] explain|\\
+
+&&|\end{description}|\SD\\
+
+\hline
+
+ & &|She wrote:|\SU\\
+
+|She wrote:|&\smash{\raisebox{\topsep}{She wrote:}}&|\begin{quote}|\\
+
+|:Indeed| &\hspace\leftmargini Indeed&|Indeed|\\
+
+ & &|\end{quote}|\SD\\
+
+\hline
+
+ & &|Type|\SU\\
+
+|Type| &\smash{\raisebox{\topsep}{Type}}&|\begin{verbatim}|\\
+
+| \typeout{OK!}| &|\typeout{OK!}|&|\typeout{OK!}|\\
+
+ & &|\end{verbatim}|\SD\\
+
+\hline
+
+\SP{A \CS{begin} is executed when {\tt*} etc.\ is first character of a
+
+code line; an indent starts {\tt verbatim}.
+
+\CS{end} is executed at code line without indent and not beginning with
+
+{\tt*} etc.---Turn this feature on by \CS{wikiEnvironments}; turn off by
+
+\CS{nowikiEnvironments}, e.g., to get around incompatibilities
+
+(lists feature is most dangerous).
+
+Disable feature entirely by package option {\tt noEnvironments}.
+
+Package option {\tt noVerbatim} instead may usually suffice,
+
+if you don't want to have any {\tt verbatim}.}\\
+
+\hline
+
+\end{tabular}
+
+\kern-1em
+
+\end{center}
+
+
+
+% \section{Test}\subsection{Sub-Test}\subsubsection{Subsub-Test}
+
+% \paragraph{Para}\subparagraph{Sub-Para}
+
+
+
+\footnotesize
+
+% \vspace{2ex}
+
+\sloppy
+
+\noindent \WE\WF %%% '''Please note:'''
+
+''Note:''
+
+% *
+
+Explicit '''turning on''' by %%% one of
+
+% \[|\wikiEnvironments|,\quad |\wikiFonts|,\quad |\wikiHeadings|\]
+
+|\wikiEnvironments| %%% , |\wikiFonts|, |\wikiHeadings|,
+
+etc.\
+
+% or by |\wikimarkup| (which executes the former three) is ''required'';
+
+is '''required''';
+
+e.g., after %%% |\maketitle| and
+
+|\tableofcontents|.
+
+|\wikimarkup| '''activates ''all''''' the features.
+
+% *
+
+|\nowikimarkup| %%% executes all of
+
+% \[|\nowikiEnvironments|,\quad |\nowikiFonts|,\quad |\nowikiHeadings|.\]
+
+% |\nowikiEnvironments|, |\nowikiFonts|, |\nowikiHeadings|.
+
+% Use them to get around incompatible code.
+
+'''''dis''ables all''' of them, e.g., to get around incompatibilities.
+
+
+
+\end{document}
+
+
+