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

[Jim Fulton]

Ka-Ping Yee wrote:
> 
> > 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?).

This is fairly easy to do, since gendoc has conventions for
entering hyper links.

> 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

Gendoc now uses my structured-text module (or some variant of it), 
which is like setext mut easier to enter and read.

> and gendoc, its goal would be
> a format simple enough to read directly as text. 

Yes.

> I think this is
> quite possible, but creating a whole new documentation format may
> not make some people happy.

But the format used by gendoc is extremely simple and natural.  It
requires very little skill, and is very readable in it's raw form,
unlike variants of Tex.

Jim


_______________
DOC-SIG  - SIG for the Python Documentation Project

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