[PYTHON DOC-SIG] Re: DTD's for Python (fwd)

[Ka-Ping Yee]

> But would it make sense to beef up gendoc?  gendoc could parse the
> .py, and possibly other special purpose doco files.

Perhaps.  The problem is that we could end up with two separate
sets of documentation -- one embedded in doc-strings, and the
other in a sophisticated desktop publisher.  Even if we manage
to keep them in separate domains to avoid conflicting information,
there'd still be no connection (what if someone wants to hyperlink
from a doc-string to the reference manual?).

The trick is to come up with something that is lightweight enough
for people to casually enter as doc-strings, yet powerful enough
to supply all the features a book author might want while writing
a technical manual.  Akin to setext and gendoc, its goal would be
a format simple enough to read directly as text.  I think this is
quite possible, but creating a whole new documentation format may
not make some people happy.


Ping

_______________
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
_______________