[Doc-SIG] Re: POD

[Guido van Rossum]

> It's a simple, subtle change, but it really makes a difference in both
> readability and writeability.  I know that ST is even *more* readable and
> writeable, but I too worry about the ambiguity of overloading apostrophes
> and asterisks.
> 
> The inter-paragraph stuff -- "=head", "=over", and so forth -- I can do
> without.  And most of it would be irrelevant in Python docstrings, since
> they come with context "for free".  I suspect that the only time you really
> need headings (etc.) in docstrings is when you're trying to write a complete
> module man page in docstrings.

Here's an idea.  The ST folks are already considering using <...> as
special markup for URLs.  How about we lobby for changing that to
A<...> where 'A' stands for any single capital letter.  We could still
recognize *emphasis* (and maybe even **strong**, although I don't care
for it), but instead of arguing whether to use '...', `...`, #...#, or
something else for inline literal text, we can use C<...>.

> [...] POD processors (or rather, the Pod::Parser module that I believe made
> it into the standard library in Perl 5.6) would inspect the module whose
> documentation was being parsed to figure out what words ought to be C<code>
> or B<bold> or what-have-you.  However, I didn't stick around to see how the
> holy wars ended -- sanity might have won out.

Ping's doctest seems to do some of this.  But I agree that it
shouldn't be a standard feature.  In some contexts it's quite hard to
know when e.g. "socket" refers to the concept of a socket and when it
refers to a module or function by the same name...

--Guido van Rossum (home page: http://www.python.org/~guido/)