[Doc-SIG] converting tex? use of docbook?

[David Goodger]

Nobody has answered yet, so I'll give it a shot.  These are just my
opinions here, nothing official.

Ian Atkin wrote:
> here's my questions:-
> - is there any motivation to move python's doc format to xml
> docbook?

There has been discussion in the past, and there seems to have been
some consensus on moving towards XML, but I don't think there's enough
of a benefit to move away from the current TeX markup and toolchain.
The current setup is mature and works well ("it ain't broke"), so
there's little perceived need to "fix" it.

> can i contrib/promote in any way? (i read a mention of a "python doc
> project" like the ldp)

There's plenty of room for tech *writing* contributions.  As for
writing *code*, unless you're willing to do a very complete and
high-quality job, I doubt if an effort to replace the existing core
documentation system would be well-received.  But there are lots of
other places where you can contribute.  May I suggest you take a look
at Docutils (http://docutils.sf.net/)?  If you like DocBook, there's a
"DocBook output writer" component that's partially finished.

> - what "types" of document are most commonly used/wanted in the
> python distro/apps and do these require unique markup?

I can think of the following classifications for Python documents:

A) Core documentation.  This is what comes with Python.  The source
   files are TeX; HTML and others are generated from the TeX files.
   For details, see "Documenting Python" at

       http://www.python.org/doc/current/doc/doc.html

B) Inline documentation.  Python modules have documentation strings,
   or "docstrings", in the source code.  Modules in Python's standard
   library have some inline docs, but they're merely hints; the core
   documentation is emphasized.  Third-party projects often maintain
   their API docs in docstrings, and extract them with HappyDoc or
   Crystal or PythonDoc etc.; Docutils plans to support this
   functionality in the future too.  Sometimes the docstrings have
   markup, sometimes they're plaintext.  See PEP 257 for more:

       http://www.python.org/peps/pep-0257.html

C) Project standalone documentation.  These are documents specific to
   a project, and the markup used is up to the project contributors.
   Anything is possible here.

D) Online help.  Some projects have online help documentation, often
   in the native format supported by the platform.

> - are there any open tools (or chains) around to convert tex source
> into xml (xslt scripts can do the rest)?

That I don't know.  Have you checked Google?

-- 
David Goodger  <goodger@users.sourceforge.net>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/