Edward Welbourne <email@example.com>
Sun, 18 Mar 2001 11:18:36 +0000 (GMT)
Oh, and the argument I missed because it was too obvious and I'm too
exhausted: verbatim means ... verbatim.
If my doc string says client code should ... call #obj.out('\#')# ...
to achieve some effect, I should expect some client code to contain the
even if some authors do realise that the \ should be elided, while
others read the docstring via a rendering tool which elided it for them;
and this will more-or-less certainly be a bug: the string given really
does have a backslash in it and really isn't just '#'. It would have
been better if your tools had forced me to put the fragment in a block,
where I *could* have said::
so would have done so and wouldn't have confused authors of client code.
Likewise - if anything more so - for 'verbatim'.
If you provide a backslash escape mechanism for verbatim and code
fragments, nearly all uses of it will cause bugs (so, in fact, they will
*be* bugs in the docs).
Stinginess with privileges is kindness in disguise.
-- Guide to VAX/VMS Security, Sep. 1984.
s/privilege/feature/ -- Eddy, 2001/March/18.