[Fredrik Lundh]
I'm beginning to fear that I've wasted my time on a project that nobody's interested in.
[David Goodger]
Could be. I don't see HTML+PythonDoc as a significant improvement over LaTeX.
[Fredrik Lundh]
Really?
Yes, really.
Have you read my list of goals?
Yes, and I mostly agree with most of them. One is worded in a very slanted way: * Build on existing non-Python-specific documentation standards and tools, where possible (basic html, javadoc, xhtml modules, etc). 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 possible. 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 LaTeX worthwhile. 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 cattle.
Moo. Or would you prefer the Buddhist "mu"? What *are* you talking about? -- David Goodger http://python.net/~goodger