| 1 |
\ProvidesFile{niceverb.tex}[2014/03/28 documenting niceverb.sty] |
| 2 |
\title{\textsf{niceverb.sty}\\---\\Minimizing |
| 3 |
Markup\\for Documenting \LaTeX\ packages\thanks{This |
| 4 |
document describes version |
| 5 |
\textcolor{blue}{\UseVersionOf{niceverb.sty}} |
| 6 |
of \pkgnamefmt{niceverb.sty} as of \UseDateOf{niceverb.sty}.} |
| 7 |
} |
| 8 |
% \listfiles 2010/03/19 |
| 9 |
{ \RequirePackage{makedoc} \ProcessLineMessage{} %% 2010/03/11 |
| 10 |
\MakeJobDoc{19}{\SectionLevelThreeParseInput} } |
| 11 |
\documentclass[fleqn]{article}%% TODO paper dimensions!? |
| 12 |
\input{makedoc.cfg} %% shared formatting settings |
| 13 |
\newcommand*{\secref}[1]{Sec.~\ref{sec:#1}} %% 2014/03/27 |
| 14 |
%% 2011/08/22: |
| 15 |
\MDkeywords{literate programming, syntactic sugar, |
| 16 |
.txt to .tex enhancement, macro programming} |
| 17 |
\hypersetup{%% was `syntacic' 2011/10/07: |
| 18 |
% pdftitle=syntactic sugar for LaTeX documentation by niceverb.sty, |
| 19 |
%% <- 2011/11/05 -> |
| 20 |
pdftitle=niceverb.sty: syntactic sugar for LaTeX documentation, |
| 21 |
pdfsubject=documenting niceverb.sty |
| 22 |
}%% /2011/08/22 |
| 23 |
\begin{document} |
| 24 |
\maketitle |
| 25 |
\begin{MDabstract} |
| 26 |
% \tracingmacros=1 \tracingonline=1 |
| 27 |
'niceverb.sty' provides very decent syntax (through active characters) |
| 28 |
for describing \LaTeX\ packages and the syntax of macros conforming to |
| 29 |
\LaTeX\ syntax conventions. |
| 30 |
\end{MDabstract} |
| 31 |
\tableofcontents |
| 32 |
|
| 33 |
%% TODO table listing of active characters |
| 34 |
%% Were tests 2010/03/08: |
| 35 |
% \section{Presenting Nasty's `Nasty' ``Nasty'' &\NVerb\ 'niceverb'} |
| 36 |
% \section{Presenting \cs{NVerb} 'niceverb'} |
| 37 |
\section{Presenting 'niceverb'} |
| 38 |
\subsection{Purpose} |
| 39 |
% \begin{abstract}\noindent |
| 40 |
% The 'nicetext' bundle provides ``minimal" markup |
| 41 |
The 'niceverb' package provides ``minimal" markup for documenting \LaTeX\ |
| 42 |
packages, reducing the number of keystrokes/visible characters needed |
| 43 |
% .\,.\,. %%% ... %% TODO nicedots |
| 44 |
(kind of poor man's \acro{WYSIWYG}).\footnote{``What you see is what you |
| 45 |
get." Novices are always warned that \acro{WYSIWYG} is essentially |
| 46 |
impossible with \LaTeX.} %% TODO UK FAQ 2010/03/11 |
| 47 |
% One feature---\verb'&\foo'%%% badly self-documenting, `&' fails |
| 48 |
It conveniently handles command names in arguments of macros |
| 49 |
such as &\footnote or even of sectioning commands. |
| 50 |
% (`.aux'/`.toc' entries). |
| 51 |
% |
| 52 |
% This is done by making some characters active. |
| 53 |
% 'niceverb.sty' thus resembles 'wiki.sty'; both are siblings. |
| 54 |
% \end{abstract} |
| 55 |
If you use 'makedoc.sty' additionally, commands for typesetting a |
| 56 |
package's code are inserted automatically (just using \TeX). |
| 57 |
%%% \footnote{Stephan I. B\"ottcher used |
| 58 |
%%% 'awk' instead to typeset the documentation of his 'lineno.sty'.} |
| 59 |
As opposed to tools that are rather common on UNIX/Linux, this |
| 60 |
operation should work at any \TeX\ installation, irrespective of |
| 61 |
platform. |
| 62 |
|
| 63 |
Both packages may at least be useful while working at a very new package |
| 64 |
and may suffice with small, simple packages. After having edited your |
| 65 |
package's code |
| 66 |
%% <jobname> 2010/02/28: |
| 67 |
(typically in a `.sty' file---<jobname>`.sty'), |
| 68 |
you just ``{`latex'}" the manual file |
| 69 |
(maybe some `.tex' file---<jobname>`.tex') |
| 70 |
and get instantly the corresponding updated documentation. |
| 71 |
|
| 72 |
'niceverb' and 'makedoc' may also help to generate without much effort |
| 73 |
documentations of nowadays commonly expected typographical quality for |
| 74 |
packages that so far only had plain text documentations. |
| 75 |
|
| 76 |
\subsection{Acknowledgement/Basic Ideas} |
| 77 |
\emph{Four} %% 2011/01/26 |
| 78 |
ideas of Stephan I. B\"ottcher's in documenting his |
| 79 |
\ctanpkgref{lineno} inspired the present work: |
| 80 |
\begin{enumerate} |
| 81 |
\item |
| 82 |
The markup and its definitions are short and simple, |
| 83 |
markup commands are placed at the right ``margin" |
| 84 |
of the ASCII file, |
| 85 |
so you hardly see them in reading the source file, |
| 86 |
you rather just read the text that will be printed. |
| 87 |
\item |
| 88 |
An 'awk' script removes the `%'s starting \emph{documentation} lines |
| 89 |
and inserts the commands for typesetting the package's \emph{code} |
| 90 |
(you don't see these commands in the source).\footnote{The |
| 91 |
corresponding part of the ``present work" is 'makedoc.sty'.} |
| 92 |
%% <- clarified 2010/03/11 |
| 93 |
\item |
| 94 |
An active character (\lq&|\rq) issues a `\string' \emph{and} switches |
| 95 |
to typewriter typeface for typesetting a command verbatim---so this |
| 96 |
works without changing category codes (which is the usual idea of |
| 97 |
typesetting code), therefore it works even in macro arguments. |
| 98 |
\item %% 2011/01/26 |
| 99 |
\lq\HardNVerb+<meta-variable>+\rq\ produces \lq<meta-variable>\rq. |
| 100 |
(\qtd{&\lt} stores the original \qtd{&<}.) %% was \lessthan 2014/03/28 |
| 101 |
\end{enumerate} |
| 102 |
|
| 103 |
\subsection{The Commands and Features of 'niceverb'} |
| 104 |
Actually, it is the main purpose of 'niceverb' to save you from |
| 105 |
``commands" $\dots$\par |
| 106 |
Single quotes &`, &', ``less than" &< (accompanied |
| 107 |
with `>'), the ``vertical" &|, the hash mark `#', ampersand `&', |
| 108 |
and in an extended ``auto mode" even backslash `\' become `\active' |
| 109 |
characters with ``special effects." |
| 110 |
% \qtd{&|$\dots$&|} (i.e., \GenCmdBox+|<code>|+) in general |
| 111 |
% should highlight descriptions of user commands and their syntax. |
| 112 |
|
| 113 |
The package mainly aims at typesetting commands and descriptions of their |
| 114 |
syntax \emph{if the latter is ``standard \LaTeX-like"}, |
| 115 |
using ``meta-variables." A string to be |
| 116 |
typeset ``verbatim" thus is assumed to start with a single command like |
| 117 |
&\foo, maybe followed by stars (\lq`*'\rq) and pairs of |
| 118 |
square brackets (\lq`['<opt-arg>`]'\rq) |
| 119 |
or curly braces (\lq`{'<mand-arg>`}'\rq), |
| 120 |
where those pairs contain strings indicating the typical |
| 121 |
kinds of contents for the respective arguments of that command. |
| 122 |
A typical example is this: |
| 123 |
\[\InlineCmdBox{&\foo*[<opt-arg>]{<mand-arg>}}\] |
| 124 |
This was achieved by typing |
| 125 |
\[\HardVerbBox+&\foo*[<opt-arg>]{<mand-arg>}+\] |
| 126 |
In ``auto mode" of the package, even typing |
| 127 |
% \tracingmacros=1 \tracingonline=1 |
| 128 |
\[\HardVerbBox+\foo*[<opt-arg>]{<mand-arg>}+\] |
| 129 |
would have sufficed---\acro{WYSIWYG}! I call such mixtures of |
| 130 |
\emph{verbatim} and ``meta-variables" \textit{\qtd{meta-code}}. |
| 131 |
|
| 132 |
Outside macro arguments, you obtain the same by typing |
| 133 |
% \[\verb+`\foo*[<opt-arg>]{<mand-arg>}'+\] |
| 134 |
\[\HardVerbBox+`\foo*[<opt-arg>]{<mand-arg>}'+\] |
| 135 |
|
| 136 |
Details: |
| 137 |
\begin{description} |
| 138 |
|
| 139 |
\item[``Meta-variables:"] The package supports the ``angle |
| 140 |
brackets" style of ``meta-variables" (as with <meta-variable>). |
| 141 |
You just type \lq\verb'<bar>'\rq\ to get \lq<bar>\rq. |
| 142 |
|
| 143 |
This works due to a sloppy variant `\NVerb' of `\verb' |
| 144 |
which doesn't care about possible ligatures and definitions of active |
| 145 |
characters. Instead, it assumes that the ``verbatim" font doesn't |
| 146 |
contain ligatures anyway.\footnote{On the other hand, &\NVerb is more |
| 147 |
\emph{careful} with 'niceverb''s special characters.} |
| 148 |
\lq\verb'\verb+<foo>+'\rq, by contrast, just yields \lq\verb'<foo>'\rq. |
| 149 |
|
| 150 |
Almost the same feature is offered by 'ltxguide.cls' which formats the |
| 151 |
basic guides from the \LaTeX\ Project Team. The present feature, |
| 152 |
however, also works in plain text outside verbatim mode. |
| 153 |
% On the other hand: without << feature |
| 154 |
|
| 155 |
\item[Single quotes (left/right) for ``short verb:"] |
| 156 |
The package ``assumes" that \emph{quoting} refers to |
| 157 |
\emph{code}, therefore \lq\verb+`foo'+\rq\ is typeset as |
| 158 |
\lq`foo'\rq, or (generally) |`<content>'| turns <content> |
| 159 |
into meta-code with the meta-variable feature as above. |
| 160 |
This somewhat resembles the &\MakeShortVerb feature of 'doc.sty'. |
| 161 |
%% Moved up here 2010/02/28: |
| 162 |
You can ``abuse" our %%% ``single quotes" |
| 163 |
feature just to get typewriter |
| 164 |
typeface.{\sloppy\par}%% not so useful here 2010/02/28: |
| 165 |
% \footnote{In macro arguments this requires that the right |
| 166 |
% single quote &' is &\active.} |
| 167 |
|
| 168 |
Problems with this feature will typically arise %%% fail %% 2010/02/28 |
| 169 |
when you try |
| 170 |
to typeset commands (and their syntax) in \emph{macro arguments}---e.g., |
| 171 |
$$\verb+\footnote{`\bar' is a celebrated fake example!}+$$ |
| 172 |
will try to \emph{execute} &\bar instead of typesetting it, giving |
| 173 |
an ``undefined" error or so. %% TODO try! 2010/02/28 |
| 174 |
\verb+\verb+ fails in the same situation, for the same reason. |
| 175 |
\lq\verb+&+\rq\ (&\footnote{&&&\bar<remaining>}) or |
| 176 |
``auto mode" (see below) may then work better.\footnote{&\bar indeed!} |
| 177 |
More generally, the quoting feature still works in macro arguments in |
| 178 |
the sense that you then have to mark difficult characters with `&' |
| 179 |
(simply as short for `\string'). However, it still won't work with |
| 180 |
curly braces that don't follow a command name |
| 181 |
(such \emph{pairs} of braces will simply get lost, |
| 182 |
\emph{single} braces will give errors or so).%%%\footnote{`{group}'} |
| 183 |
|
| 184 |
Double quotes and apostrophes should still work the usual way. |
| 185 |
% %% TODO doesn't work, inside runs into `}' 2010/02/28: |
| 186 |
% otherwise you could control the parsing mechanisms using curly braces |
| 187 |
% (outside and inside don't interact: `Harry{'}s' for \qtd{Harry's}). |
| 188 |
For difficult cases, you can still use the standard `\verb' |
| 189 |
command from \LaTeX. |
| 190 |
To get \emph{usual} single quotes, you can use their standard substitutes |
| 191 |
`\lq' and `\rq', or for pairs of them, |
| 192 |
|\qtd{<text>}| in place of `\lq <text>\rq'---or even `\lq <text>\rq\ '. |
| 193 |
To get single quotes around some verbatim <verb>, |
| 194 |
often `\qtd{&<verb>}' works. |
| 195 |
It is for this reason that I have refrained from different |
| 196 |
solutions as in \ctanpkgref{newverbs} (so far). |
| 197 |
|
| 198 |
%% 2012/10/10: |
| 199 |
v0.44 provides |\AddQuotes| after which single quotes \emph{both} |
| 200 |
turn their content into metacode \emph{and print} single quotes |
| 201 |
around them \emph{automatically.} This can be turned off again by |
| 202 |
|\DontAddQuotes|. |
| 203 |
|
| 204 |
\item[Single right quotes for &\textsf:] |
| 205 |
Package names are (by some convention I often yet not always |
| 206 |
see working) |
| 207 |
typeset with `\textsf'; |
| 208 |
it was natural to use a remaining case of using single quotes |
| 209 |
for abbreviating $$&\textsf{<text>}$$ by |'<text>'|. |
| 210 |
% \footnote{% |
| 211 |
% Font switching by sequences of single quotes is a feature of the |
| 212 |
% syntax for editing \textit{Wikipedia} pages and of 'wiki.sty'.} |
| 213 |
%% <- undoubled 2010/02/28 -> |
| 214 |
This idea of switching fonts continues font switching of 'wiki.sty' |
| 215 |
which uses the syntax for editing {\it Wikipedia} pages |
| 216 |
(font switching by sequences of right single quotes). |
| 217 |
|
| 218 |
\item[Verticals for setting-off command descriptions:]%%% |
| 219 |
\hskip0pt plus 2em |
| 220 |
\GenCmdBox+|<code>|+ works like \qtd{&`<code>&'} except putting |
| 221 |
the result into a \emph{framed box} (just as all around |
| 222 |
here)---or something else that you can achieve using some \emph{hooks} |
| 223 |
described with the implementation. There are variants like |
| 224 |
\GenCmdBox+\cmdboxitem|<code>|+. |
| 225 |
|
| 226 |
\item[Ampersand shows command syntax \&c. even in arguments:] |
| 227 |
\hfil E.g., type \lq\verb+&\foo{<arg>}+\rq\ to get |
| 228 |
\lq`\foo{<arg>}'\rq. This may be even more convenient for typing than |
| 229 |
the single quotes method, although looking somewhat strange. |
| 230 |
However, in macro arguments this does not work with |
| 231 |
\emph{private letters} (`@' and `_' here), for this case, |
| 232 |
use |\cs{<characters>}| or |\cstx{<characters>}<parameters>|.%%% |
| 233 |
% `&' may terminate \textit{verbatim} unexpectedly, being designed for |
| 234 |
% displaying ``\LaTeX-like command syntax" in the first instance. |
| 235 |
\footnote{Moreover, && currently has a limited 'xspace' |
| 236 |
functionality only.}%%%\footnote{You can even use && for referring to |
| 237 |
% active characters like && in footnotes etc.!} |
| 238 |
%% <- said elsewhere now 2010/03/07 |
| 239 |
|
| 240 |
\begin{sloppypar} |
| 241 |
This choice of `&' rests on the assumption that there won't be many |
| 242 |
tables in the documenation. You can restore the usual meaning of `&' |
| 243 |
by `\MakeNormal\&' and turn the present special meaning on again by |
| 244 |
\[`\MakeActive\&' \mbox{\quad or\quad } |
| 245 |
`\MakeActiveLet\&\CmdSyntaxVerb'\] |
| 246 |
You could also |
| 247 |
redefine (&\renewcommand) &\descriptionlabel using `\CmdSyntaxVerb' |
| 248 |
(the ``normal command" that is equivalent to `&', its ``permanent |
| 249 |
alias") |
| 250 |
so \verb+\item[\foo]+ works as wanted. |
| 251 |
\end{sloppypar} |
| 252 |
|
| 253 |
\textbf{Another} feature of 'niceverb''s `&' is getting |
| 254 |
(some of the) special characters %% 2010/03/20 |
| 255 |
(as listed in the standard macro `\dospecials') verbatim in arguments |
| 256 |
(where `\verb' and the like fail). It just acts similarly as \TeX's |
| 257 |
%% undoubled lines 2011/05/09 |
| 258 |
primitive `\string' (which it actually invokes---cf. discussion on the |
| 259 |
left quote feature above). |
| 260 |
|
| 261 |
\item[``Auto mode" typesets commands verbatim unless .\,.\,.] |
| 262 |
\begin{sloppypar} |
| 263 |
In~``auto mode," the backslash \lq`\'\rq\ is an active character that |
| 264 |
builds a command name from the ensuing letters and typesets the |
| 265 |
command (and its syntax, allowing meta-variables) verbatim. |
| 266 |
However, there are some exceptions, which are collected in a macro |
| 267 |
|\niceverbNoVerbList|. &\begin, &\end, and &\item belong to this list, |
| 268 |
you can redefine (`\renewcommand') it, or add <macros> to it by |
| 269 |
|\AddToNoVerbList}{<macros>}| %% 2010/12/29 |
| 270 |
There is also a command |\NormalCommand{<letters>}| \emph{issuing} the |
| 271 |
command `\<letters>' instead of typesetting it. |
| 272 |
Since auto mode is somewhat dangerous, you have to start it explicitly |
| 273 |
by |\AutoCmdSyntaxVerb|. You can end it by |\EndAutoCmdSyntaxVerb|. |
| 274 |
|\AutoCmdInput{<file>}| is probably most important. |
| 275 |
\end{sloppypar} |
| 276 |
|
| 277 |
Auto mode is motivated by the observation that there are package files |
| 278 |
containing their documentation as pure (well-readable) ASCII |
| 279 |
text---contain\-ing the names of the new commands without any kind of |
| 280 |
quotation marks or verbatim commands. |
| 281 |
Auto mode should typeset such documentation just from the same ASCII |
| 282 |
text. |
| 283 |
|
| 284 |
\item[Hash mark \lq&#\rq\ comes verbatim.] |
| 285 |
No macro definitions are expected in the `document' |
| 286 |
environment.\footnote{This idea appeared 2009 on the 'LATEX-L' |
| 287 |
mailing list. It may be wrong, |
| 288 |
as I have sometimes experienced $\dots$} |
| 289 |
%% <- changed 2010/03/11 |
| 290 |
Rather, \lq`#'\rq\ is an active character for taking the next |
| 291 |
character (assuming it is a digit) to form a reference to a |
| 292 |
\emph{macro parameter}---\lq`#1'\rq\ becomes \lq#1\rq\---\acro{WYSIWYG} |
| 293 |
indeed! (So the general syntax is |#<digit>|.) |
| 294 |
\item[Escaping from 'niceverb' (generally).] |
| 295 |
To get rid of the functionality of some active character <char> |
| 296 |
(\qtd{&&}, single quote, ampersand, hash mark---not |
| 297 |
``auto mode," see above) here, use |\MakeNormal\<char>|---may |
| 298 |
be within a group. To revive it again, use |\MakeActive\<char>|. |
| 299 |
This may fail when a different package overtook the active <char> |
| 300 |
(but I expect more failures then), in this case |
| 301 |
|\MakeActiveLet\<char>\<perm-alias>| |
| 302 |
revives the 'niceverb' meaning of <char> |
| 303 |
where `\<perm-alias>' is the ``permanent alias" for that active |
| 304 |
<char> according to the documentation below. |
| 305 |
E.g., `\LQverb' is the ``permanent alias" for active single left |
| 306 |
quote, 'niceverb' activates it by |
| 307 |
\NVerb+\MakeActiveLet\'\LQverb+.---You can turn off 'niceverb' |
| 308 |
syntax \emph{alltogether} by |\noNiceVerb| and revive it |
| 309 |
by |\useNiceVerb| (without ``auto mode").{\sloppy\par} |
| 310 |
|
| 311 |
\strong{Right Quotes:} Disabling\slash reviving replacement |
| 312 |
of `\textsf' by single right quotes requires |
| 313 |
\[|\nvRightQuoteNormal| \mbox{\quad or\quad } |\nvRightQuoteSansSerif|\] |
| 314 |
%% 2014/03/27: |
| 315 |
respectively.---The feature fails in certain occasions |
| 316 |
because a single right quote must not always be interpreted |
| 317 |
as `\textsf', and deciding this by macros became quite |
| 318 |
laborious for me and is most likely still not perfect. |
| 319 |
There is a command |\nvAllRightQuotesSansSerif| |
| 320 |
to be used with care that interpretes \emph{all} single |
| 321 |
right quotes as `\textsf', which, e.g., means that you |
| 322 |
must use `\rq' for apostrophes. |
| 323 |
|
| 324 |
\strong{``Moving" arguments:} %% 2014/03/27 |
| 325 |
|\NiceVerbMove{<text>}| with v0.6 is for ``moving" arguments so that |
| 326 |
'niceverb' syntax operates \emph{locally} at the destination |
| 327 |
(table of contents or page headings). |
| 328 |
It is automatically used by 'niceverb''s variant of \LaTeX's |
| 329 |
sectioning commands; while with `\markboth', `\markright', |
| 330 |
`\addcontentsline' etc.\ you must it include yourself |
| 331 |
(currently, \TODO?). |
| 332 |
\end{description} |
| 333 |
|
| 334 |
\subsection{Examples} |
| 335 |
The file 'mdoccorr.cfg' providing some `.txt'$\to$\LaTeX\ |
| 336 |
functionality---i.e., typographical corrections---documents itself |
| 337 |
using 'niceverb' syntax. Its code and the documentation that is |
| 338 |
typeset from it are in the \qtd{examples} section of |
| 339 |
'makedoc.pdf'.---Moreover, |
| 340 |
the documentation 'niceverb.pdf' of 'niceverb.sty' was |
| 341 |
typeset from 'niceverb.tex' and 'niceverb.sty' using 'niceverb' |
| 342 |
syntax, likewise 'fifinddo.pdf' and 'makedoc.pdf'. |
| 343 |
The example of 'niceverb' shows the most frequent use of the `&' |
| 344 |
feature.{\sloppy\par} |
| 345 |
|
| 346 |
'nicetext' bundle release v0.4 contains a file 'substr.tex' |
| 347 |
that should typeset the documentation of the version of |
| 348 |
Harald Harders' |
| 349 |
'substr.sty'\footnote{\url{http://ctan.org/pkg/substr}} |
| 350 |
that your \TeX\ finds first, as well as 'arseneau.tex' |
| 351 |
typesetting a few packages by Donald Arseneau. |
| 352 |
The outcomes (with me) are 'substr.pdf' and 'arseneau.pdf'. |
| 353 |
These are the first applications of 'niceverb''s ``auto mode" to |
| 354 |
(unmodified) third-party package files. |
| 355 |
(I also made a more ambitious documentation of Donald Arseneau's |
| 356 |
'import.sty v3.0' before I found that CTAN already has a nicely |
| 357 |
typeset documentation of 'import.sty v5.2'.) |
| 358 |
|
| 359 |
%% removed 2010/03/11: |
| 360 |
% It seems to me that I could type so many pages on 'fifinddo' and |
| 361 |
% 'makedoc' in little more than a week |
| 362 |
% % (2009/04/12, much of which was needed for debugging and reworking concepts) |
| 363 |
% only due to the ``minimal" \emph{verbatim} and syntax-display syntax. |
| 364 |
% |
| 365 |
\subsection{What is Wrong with the Present Version} |
| 366 |
\begin{enumerate} |
| 367 |
\item 'niceverb.sty' should be an extension of 'wiki.sty'; |
| 368 |
yet their font selection mechanisms are currently not compatible. |
| 369 |
%% 2010/02/28: |
| 370 |
Especially, the feature of \[\hbox\bgroup|''<text>''|\egroup\] |
| 371 |
%% <- failed with \mbox as of 2010/03/23, first two rq missing |
| 372 |
%% 2010/03/29 |
| 373 |
replacing |
| 374 |
`\textit{<text>}' or `\emph{<text>}' may be considered missing. |
| 375 |
\item Font switching or horizontal spacing may fail in certain |
| 376 |
situations. |
| 377 |
% (parentheses, titles, footnotes; |
| 378 |
You can correct spacing by \lq`\ '\rq. |
| 379 |
%% <- \qtd{`&\ '}. |
| 380 |
% \item |
| 381 |
% The feature of mixing high-quality-typeset comments into the |
| 382 |
% package code listing is implemented in a very rudimentary way only. |
| 383 |
% % just allowing for `\subsection's. |
| 384 |
% The ``comment detector" detects Wikipedia-style subsection titles |
| 385 |
% instead of lines beginning with percent characters.\footnote{% |
| 386 |
% Percent characters will definitely not be ``ignored" as with &\DocInput, |
| 387 |
% rather they will hide rests of \emph{documentation} lines as usually, |
| 388 |
% while they will be typeset verbatim in \emph{package code} lines.} |
| 389 |
% Switching between plain and verbatim typesetting in the package |
| 390 |
% listings isn't settled yet, since there are different styles of using |
| 391 |
% percent symbols. I have sometimes used double percent symbols |
| 392 |
% (\lq\verb+%%+\rq) |
| 393 |
% for commenting text and single ones just for ``reversible deletion of |
| 394 |
% code," while usually single percent symbols indicate commenting text |
| 395 |
% indeed. Double percent symbols may, by contrast, mean that the text remains |
| 396 |
% visible in the `.sty' file only, suppressed in the typeset |
| 397 |
% documentation ('lineno.sty'). |
| 398 |
% For a while, it may be necessary to provide replacing macros for each |
| 399 |
% package separately instead of providing a single macro package |
| 400 |
% managing all of them. |
| 401 |
% \item |
| 402 |
% The code listing currently uses the `listing' and `listingcont' |
| 403 |
% environments of 'moreverb.sty'; |
| 404 |
% the code font and the line numbers may be too large. |
| 405 |
\item The ``vertical" character \qtd{&|} produces inline boxes |
| 406 |
only at present. It might as well provide a version of the |
| 407 |
`decl' tabular environment of 'ltxguide.cls'. |
| 408 |
%% changes 2010/03/10 |
| 409 |
% coloured\slash framed boxes instead (2009/04/09). They have |
| 410 |
% their merits! See 'fifinddo.pdf' and 'makedoc.pdf'. However, |
| 411 |
% they |
| 412 |
The inline boxes |
| 413 |
badly deal with long command names and many arguments. |
| 414 |
Doubled verticals could ensure the `decl' mode. |
| 415 |
Moreover, such a box might issue an \emph{index} entry. |
| 416 |
\item One may have \emph{opposite} ideas about using quotes---maybe |
| 417 |
rather `"<code>"' should typeset <code> \textit{verbatim}. |
| 418 |
There might be a package option for this. If ordinary |
| 419 |
\qtd{\NVerb'``<text>"'} still should work, awful tricks as now with |
| 420 |
the right quote feature would be needed. %% TODO 2010/03/06 |
| 421 |
% \item ``Auto mode" has \emph{not} been tested on a serious application yet. |
| 422 |
%% partially improved 2010/02/28: |
| 423 |
% \item % 'niceverb''s font switching tricks sometimes turn against their |
| 424 |
% % inventor (and other users?). There must be some switching |
| 425 |
% % ``off'' (and ``on'' again).% |
| 426 |
% % \footnote{\hspace{1sp}'fifinddo'\slash\hspace{1sp}'makedoc' |
| 427 |
% % %% <- TODO oh, oh! 2009/04/11 |
| 428 |
% % allow inserting such commands from a driver script, |
| 429 |
% % invisible in the file that contains the ``contentual'' |
| 430 |
% % documentation.} |
| 431 |
% % Also, there |
| 432 |
% There |
| 433 |
% might better help with weird errors, |
| 434 |
% some syntax checks might intercept earlier. |
| 435 |
% |
| 436 |
% Similarly, some choices reflect a %% rather OK 2010/02/28 |
| 437 |
% personal style and should be modifiable, especially by package |
| 438 |
% options.\footnote{Please sponsor the project or support it |
| 439 |
% otherwise!} |
| 440 |
\item ``auto mode" seems not to work in section titles. (2011/01/26) |
| 441 |
%% <- noted with edtnotesc |
| 442 |
\item Certain difficulties with typesetting code in macro arguments |
| 443 |
may be overcome easily using $\varepsilon$\mbox{-}\TeX\ |
| 444 |
features, I need to find out $\dots$ |
| 445 |
\end{enumerate} |
| 446 |
|
| 447 |
\newpage %% 2014/03/28 |
| 448 |
\section{The Package File} %% 2014/03/19 |
| 449 |
% \section{The ``Package" File} %% test for page heading 2014/03/24 |
| 450 |
% \section{`nicetext.sty'} %% tests for pageheadings 2014/03/27 |
| 451 |
\subsection{Preliminaries} %% 2014/03/19 |
| 452 |
\subsubsection{File Header} %% 2014/03/19 |
| 453 |
\input{niceverb.doc} |
| 454 |
\end{document} |
| 455 |
|
| 456 |
HISTORY |
| 457 |
|
| 458 |
2009/04/09 adjusted to new doc-generation method |
| 459 |
2009/04/12 examples, 'awk' lower-case |
| 460 |
2009/04/15 example 'mdcorr.cfg', abstract, |
| 461 |
\pagebreak to implementation |
| 462 |
2010/02/27 replaced `|' by `+' with \verb |
| 463 |
so `|' works as announced |
| 464 |
2010/02/28 "Missing:" ''...'' 'wiki' feature, |
| 465 |
somethings aren't missing anymore |
| 466 |
(or otherwise removed); more on quotes; |
| 467 |
applying |...| |
| 468 |
2010/03/05 \SimpleVerb -> \NVerb; after intro on `&' quotes as well |
| 469 |
2010/03/06 typo in ``examples''; removed makedoc.cfg sample; |
| 470 |
more on `&' |
| 471 |
2010/03/07 without \listfiles |
| 472 |
2010/03/09 hyperref ... \input{mdcorr.cfg}!, |...| settled |
| 473 |
2010/03/10 moved pdf stuff to 'makedoc.cfg'; |
| 474 |
do use 'mdcorr.cfg' for demo; future of | |
| 475 |
2010/03/11 applied \MakeJobDoc and shortened preamble; |
| 476 |
various minor doc changes |
| 477 |
2010/03/12 ``Ampersand" improved; \noNiceVerb + \useNiceVerb |
| 478 |
2010/03/14 use \InlineCmdBox and \HardVerbBox; |...| described |
| 479 |
2010/03/18 \AddToMacro; ``auto mode" tested seriously (substr.sty) |
| 480 |
- \AutoCmdInput |
| 481 |
2010/03/19 line break changes; '' -> " |
| 482 |
2010/03/20 testing niceverb v0.31 |
| 483 |
2010/03/23 `mdoccorr.cfg' example again |
| 484 |
2010/03/27 ``auto mode," |
| 485 |
2010/03/29 \mbox -> \hbox in display; arseneau.tex/pdf |
| 486 |
2010/04/05 Harder -> Harders |
| 487 |
2010/11/27 \ProvidesFile for myfilist |
| 488 |
2010/12/29 \AddToNoVerbList |
| 489 |
2011/01/26 using color.sty and readprov.sty; |
| 490 |
ack. Stephan B. for <...>; auto headings issue |
| 491 |
2011/05/09 undoubled lines about `&' |
| 492 |
2011/08/22 using new makedoc.cfg features |
| 493 |
2011/10/07 `syntacic' |
| 494 |
2011/11/05 modified pdftitle |
| 495 |
2012/10/10 \AddQuotes, \DontAddQuotes |
| 496 |
|
| 497 |
FOR V0.6: |
| 498 |
2014/03/19 subsec. Preliminaries, subsubsec. Header, `Implementation |
| 499 |
of the Markup Syntax' -> `The Package File' |
| 500 |
2014/03/24 experiment with former |
| 501 |
2014/03/25 debugging in abstract |
| 502 |
2014/03/26 trying class option `fleqn' / debugging again |
| 503 |
2014/03/27 \secref; |\NiceVerbMove|, |\nvAllRightQuotesSansSerif|; |
| 504 |
tests |
| 505 |
2014/03/28 debugging; \lessthan -> \lt; \newpage |