[XML-SIG] Re: PyDoc/XML?
Tue, 28 Sep 1999 19:18:56 -0400
>> 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.
>Where's the technical problem?
><description>A collection of k-RAD routines for the very 3733T</description>
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 & 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.