[Doc-SIG] Some random thoughts

[Laurence Tratt]

Edward Welbourne wrote:

>> # doesn't seem entirely appropriate ... an attachment to it for
>> delimiting comments ... perhaps |blah| ... TeX heritage IIRC?
> and someone else remarked that in-paragraph code is rare.  So, if it's
> just delimiting *identifiers* that's needed, |blah| will do fine;
> however, this can't be stretched to include the few instances of in-line
> code, whereas #arbitrary.code('fragment')# will be unambiguous (subject to
> `usual' tricks like #recognising('# within a string')# as not a
> terminator); but use of bitwise or in an expression will present a
> problem for |blah| ...

OK, you've lost me here :) All I was suggesting was substituting | for # :
if # can cover something, then I guess | can as well. It's mostly
aesthetics.

Whether | or # should cover identifiers or arbitrary code fragments is
another discussion (I had assumed that | would cover identifiers and we'd
have another mechanism for code fragments: my mistake). In my opinion we
will have to come up with a mechanism for precise specification of remote
identifiers. In English: if a doc string references "a" and a is within the
namespace of the current module/class/method (via imports or other
definitions etc) then I'm happy (my system contains all the information
necessary for this to work as one would expect); if it isn't then I think
I'd need a way of specifying exactly what "a" is referring to so as to avoid
ambiguity.
 
> I'll be well disgruntled if my string *loses its quotes* because
> someone thought they meant `put this in code face'. 

I don't think you need to worry about this: we all seem to agree that ' ' is
crufty for code markup.

Not that we've agreed on an alternative yet <wink>.

>>> If it can't be said with minimal markup, it doesn't belong
>>> in the doc string ...
>> I'm not going to buy that: ...
> sorry, I was paraphrasing Calvin: As far as *I'm* concerned, if
> something is so complicated that you can't exlain it in 10 seconds, then
> it's probably now worth knowing anyway.  I don't buy this either, but it
> *does* contain a grain of truth.

What I would like is something that can be *mostly* understood in a short
space of time (10 seconds is pushing it), but which explains all those nasty
little what-ifs in a more precise way somewhere else.
 
> I really don't see that doc strings need more than structured text; and
> anything which *does*, it seems to me, *is* trying too hard in the wrong
> place; anything which *needs* nested emphasis/strong/... is over-using
> font-changes.

OK, I think I agree with that. Nested font changes are probably evil, but
they weren't my original thinking (I thought | might do for identifiers and
<Code> for code fragments etc. That seemed, by default, to allow nested font
styles).

> There's always out-of-line documentation and cross-references for when
> the information content is just too complex to encode with structured
> text; and those times are exactly when the information, if put into the
> doc-string, would take up so much vspace on screen that the function's
> def line and body get too far separated for practical readability.

I want to keep doc strings as simple as feasible, but I've also never bought
into the whole vspace argument (witness someone's complaint about the
whitespace I use), probably because the world I've been bought up in has big
screens and no line editors <wink>. I guess I'm trying to strike a
compromise between ultimate simplicity, and C++ doc TeX monstrosities
neither of which seems quite appropriate.


Laurie