[Doc-SIG] Re: POD (resend)

[Ka-Ping Yee]

Tim Peters wrote:
> rather see no markup at all than that inconsistent gibberish -- Ping can
> figure out what they meant better than they can!

Thank you, Tim. :)

Juergen Hermann wrote:
> And can be very misleading in some cases (I have functions named "text", for 
> example, which could make this text :) quite confusing after formatting).

Not at all.  pydoc only hyperlinks function names if they are immediately
followed by an opening parenthesis.  This aligns with current conventions
for talking about functions.  Class names are indeed hyperlinked if they
are just mentioned, but it is very rare (and i would argue bad practice!)
to choose a class name that is a single uncapitalized common word.

In short, when i made these decisions i tried to be quite conservative,
and to carefully observe existing conventions.  Then i tested these
design choices by running pydoc over the entire standard library and
looking at all of the generated pages.  I was happy with the results,
so i let it go out.

As a general comment, i would recommend this kind of philosophy
(conservative) and testing (extensive) for any proposed markup syntax.

I know i have been very quiet of late on the Doc-SIG; partly this is
because i am so overwhelmed by the traffic here and i want to be
completely up-to-date so i can contribute something intelligent;
partly this is because i am still holding out hope that it is possible
to design a minimal, unambiguous syntax that preserves enough semantic
information to make Guido and Fred happy, and i want to make a good
serious attempt at doing so before i present any ideas.  I think Greg
made a good point about the typability of POD markup, but i prefer to
avoid purely presentational markup.


-- ?!ng