[Doc-SIG] Creating a new type of document

[David Goodger]

Derek Wyatt wrote:
 > First off... thanks for the tool.  I love the markup language.

:-)

 > I'm trying to use this to create a documentation centre within the
 > company that i work for.  I like the idea of PEPs (as i've stated on
 > a previous message) but I don't like the PEP acronym

Understandable, if it doesn't fit your documents.

 > What am i writing to accomplish this?  I am getting a bit of a feel
 > for how the system works and it looks like i'm not going to be
 > writing a reader or parser since the file will be basic reST.
 > However i think i need to write a transform, writer and a front-end.
 > Is this correct?

I think you'll need:

* a Reader (subclasses of docutils.readers.pep classes should
   suffice),
* transforms (subclasses/variations of docutils.transforms.peps
   classes),
* a Writer (subclasses of docutils.writers.pep_html classes),
* a template file (variation of tools/pep-html-template),
* possibly a stylesheet (variation of tools/stylesheets/pep.css), and
* a front end (variation of tools/pep.py; don't use pep2html.py, which
   contains a lot of non-Docutils legacy code).

It may be cleaner to generalize some of the PEP-specific classes for
easier subclassing; if so, we could add new generic "proposal" modules
that PEP modules could use.

 > I could write an html munger that takes the output of the html.py
 > front end and puts in the "DED nn" links and the links at the top,
 > but it seems much cleaner to write something that can intercept the
 > reST parsed output into XML and insert the stuff there.

Agreed.  You may want to take a look at other projects that have done
the same thing:

* PEGs (Proposals for Enhancing Gzz):
   http://himalia.it.jyu.fi/gzzdoc/pegboard/pegboard.gen.html

* GLEPs (Gentoo Linux Enhancement Proposals):
   http://www.gentoo.org/proj/en/glep/

Both of these have adopted Python's PEP system and reStructuredText
for their own proposals.  If anyone knows of other projects that have
done the same thing, please let me know.  I haven't looked at any of
the actual code they use, so I can't say if it's done "correctly".

-- 
David Goodger                               http://python.net/~goodger
For hire: http://python.net/~goodger/cv