[XML-SIG] Re: PyDoc/XML?

John Day jday@csihq.com
Tue, 28 Sep 1999 19:18:56 -0400


Uche,

I wrote:
>> In other words, is it possible to use XML as a markup language inside the
>> comments of another language etc. I seem to recall that this is done in
>> SGML but haven't heard of it in XML.

You replied
>Where's the technical problem?
>
>#!/usr/bin/python
>"""
><module name='foo'>
><description>A collection of k-RAD routines for the very 3733T</description>
></module>
>"""

I see at least two problems (perhaps more esthetic than technical :)
1. XML is not (IMHO) user-friendly enough to allow human entry and still
   remain well-formed & validatable (XML would require that last phrase
   to be written "well-formed &amp; validatable"). We can't expect folks
   to remember what has to be escaped and/or quoted etc.
2. XML is not (IMHO) flexible and readable enough  to be blended or
   mixed with ordinary, unmarked document comments in a natural way. Your
   triple-quoted examples show pure XML. Why can't we mix this with 
   'free-style' comments in a intuitive way (a la JavaDocs)?

These problems suggest that we would need some kind of pre- or post-
processor to correct these problems. If so, why not invent a markup-language
that is friendly and flexible enough to eliminate this need? 

So this was my original question: Is it possible to define a markup-language
like this in XML? 

I should point out that I mainly want to generate language _reference_
manuals with this markup language. I agree with you that other documents,
including general user and programming documentation should be produced
as standalone documents. Reference manuals, however, would benefit by 
their one-to-one relationship with the code they resemble.


John Day