[Doc-SIG] backslashing

[Edward Welbourne]

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
fragment::

        obj.out('\#')

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::

        obj.out('#')

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).

	Eddy.
--
Stinginess with privileges is kindness in disguise.
           -- Guide to VAX/VMS Security, Sep. 1984.
s/privilege/feature/        -- Eddy, 2001/March/18.