diff options
author | Karl Berry <karl@freefriends.org> | 2010-04-03 15:42:12 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2010-04-03 15:42:12 +0000 |
commit | 14b154c49df4af70e973eeafb54e2f31250aff0e (patch) | |
tree | 3d16bd3f92c8dd87c3475e212fca73e37ce370d7 /Master/texmf-dist/doc/latex/nicetext/docsrc | |
parent | 2a8bfdf220d7f65a85d288b2edef58e46dd9f654 (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')
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} + + + |