[Doc-SIG] that library reference, again

[David Goodger]

[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>

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 249 bytes
Desc: OpenPGP digital signature
Url : http://mail.python.org/pipermail/doc-sig/attachments/20051229/6adae0ba/signature.pgp