Re: [pygame] updating the docs

[Dan <dan@xxxxxxxxxxxxxxxx>]

> If it's going to be a "tagged" format, I'd suggest
> using tags like
> <method> ... </method>  <class>...</class> ..
> <function> .. </function>

I suggest DocBook:

  <RefEntry>
    <RefMeta>
      <RefEntryTitle>surfarray</RefEntryTitle>
    </RefMeta>
    <RefNameDiv>
      <RefName>pygame.surfarray</RefName>
      <RefPurpose>like a <class>Surface</class>,
                  but faster pixel-by-pixel access</RefPurpose>
    </RefNameDiv>
    ...

DocBook scales upward very well, which is important because a project's
documentation has a habit of growing and becoming umanageable. In
addition, DocBook is a standard format for documentation, especially
open-source documentation.

On the downside, DocBook's standard stylesheets are huge and difficult
to customise. On the good side, when the documentation is still small
you can write your own stylesheets.

Eric S. Raymond suggests that all open-source documentation should be in
DocBook:
  http://www.faqs.org/docs/artu/documentationchapter.html

If DocBook is too verbose, the documentation could be made in a subset
of DocBook that can later be converted to the full DocBook.

I can help you convert to DocBook, if you like, because I'm familiar
with it.

-- 
   They've signed me up for every advertising campaign
   and mailing list there is. These people are out of
   their minds. They're harassing me.
       - spam tycoon Alan Ralsky, who was signed up for tons of
         (paper) junk mail after publicly proclaiming that
         he had no regrets about his spam empire.