[Doc-SIG] SGML Python docs

[Cees de Groot]

tratt@dcs.kcl.ac.uk said:
> I would imagine this is the only way to reliably retain all the
> information that the LaTeX now holds (eg about when "string" is a
> module, and when it's an attribute in an RE object). I don't believe
> in reinventing the wheel when it's not necessary, but I would imagine
> we would be trying to mangle two different wheels together if we used
> a non-specific DTD. 

Fred made a statement about energy better spent at writing documentation than 
converting it - this becomes very true in the area of DTDs. A DTD like DocBook 
isn't non-specific, it is very specific: writing software documentation, and 
with it are all the tools to adapt it to your own piece of software (starting 
with very simple things like role attributes). With inventing your own DTD 
you'll have little gains, but a big burden: endless discussions on tags, the 
need to maintain it, the need to write conversion software, etcetera. I'd 
advise anything short of a full-time SGML publishing business against doing so.

The <SystemItem role="module">string</> module.
The <StructField>string</> attribute of an RE object.

As I mentioned, with the decision to use DocBook, you'd need to make a sort of 
stylesheet where you define the markup to apply to the common elements of the 
software being documented; in the case of Python, this list is probably 
something like [module, class, function, parameter, default value of 
parameter, attribute], in other words: not very long and way easier to 
maintain than a complete DTD.



 
-- 
Cees de Groot               http://pobox.com/~cg          <cg@pobox.com>
--- We're hiring Java developers => www.acriter.com