[XML-SIG] Re: PyDoc/XML?

[uche.ogbuji@fourthought.com]

John Day:
> >> 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.

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

John Day:
> I see at least two problems (perhaps more esthetic than technical :)

Why be so polite?  It's downright hideous.

> 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)?

And that's exactly why I said I wouldn't recommend it (although I won't 
automatically agree with XML's lack of readibility).  I appear to have 
misunderstood your question, and I'm still not sure I understand it.

> 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? 

Please provide some sort of example.  Are you sure you mean "markup-language"?

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

I don't get it.  Presumably your objection to XML-in-the-midst-of-code is all 
the palaver with angle brackets, beginning and end-tags, character entities 
and all that.  In that case, how can we possibly come up with an XML-based 
language that is not problematic?

> 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.

Actually, I am precisely talking about reference documents with the DTD and 
XSL I presented.  The result would certainly not be friendly enough to be used 
for intros or tutorials.  I don't think there is any way to generate general 
user and programming documentation automatically until AI is a good deal 
further advanced.

So I'm quite in the dark at this point.  I think it might help if you could 
provide examples, even poor ones.

-- 
Uche Ogbuji
FourThought LLC, IT Consultants
uche.ogbuji@fourthought.com	(970)481-0805
Software engineering, project management, Intranets and Extranets
http://FourThought.com		http://OpenTechnology.org