[Doc-SIG] Some random thoughts

[Edward Welbourne]

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

Well, if the `something' in question may contain (unprotected) uses of |
but mayn't contain (unprotected) uses of #, then #something# will work
and |something| will be ambiguous; this applies when `something' is an
arbitrary expression written in python (i.e. the stuff one uses in an
in-paragraph code fragment: the use of comments in doc-string code
blocks isn't affected (code *blocks* being introduced other ways, either
by keyword or by >>> and ...) as they're not part of paragraph text).

By contrast, when discussing a set of flag constants to be combined with
bitwise or, one will want to use | in code fragments within the text of
a paragraph, which will cause problems if | is also in use as the
delimiter by which the paragraph tries to spot the end of the code
fragment.  So | is prettier, and sufficient as long as we only care
about indicating identifiers, but totally useless for delimiting code
fragments within paragraphs of doc-string text.

Now, 
 * Ping and others have adequate machinery for spotting identifiers,
   albeit Tibs and I don't like those,
 * I would argue that, for all that they're reputedly rare, we *do* need
   some mechanism for marking up code fragments,
 * identifiers are code fragments too, and most of my objections to
   Ping's heuristics evaporate when they are applied only to the text of
   code fragments (and to other appropriately marked-up pieces of text,
   such as where an argument name appears in the Arguments: block)

> It's mostly aesthetics.
Nope: #code|fragment# is parseable; |code|fragment| is broken.
No code fragment needs to include a # (outside quotes), some code
fragments do need to use bitwise or.
Parsers are not aesthetes.
Not even mostly.

The argument *against* # is aesthetic.
The argument *for* it is practical.
The argument for | is aesthetic and impractical.

Note that | also suffers problems if someone is illustrating a unix
shell command """... to find users of this module, cd to the python
installation directory and use find | xargs grep to hunt for .py files
which import it ...""".  I am a little concerned (non-British
anglophones, please comment - this is not normal UK usage) by the
possibility that some folk may use # to mean `number' in their doc
strings (outside code fragments), which would present a corresponding
deficiency for #.

> we all seem to agree that ' ' is crufty for code markup.
cool.

> Not that we've agreed on an alternative yet <wink>.
OK, am I making any progress towards persuading you ?

> I've also never bought into the whole vspace argument
Fair dinkum.  That one is aesthetic.

> probably because the world I've been bought up in has big screens
while I was brought up with 25-line screens and now exploit big screens
to give me friendly-sized fonts and about 50 lines, but still desire
tight vertical layout - Tibs tells me my habitual use of, e.g.

    try: val = dict[key]
    except KeyError: val = default

is unkind to other pythoneers.  But this one is aesthetic.

> I guess I'm trying to strike a compromise between ultimate simplicity
> and ... monstrosities.
Yup, that's what we're all here for, so thanks for your contribution ;^)

	Eddy.