summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/nicetext/niceverb.tex
blob: 629d240c4583db05127cd983591ce3c77b60c07e (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
\ProvidesFile{niceverb.tex}[2009/04/15 documenting niceverb.sty]
\title{\textsf{niceverb.sty}\\---\\Minimizing 
  Markup\\for Documenting \LaTeX\ packages%%% \thanks{This 
%     manual describes package version
%     version 0.2 as of April 09, 2009%%%\fileversion\ as of \filedate\ 
%     .}}%%%of the package.}%
}
\author{Uwe L\"uck\\{\tt http://contact-ednotes.sty.de.vu}}
\listfiles
  \begingroup %% build niceverb.doc
    \RequirePackage{makedoc}
    \LaTeXresultFile{niceverb.doc} 
    \HeaderLines{19}
    \MainDocParser{\SectionLevelTwoParseInput}
    \MakeDoc{niceverb.sty}
    \CloseResultFile
  \endgroup
% \input{mknvdoc.tex}
\documentclass{article}%% TODO paper dimensions!?
\input{makedoc.cfg}\MakeOther\|%% TODO \verb| 2009/04/09
%% removed 2009/04/09 for makedoc.sty:
% \usepackage{niceverb} 
% \usepackage{moreverb}
% \usepackage{verbatim} 
% \newenvironment{packagecode}
%   {\PackageCode}
%   {\endPackageCode}
% \gdef\PackageCode{\small \listing[5]{1}}
% \gdef\endPackageCode{%
%   \endlisting
%   \global\def\PackageCode{\small \listingcont}%
%   \global\let\endPackageCode\endlistingcont}
% \renewcommand*{\listinglabel}[1]{%
%   \llap{\footnotesize\rmfamily\the#1}\hskip\listingoffset\relax}

\begin{document}
\maketitle

\begin{abstract}\noindent\hspace{1sp}%% exemplifies a problem
'niceverb.sty' provides very decent syntax for describing \LaTeX\ 
packages and the syntax of macros conforming to \LaTeX\ syntax 
conventions. 
\end{abstract}
\tableofcontents

  %% TODO table listing active characters
\section{Presenting 'niceverb'}
\subsection{Purpose}
% \begin{abstract}\noindent
% The 'nicetext' bundle provides ``minimal'' markup 
The 'niceverb' package provides ``minimal'' markup for documenting \LaTeX\ 
packages, reducing the number of keystrokes/visible characters needed
% .\,.\,. %%% ... %% TODO nicedots 
(kind of poor man's WYSIWYG).\footnote{``What you see is what you 
get.'' Novices are always warned that WYSIWYG is essentially 
impossible with \LaTeX.}
% One feature---\verb'&\foo'%%% badly self-documenting, `&' fails
It conveniently handles command names in arguments of macros 
such as &\footnote or even of sectioning commands. 
% (`.aux'/`.toc' entries).
% 
% This is done by making some characters active. 
% 'niceverb.sty' thus resembles 'wiki.sty'; both are siblings. 
% \end{abstract}
If you use 'makedoc.sty' additionally, commands for typesetting a 
package's code are inserted automatically (just using \TeX). 
%%% \footnote{Stephan I. B\"ottcher used
%%% 'awk' instead to typeset the documentation of his 'lineno.sty'.} 
As opposed to tools that are rather common on UNIX/Linux, this 
operation should work at any \TeX\ installation, irrespective of 
platform.

Both packages may at least be useful while working at a very new package 
and may suffice with small, simple packages. After having edited your 
package's code (typically in a `.sty' file), you just ``{`latex'}'' the 
manual file (maybe some `.tex' file) and get instantly the corresponding 
refreshed documentation.

'niceverb' and 'makedoc' may also help to generate without much effort 
documentations of nowadays commonly expected typographical quality for 
packages that so far only had plain text documentations.

\subsection{Acknowledgement/Basic Ideas}
Three ideas of Stephan I. B\"ottcher's in documenting his 'lineno.sty' 
inspired the present work: 
\begin{enumerate}
\item 
The markup and its definitions are short and simple, 
markup commands are placed at the right ``margin'' 
of the ASCII file, 
so you hardly see them in reading the source file, 
you rather just read the text that will be printed. 
\item 
An 'awk' script removes the `%'s starting \emph{documentation} lines 
and inserts the commands for typesetting the package's \emph{code} 
(you don't see them in the source).
\item 
An active character (\lq&|\rq) issues a `\string' \emph{and} switches 
to typewriter typeface for typesetting a command verbatim---so this 
works without changing category codes (which is the usual idea of 
typesetting code), therefore it works even in macro arguments.
\end{enumerate}

\subsection{The Commands and Features of 'niceverb'}

Single quotes \verb|`|, \verb|'|, ``less than'' \verb|<| (accompanied 
with \verb|>|), the hash mark \verb|#|, ampersand \verb|&|, and in an 
extended ``auto mode'' even backslash \verb|\| become &\active 
characters with ``special effects.'' \lq`|'\,.\,.\,.\,`|'\rq\
should highlight descriptions of user commands and their syntax. 

The package mainly aims at typesetting commands and descriptions of their 
syntax \emph{if the latter is ``standard \LaTeX-like''}, 
using ``meta-variables.'' A string to be 
typeset ``verbatim'' thus is assumed to start with a single command like 
&\foo, maybe followed by stars (\lq`*'\rq) and pairs of 
square brackets (`['.\,.\,.`]') or 
curly braces (\verb'{'.\,.\,.\verb'}'), 
where those pairs contain strings indicating the typical 
kinds of contents for the respective arguments of that command.
A typical example is this: 
\[&\foo*[<opt-arg>]{<mand-arg>}\]
This was achieved by typing \[\verb'&\foo*[<opt-arg>]{<mand-arg>}'\]
In ``auto mode'' of the package, even typing 
\[\verb|\foo*[<opt-arg>]{<mand-arg>}|\]
  %% angle brackets feature to be suppressed here!
would have sufficed---WYSIWYG! (I call such mixtures of 
\emph{verbatim} and ``meta-variables'' \textit{\lq meta-code\rq}.)

Now for the details:
\begin{description}

\item[``Meta-variables:''] {\sloppy The package supports the ``angle 
brackets'' style of ``meta-variables'' (as with <meta-variable>). 
You just type \lq\verb'<foo>'\rq\ to get \lq<foo>\rq.\par}

This works due to a sloppy variant &\SimpleVerb of &\verb 
which doesn't care about possible ligatures and definitions of active 
characters. Instead, it assumes that the ``verbatim'' font doesn't 
contain ligatures anyway. \lq\verb'\verb|<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:'']
{\sloppy The package ``assumes'' that \emph{quoting} refers to 
\emph{code}, therefore \lq\verb|`foo'|\rq\ is typeset as 
\lq`foo'\rq. This somewhat resembles the &\MakeShortVerb feature of 
'doc.sty'.\par}

It will typically fail when you try to typeset commands (and their 
syntax) in \emph{macro arguments}---e.g., 
$$\verb|\footnote{`\bar' is a celebrated fake example!}|$$
will try to \emph{execute} &\bar instead of typesetting it, giving 
an ``undefined'' error so.
\verb|\verb| fails in the same situation, for the same reason. 
\lq\verb|&|\rq\ (&\footnote{&&&\bar<remaining>}) or 
``auto mode'' (see below) may then work better.

Double quotes and apostrophes should still work the usual way; 
otherwise you could control the parsing mechanisms using curly braces 
(outside and inside don't interact).
To get usual single quotes, you can use their standard substitutes 
`\lq' and `\rq'. 
You can ``abuse'' this ``single quotes'' feature just to get typewriter 
typeface.\footnote{In macro arguments this requires that the right 
single quote &' is &\active.}
For difficult cases, you can still use the standard `\verb' 
command from \LaTeX.

\item[Single right quotes for &\textsf:]
{\sloppy Package names are (by some unwritten convention!?) 
typeset with `\textsf'; 
it was natural to use a remaining case of using single quotes 
for abbreviating &\textsf{<text>} by \SimpleVerb|'<text>'|.\footnote{%
Font switching by sequences of single quotes is a feature of the 
syntax for editing Wikipedia pages and of 'wiki.sty'.}\par}
%% TODO fails in parentheses due to preserving apostrophes

This idea of switching fonts continues font switching of 'wiki.sty'
which uses the syntax for editing Wikipedia pages. 

\item[Ampersand \lq&&\rq\ typesets command syntax even in arguments:] 
\hfil e.g., type \lq\verb|&\foo{<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, `&' may terminate \textit{verbatim} unexpectedly, being 
designed for displaying ``\LaTeX-like command syntax'' in the first
instance.\footnote{Moreover, && currently has a limited 'xspace' 
functionality only.}\footnote{You can even use && for referring to 
  active characters like && in footnotes etc.!}

\begin{sloppypar}
This choice of `&' rests on the assumption that there won't be many 
tables in the documenation. You can restore the usual meaning of `&' 
by \verb|\MakeAlign\&| and turn the present special meaning on again by 
$$\verb|\MakeActiveLet\&\CmdSyntaxVerb|.$$ 
You could also 
redefine (&\renewcommand) &\descriptionlabel using `\CmdSyntaxVerb' 
(the ``normal command'' equivalent to `&') so \verb|\item[\foo]| works 
as wanted.
\end{sloppypar}

\item[``Auto mode'' typesets commands verbatim unless .\,.\,.]
{\sloppy 
\hfil In~``auto mode'', the backslash \lq`\'\rq\ is an active character that 
builds a command name from the ensuing letters and typesets the 
command (and its syntax, allowing meta-variables) verbatim. 
However, there are some exceptions, which are collected in a macro 
&\niceverbNoVerbList. &\begin, &\end, and &\item belong to this list, 
you can redefine (`\renewcommand') it.
There is also a command &\NormalCommand{<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.\par}

Auto mode is motivated by the observation that there are package files 
containing their documentation as pure (well-readable) ASCII 
text---contain\-ing the names of the new commands without any kind of 
quotation marks or verbatim commands. 
Auto mode should typeset such documentation just from the same ASCII 
text.

\item[Hash mark &# comes verbatim.]
No macro definitions are expected in the `document' 
environment.\footnote{This idea recently appeared on the 'latex-l' 
mailing list. It may be wrong, not sure at the moment, think of 
'latexa.ltx' .\,.\,.} 
Rather, \lq`#'\rq\ is an active character for taking the next 
character (assuming it is a digit) to form a reference to a 
\emph{macro parameter}---\lq`#1'\rq\ becomes \lq#1\rq\ (WYSIWYG 
indeed!). 
\end{description}

\subsection{Examples}
The local configuration file 'mdcorr.cfg' documents itself using 
'niceverb' syntax. Its code and the documentation that is typeset from 
it are at the end of the \lq examples\rq\ section of 'makedoc.pdf'.
(2009/04/15)

Moreover, the documentation 'niceverb.pdf' of 'niceverb.sty' was 
typeset from 'niceverb.tex' and 'niceverb.sty' using 'niceverb' 
syntax, likewise 'fifinddo.pdf' and 'makedoc.pdf'. 
The example of 'niceverb' shows the most frequent use of the `&' 
feature. 

It seems to me that I could type so many pages on 'fifinddo' and 
'makedoc' in little more than a week 
% (2009/04/12, much of which was needed for debugging and reworking concepts) 
only due to the ``minimal'' \emph{verbatim} and syntax-display syntax. 

\subsection{What is Wrong with the Present Version}
\begin{enumerate}
\item 'niceverb.sty' should be an extension of 'wiki.sty'; 
      yet their font selection mechanisms are currently not compatible. 
\item Font switching or horizontal spacing may fail in certain situations
      (parentheses, titles, footnotes; you can correct spacing by 
      \lq`\ '\rq).
  %% TODO 2009/04/10 redefine \noindent, \footnote ... 
  %%                 or use correcting function with 'fifinddo'
% \item 
% The feature of mixing high-quality-typeset comments into the 
% package code listing is implemented in a very rudimentary way only. 
% % just allowing for `\subsection's. 
% The ``comment detector'' detects Wikipedia-style subsection titles 
% instead of lines beginning with percent characters.\footnote{%
% Percent characters will definitely not be ``ignored'' as with &\DocInput, 
% rather they will hide rests of \emph{documentation} lines as usually, 
% while they will be typeset verbatim in \emph{package code} lines.} 
% Switching between plain and verbatim typesetting in the package 
% listings isn't settled yet, since there are different styles of using 
% percent symbols. I have sometimes used double percent symbols 
% (\lq\verb|%%|\rq) 
% for commenting text and single ones just for ``reversible deletion of 
% code,'' while usually single percent symbols indicate commenting text 
% indeed. Double percent symbols may, by contrast, mean that the text remains 
% visible in the `.sty' file only, suppressed in the typeset 
% documentation ('lineno.sty').
% For a while, it may be necessary to provide replacing macros for each 
% package separately instead of providing a single macro package 
% managing all of them. 
% \item 
% The code listing currently uses the `listing' and `listingcont' 
% environments of 'moreverb.sty'; 
% the code font and the line numbers may be too large. 
\item The ``vertical'' character \lq&|\rq\ was planned to be active 
      and provide a version of the `decl' environment of 
      'ltxguide.cls'. Currently 'makedoc.cfg' installs inline, 
      coloured\slash framed boxes instead (2009/04/09). They have 
      their merits! See 'fifinddo.pdf'  and 'makedoc.pdf'. However, 
      they badly deal with long command names and many arguments 
      .\,.\,. (They could also issue an `\index' command!)---Doubled 
      verticals could make the difference, calling a `decl' table 
      indeed. 
\item ``Auto mode'' has not been tested on a serious application yet. 
\item 'niceverb''s font switching tricks sometimes turn against their 
      inventor (and other users?). There must be some switching 
      ``off'' (and ``on'' again).%
        \footnote{\hspace{1sp}'fifinddo'\slash\hspace{1sp}'makedoc'
          %% <- TODO oh, oh! 2009/04/11
          allow inserting such commands from a driver script, 
          invisible in the file that contains the ``contentual'' 
          documentation.}
      Also, there might better help with weird errors, 
      some syntax checks might intercept earlier. 

      Similarly, some choices reflect a 
      personal style and should be modifiable, especially by package 
      options.\footnote{Please sponsor the project or support it 
        otherwise!}
\end{enumerate}

\pagebreak[3] %% 2009/04/15
\section{Implementation of the Markup Syntax}
% \verbatiminput{niceverb.sty}
% \listinginput[5]{1}{niceverb.sty}
\input{niceverb.doc}

%% removed 2009/04/09 for makedoc.sty:
% \section{Code Preparing Source for Typesetting} 
% This is at present in a file `mknvdoc.tex'.
% \listinginput[5]{1}{mknvdoc}
\end{document}

2009/04/09: adjusted to new doc-generation method
2009/04/12: examples, 'awk' lower-case
2009/04/15: example 'mdcorr.cfg', abstract, 
            \pagebreak to implementation