[Python-Dev] [Doc-SIG] that library reference, again

[Fredrik Lundh]

> [David Goodger]
> >> Could be. I don't see HTML+PythonDoc as a significant improvement
> >> over LaTeX.
>
> [Fredrik Lundh]
> > Really?
>
> Yes, really.

Your reply makes it obvious that you don't understand the issues involved
here, nor how the goals address them.

(Snipping heavily below due to lack of time; if you want some other argument
refuted, you have to repost and wait until next week.)

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

No, it's a fundamental goal: to support light-weight generation of rendered
markup directly from source code, to enable simple tools (CGI scripts, etc)
to be able to render reference documentation.

The issue this is addressing is that the current workflow is way too heavy;
when I made my first post, it typically took 3-6 months for a contribution to
the documentation to appear on python.org.  Thanks to Trent and Neal, the
situation is a bit better today, but it's far from ideal.  (More on this below).

> The second sentence lacks a rationale.  What's wrong with "-- dashes"?
> What's "silly" about "``quotes''"?

I'd say that the fact that you're asking this should disqualify you from ever
working on documentation tools again...  don't you know *anything* about
typography ?

> The reference to ReST is wrong here; ReST certainly can know the
> semantics of a given identifier.

> I don't think you understand ReST except superficially.

That's why I'm listening to people who've tried to use ReST for this pur-
pose.  They've all failed.  Maybe they also only understood ReST super-
ficially.  Or maybe it's because ReST is created by people who have a
very shallow understanding of the issues involved in writing structured
reference documentation.  Your guess is as good as mine.

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

Support for quick turnaround, edit via the web, richer semantic information,
and a larger existing toolbase isn't better than the status quo ?

Sounds more like a ReSTian sour-grapes (or scorched-earth) approach
than a serious argument from someone who's interested in improving the
Python documentation.

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

The problem is that the WORKFLOW doesn't work.  Quoting from an earlier
post (you have read the earlier discussion, right?):

    If an ordinary user finds a minor issue, a typo, or an error in the
    documentation, the current user workflow is:

    1) (optionally) cut and paste the text to an editor, edit, and save to disk
    2) go to the sourceforge site, and locate the python project
    3) (optionally) sign up for a sourceforge account
    4) log in to your sourceforge account
    5) open a new bug or patch issue, and attach your suggestion
    6) wait 3-6 months for someone to pick up your patch, and for the
       next documentation release to appear on the site

to which can be added:

    If a developer finds a minor issue, a typo, or an error in the documentation,
    the current developer workflow is:

    If logged in to a machine with a full Python development environment:

    1) sync the project
    2) locate the right source file
    3) edit, and save to disk
    4) (optionally) regenerate the documentation and inspect it (3-6 minutes
        if you have the toolchain installed)
    5) commit the change (alternatively, generated a patch; see 2-5 above)
    6) wait up to 12 hours for the updated text to appear on the developer
       staging area on python.org, and 3-6 months for the next documentation
       release to appear on the site

    If no access to a Python development environment:

    1) (optionally) cut and paste the text to an editor, edit, and save to disk
    2) write note or mail to self (or generated a patch; see user instructions
       above)
    3) at an unspecified later time, try to remember what you did, and follow
       the developer instructions above.  wait 3-6 months for the next doc
       release to appear on the site.

I'm not arguing that a change of markup will solve this; I'm saying that a
a light-weight toolchain will make it possible to cut this down to 3-6 seconds
(plus optional moderation overhead for ordinary users).  If people get feedback,
they contribute.

The need for a light-weight markup language follows from this; to eliminate
as much overhead as possible,

 - the semantic model should match the reader's understanding of the
   target domain (in this case, the contents of Python library namespace)
 - the markup closely reflect the underlying semantic model
 - it should be *understandable* and *modifiable* (so you can tweak and
   copy constructs you see in the source, rather than having to look them
   up in a huge reference manual)
 - and it should be easy to parse for both machines and humans.

It's the workflow that's the real problem here, but you cannot fix the workflow
without fixing the markup.

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

I assume this means that we're going to keep getting more "ReST can certainly
do this but we're not going to show anyone how" posts from the ReST camp ?

</F>