[Doc-SIG] Re: POD
Guido van Rossum
Fri, 30 Mar 2001 07:19:12 -0500
> 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/)