[Doc-SIG] Some random thoughts

[Laurence Tratt]

Edward Welbourne wrote:

>  * I would argue that, for all that they're reputedly rare, we *do* need
>    some mechanism for marking up code fragments,

OK, I personally can accept the need for arbitrary code fragments. And I can
accept the need for some guesswork in order to pick the identifiers out of
that fragment (some people here may remember me doing this on the LaTeX
documentation some years back... check out the archives). What I worry about
is that I sometimes use <code> type markup for *non* Python stuff, and I
don't really want that to be heuristicised (yeah, I just made that up) in
the same way. So perhaps what we need is a markup for code fragments (and
I'd agree that an identifier could be seen as a special instance of a code
fragment) and something else for genuine <code> markup.

So I have now rather cleverly doubled the problem space. Probably not my
best move.

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

Aesthetes? That's a word and not a Greek island? You can now see why IIRC
Eddy's based in Cambridge and I'm only in London <wink>.

OK, so | can't be used as a code fragment thingy (if we want one). I
originally thought it would only be applied to identifiers anyway...
 
> The argument *against* # is aesthetic.
> The argument *for* it is practical.
> The argument for | is aesthetic and impractical.

I'll take that as a vote against | then :)
 
> 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 ...""".

Woah there... By that token, any single printable character you choose is a
potential Unix command line input. I'm trying to keep things a little
simpler than that (I notice we already seem to have lost everyone else on
this thread, and I'm only just about hanging in here). My first complaint
about StructuredText is that there isn't a protocol for escaping character;
if there is (and there *has* to be in my opinion. It's possibly the biggest
single ommission at the moment), then the problem goes away.

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

I remain mostly confused. Mostly over why we're arguing the toss over a
single character <wink>.

> Tibs tells me my habitual use of, e.g.
> 
>     try: val = dict[key]
>     except KeyError: val = default
> 
> is unkind to other pythoneers.

Yeah, that's fairly evil as is the whitespace abuse <wink>.


tongue-in-cheek-ly y'rs Laurie