diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex')
| -rw-r--r-- | Master/texmf-dist/doc/latex/nicetext/CHANGE.LOG (renamed from Master/texmf-dist/doc/latex/nicetext/doc/CHANGE.LOG) | 4 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/latex/nicetext/CHANGE.txt (renamed from Master/texmf-dist/doc/latex/nicetext/doc/CHANGE.txt) | 4 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/latex/nicetext/FILEs.txt (renamed from Master/texmf-dist/doc/latex/nicetext/FILES.txt) | 4 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/latex/nicetext/NNOUNCE.txt (renamed from Master/texmf-dist/doc/latex/nicetext/doc/NNOUNCE.txt) | 0 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/latex/nicetext/RELEAS03.txt (renamed from Master/texmf-dist/doc/latex/nicetext/doc/RELEAS03.txt) | 0 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/latex/nicetext/RELEAS04.txt (renamed from Master/texmf-dist/doc/latex/nicetext/doc/RELEAS04.txt) | 0 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/latex/nicetext/docsrc/README.tex | 11 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/latex/nicetext/docsrc/fifinddo.tex | 342 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/latex/nicetext/docsrc/gather.tex | 8 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/latex/nicetext/docsrc/makedoc.tex | 646 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/latex/nicetext/docsrc/mdoccheat.tex | 104 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/latex/nicetext/docsrc/niceverb.tex | 453 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/latex/nicetext/docsrc/wikicheat.tex | 148 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/latex/nicetext/fifinddo.pdf (renamed from Master/texmf-dist/doc/latex/nicetext/doc/fifinddo.pdf) | bin | 308881 -> 308881 bytes | |||
| -rw-r--r-- | Master/texmf-dist/doc/latex/nicetext/makedoc.pdf (renamed from Master/texmf-dist/doc/latex/nicetext/doc/makedoc.pdf) | bin | 304457 -> 304457 bytes | |||
| -rw-r--r-- | Master/texmf-dist/doc/latex/nicetext/mdoccheat.pdf (renamed from Master/texmf-dist/doc/latex/nicetext/doc/mdoccheat.pdf) | bin | 69681 -> 69681 bytes | |||
| -rw-r--r-- | Master/texmf-dist/doc/latex/nicetext/niceverb.pdf (renamed from Master/texmf-dist/doc/latex/nicetext/doc/niceverb.pdf) | bin | 278658 -> 278658 bytes | |||
| -rw-r--r-- | Master/texmf-dist/doc/latex/nicetext/wikicheat.pdf (renamed from Master/texmf-dist/doc/latex/nicetext/doc/wikicheat.pdf) | bin | 78545 -> 78545 bytes |
18 files changed, 10 insertions, 1714 deletions
diff --git a/Master/texmf-dist/doc/latex/nicetext/doc/CHANGE.LOG b/Master/texmf-dist/doc/latex/nicetext/CHANGE.LOG index 4bad6ce9db4..da671983231 100644 --- a/Master/texmf-dist/doc/latex/nicetext/doc/CHANGE.LOG +++ b/Master/texmf-dist/doc/latex/nicetext/CHANGE.LOG @@ -1,4 +1,8 @@ ______________________________________________________________________ +r0.42a 2011/01/30 moves makedoc.cfg to docsrc, changes name +`FILES.txt' into `FILEs.txt' and ordering within the file, +and uses the `source' tree in the .tds. +______________________________________________________________________ nicetext RELEASE 0.42 2011/01/26 SUMMARY: corrected `makedoc.sty', enhanced `fifinddo.sty' and .txt->.tex, use `hypertoc.sty' diff --git a/Master/texmf-dist/doc/latex/nicetext/doc/CHANGE.txt b/Master/texmf-dist/doc/latex/nicetext/CHANGE.txt index 4bad6ce9db4..da671983231 100644 --- a/Master/texmf-dist/doc/latex/nicetext/doc/CHANGE.txt +++ b/Master/texmf-dist/doc/latex/nicetext/CHANGE.txt @@ -1,4 +1,8 @@ ______________________________________________________________________ +r0.42a 2011/01/30 moves makedoc.cfg to docsrc, changes name +`FILES.txt' into `FILEs.txt' and ordering within the file, +and uses the `source' tree in the .tds. +______________________________________________________________________ nicetext RELEASE 0.42 2011/01/26 SUMMARY: corrected `makedoc.sty', enhanced `fifinddo.sty' and .txt->.tex, use `hypertoc.sty' diff --git a/Master/texmf-dist/doc/latex/nicetext/FILES.txt b/Master/texmf-dist/doc/latex/nicetext/FILEs.txt index f9dc3a20e57..4c512433240 100644 --- a/Master/texmf-dist/doc/latex/nicetext/FILES.txt +++ b/Master/texmf-dist/doc/latex/nicetext/FILEs.txt @@ -3,8 +3,8 @@ FILES IN CTAN DIRECTORY /macros/latex/contrib/nicetext: FILES.txt present file FileList.txt source file versions README summary - README.txt copy of README README.pdf PDF version of README + README.txt copy of README fifinddo.sty parsing and file handling makedoc.sty package to documentation preprocessing @@ -49,4 +49,4 @@ run dialogues/templates/examples |____substr.tex typesets substr.sty documentation __________________________ -this file 2011/01/26, U.L. +this file 2011/01/30, U.L. diff --git a/Master/texmf-dist/doc/latex/nicetext/doc/NNOUNCE.txt b/Master/texmf-dist/doc/latex/nicetext/NNOUNCE.txt index a39e9134bac..a39e9134bac 100644 --- a/Master/texmf-dist/doc/latex/nicetext/doc/NNOUNCE.txt +++ b/Master/texmf-dist/doc/latex/nicetext/NNOUNCE.txt diff --git a/Master/texmf-dist/doc/latex/nicetext/doc/RELEAS03.txt b/Master/texmf-dist/doc/latex/nicetext/RELEAS03.txt index 2c1905a37e2..2c1905a37e2 100644 --- a/Master/texmf-dist/doc/latex/nicetext/doc/RELEAS03.txt +++ b/Master/texmf-dist/doc/latex/nicetext/RELEAS03.txt diff --git a/Master/texmf-dist/doc/latex/nicetext/doc/RELEAS04.txt b/Master/texmf-dist/doc/latex/nicetext/RELEAS04.txt index acc9f8f74f5..acc9f8f74f5 100644 --- a/Master/texmf-dist/doc/latex/nicetext/doc/RELEAS04.txt +++ b/Master/texmf-dist/doc/latex/nicetext/RELEAS04.txt diff --git a/Master/texmf-dist/doc/latex/nicetext/docsrc/README.tex b/Master/texmf-dist/doc/latex/nicetext/docsrc/README.tex deleted file mode 100644 index ce26748edb5..00000000000 --- a/Master/texmf-dist/doc/latex/nicetext/docsrc/README.tex +++ /dev/null @@ -1,11 +0,0 @@ -\ProvidesFile{README.tex}[2010/11/27 make README.pdf] -\listfiles - -\documentclass[12pt]{article} -\usepackage{verbatim} -\pagestyle{empty} -\begin{document} -\vspace*{-2\baselineskip} -\enlargethispage{1\baselineskip} -\verbatiminput{README.txt} -\end{document} diff --git a/Master/texmf-dist/doc/latex/nicetext/docsrc/fifinddo.tex b/Master/texmf-dist/doc/latex/nicetext/docsrc/fifinddo.tex deleted file mode 100644 index f517ad3a3e7..00000000000 --- a/Master/texmf-dist/doc/latex/nicetext/docsrc/fifinddo.tex +++ /dev/null @@ -1,342 +0,0 @@ -\ProvidesFile{fifinddo.tex}[2010/11/27 documenting fifinddo.sty] -\title{\textsf{fifinddo}\\---\\Filtering \TeX(t) Files by - \TeX\thanks{This file describes -% \protect\GetFileInfo{\jobname.sty}% - version \fileversion\ of \textsf{\filename} as of \filedate.}} - %% ^ 2010/11/26 -% \listfiles -\documentclass{article} -\usepackage{makedoc} -% \usepackage{substr} %% for failure examples TODO 2010/03/17 -\input{makedoc.cfg} -%% <- TODO -> makedoc.cfg -\usepackage{readprov} -\ReadPackageInfos{fifinddo} -% \ReadFileInfos{fifinddo.sty} -% \hypersetup{pdfstartview=FitH} %% fine! 2010/11/11 -\begin{document} -% \GetFileInfo{fifinddo.sty} %% 2010/11/25/26 -\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} -%% done, moving to .sty 2010/04/06: -% 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, - 'parselines' 2010/11/13 - -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 -2010/04/06 possible uses of reading TeX category codes moved to .sty -2010/11/11 \thanks <- package version -2010/11/12 package date updated, \author -> makedoc.cfg -2010/11/13 package date updated; parselines -2010/11/24 debugging -2010/11/25f. using readprov.sty -2010/11/27 reworked \ProvidesFile diff --git a/Master/texmf-dist/doc/latex/nicetext/docsrc/gather.tex b/Master/texmf-dist/doc/latex/nicetext/docsrc/gather.tex deleted file mode 100644 index 5a14c651361..00000000000 --- a/Master/texmf-dist/doc/latex/nicetext/docsrc/gather.tex +++ /dev/null @@ -1,8 +0,0 @@ -\RequirePackage{myfilist} -\ProvidesFile{gather.tex}[2010/11/27 collect file infos] -\EmptyFileList %%% [readprov.sty,myfilist.sty] -% \ReadPackageInfos{readprov,myfilist} -\ReadPackageInfos{fifinddo,makedoc,niceverb,wiki} -\ReadFileInfos{fifinddo,makedoc,niceverb,makedoc.cfg,mdoccorr.cfg} %%% ,mdoccheat,wikicheat} -\ReadFileInfos{gather} -\ListInfos[FileList.txt] diff --git a/Master/texmf-dist/doc/latex/nicetext/docsrc/makedoc.tex b/Master/texmf-dist/doc/latex/nicetext/docsrc/makedoc.tex deleted file mode 100644 index b6c78135c42..00000000000 --- a/Master/texmf-dist/doc/latex/nicetext/docsrc/makedoc.tex +++ /dev/null @@ -1,646 +0,0 @@ -\ProvidesFile{makedoc.tex}[2011/01/25 documenting makedoc.sty] -\RequirePackage{makedoc} -\documentclass{article} -\input{makedoc.cfg} -\usepackage{color} %% 2011/01/25 -\sfcode`/=1001 %% TODO makedoc.cfg!? 2010/03/21 niceverb!? 2011/01/25 -\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\thanks{% - This document describes %% 2011/01/25 - version~\textcolor{blue}{\UseVersionOf{makedoc.sty}} - of 'makedoc.sty' as of \UseDateOf{makedoc.sty}.}} -\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 -2010/11/27 \ProvidesFile for myfilist -2011/01/25 \thanks with readprov.sty diff --git a/Master/texmf-dist/doc/latex/nicetext/docsrc/mdoccheat.tex b/Master/texmf-dist/doc/latex/nicetext/docsrc/mdoccheat.tex deleted file mode 100644 index 029bf243bf8..00000000000 --- a/Master/texmf-dist/doc/latex/nicetext/docsrc/mdoccheat.tex +++ /dev/null @@ -1,104 +0,0 @@ -\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 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 - diff --git a/Master/texmf-dist/doc/latex/nicetext/docsrc/wikicheat.tex b/Master/texmf-dist/doc/latex/nicetext/docsrc/wikicheat.tex deleted file mode 100644 index e56bff99120..00000000000 --- a/Master/texmf-dist/doc/latex/nicetext/docsrc/wikicheat.tex +++ /dev/null @@ -1,148 +0,0 @@ -\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} - diff --git a/Master/texmf-dist/doc/latex/nicetext/doc/fifinddo.pdf b/Master/texmf-dist/doc/latex/nicetext/fifinddo.pdf Binary files differindex 7551e473cd7..7551e473cd7 100644 --- a/Master/texmf-dist/doc/latex/nicetext/doc/fifinddo.pdf +++ b/Master/texmf-dist/doc/latex/nicetext/fifinddo.pdf diff --git a/Master/texmf-dist/doc/latex/nicetext/doc/makedoc.pdf b/Master/texmf-dist/doc/latex/nicetext/makedoc.pdf Binary files differindex d2e6a4a2be9..d2e6a4a2be9 100644 --- a/Master/texmf-dist/doc/latex/nicetext/doc/makedoc.pdf +++ b/Master/texmf-dist/doc/latex/nicetext/makedoc.pdf diff --git a/Master/texmf-dist/doc/latex/nicetext/doc/mdoccheat.pdf b/Master/texmf-dist/doc/latex/nicetext/mdoccheat.pdf Binary files differindex 1ead8986302..1ead8986302 100644 --- a/Master/texmf-dist/doc/latex/nicetext/doc/mdoccheat.pdf +++ b/Master/texmf-dist/doc/latex/nicetext/mdoccheat.pdf diff --git a/Master/texmf-dist/doc/latex/nicetext/doc/niceverb.pdf b/Master/texmf-dist/doc/latex/nicetext/niceverb.pdf Binary files differindex a1fa66d2e67..a1fa66d2e67 100644 --- a/Master/texmf-dist/doc/latex/nicetext/doc/niceverb.pdf +++ b/Master/texmf-dist/doc/latex/nicetext/niceverb.pdf diff --git a/Master/texmf-dist/doc/latex/nicetext/doc/wikicheat.pdf b/Master/texmf-dist/doc/latex/nicetext/wikicheat.pdf Binary files differindex 481c7e314d4..481c7e314d4 100644 --- a/Master/texmf-dist/doc/latex/nicetext/doc/wikicheat.pdf +++ b/Master/texmf-dist/doc/latex/nicetext/wikicheat.pdf |