[Python-Dev] [Doc-SIG] that library reference, again
goodger at python.org
Fri Dec 30 03:58:00 CET 2005
>>> I'm beginning to fear that I've wasted my time on a project
>>> that nobody's interested in.
>> Could be. I don't see HTML+PythonDoc as a significant improvement
>> over LaTeX.
> Have you read my list of goals?
Yes, and I mostly agree with most of them. One is worded in a very
* Build on existing non-Python-specific documentation standards
and tools, where possible (basic html, javadoc, xhtml modules,
It seems that this goal is specifically written to exclude ReST.
Javadoc is only a standard in the Java world. LaTeX *is* an
existing language-independent standard, and has a much longer
history than javadoc.
I'd re-write the above goal as:
* Build on existing documentation standards and tools, where
Another goal is highly biased toward XML-style markup:
* Make it trivial to do basic rendering to HTML (a few re.sub
calls should suffice), to enable simple tools (CGI scripts, etc)
to be able to render reference documentation.
This is the tail wagging the dog.
This item is under-specified:
* Make is easy to do advanced rendering to HTML, XHTML or XML
models (e.g. typographic issues, navigation, dynamic styling,
etc.). No more -- dashes and silly ``quotes''.
The second sentence lacks a rationale. What's wrong with "-- dashes"?
What's "silly" about "``quotes''"?
Your list is missing an important goal:
* Easy to read.
The final paragraph of the "Project Goals" section lacks context and
contains a false statement:
The semantic model should be simple, python-oriented, and more
detailed than today. For example, while a ReST-based solution
knows that open in a given context should be rendered in bold, and
a LaTeX-based solution knows that the given open is a function,
the PythonDoc model also knows that it refers to the os.open
function, rather than the built-in open function.
The reference to ReST is wrong here; ReST certainly can know the
semantics of a given identifier. I'd like to see an example of how
the HTML+PythonDoc markup indicates that a particular "open" is
os.open and not __builtins__.open.
> Does LaTeX address all of them?
Perhaps not. So? It works well enough.
> Does ReST?
Not currently, but so what? I didn't propose ReST as an alternative
to LaTeX for Python's documentation. All I'm saying is that the
proposed HTML+PythonDoc markup is not significantly better than the
status quo. I don't think there's enough benefit to make leaving
IOW: -1 on replacing LaTeX with HTML+PythonDoc.
> If not, can you explain why they're not important.
>> Yes, I'm biased. So are you.
> I don't think you understand the problem, so your bias is
> irrelevant. This is all about semantics, not presentation markup.
I don't think you understand ReST except superficially. In any case,
ReST is irrelevant to this discussion. I do not consider ReST a
suitable replacement for LaTeX in Python's docs at present.
My bias is simple: I am against wasting the time and effort required
to replace one form of verbose markup with a different but equivalent
form. The proposed solution is no better than the status quo. I
agree with the people who have stated that they find the direct
writing of HTML painful.
IMO, the markup itself is almost irrelevant. As others have stated,
writing good documentation is hard. People will latch on to any
excuse to avoid it, and markup is convenient. But even if the docs
had no markup whatsoever, if they were written in plain text like
RFCs, I doubt there would be significantly more patch contributions.
Plain text patches are already accepted; perhaps this fact needs more
emphasis, but that's all.
> We know that you have big hats over in ReST-land; now show us some
Moo. Or would you prefer the Buddhist "mu"?
What *are* you talking about?
David Goodger <http://python.net/~goodger>
-------------- next part --------------
A non-text attachment was scrubbed...
Size: 249 bytes
Desc: OpenPGP digital signature
Url : http://mail.python.org/pipermail/python-dev/attachments/20051229/6adae0ba/signature-0001.pgp
More information about the Python-Dev