[capidl] XML documentation
Jonathan S. Shapiro
shap@eros-os.org
Tue, 18 Sep 2001 11:34:28 -0400
This is a multi-part message in MIME format.
------=_NextPart_000_0108_01C14035.E046B860
Content-Type: text/plain;
charset="iso-8859-1"
Content-Transfer-Encoding: quoted-printable
Following last night's conversation with MarkM, I have concluded that =
the move to pure XML documentation is too strong. MarkM, very =
reasonably, wants to continue writing his documentation in JavaDoc-style =
HTML (i.e. not XHTML or even well-formed XML). To me, JavaDoc was a =
source of ideas, not a compatibility objective. I would like first to =
explain what motivated XML here, and then a resolution to our =
difficulty.
The motivation for XML is that our experience with the EROS =
documentation tree is that HTML is inadequate. HTML is great if the only =
output you care about is HTML, but you can't get enough semantic tagging =
to do anything *other* than HTML, so transformation becomes hard. Thus =
the move to XML. This is all empirically motivated.
I should add that subsequent to this move we are coming to the =
conclusion that XSLT is completely inadequate. A tree processor that is =
too weak to also process content (text) nodes simply isn't very useful =
as a transformer to multiple output formats.
The second problem is that students cannot successfully write XML (or =
HTML) unless you validate the input every time you run the tool.
However, on reflection it proves that forcefully integrating XML into =
CapIDL is too strong. Mark proposed something obvious that may get us =
out of the box.
First, he notes that JavaDoc passes through the HTML documentation as =
quoted strings. If we continue this practice, then CapIDL can be neutral =
about input format provided we make the following commitments:
@foo{} expansion is done using a routine supplied
by the back end.
IDL inputs using XML for documentation will
identify the fact that they used XML for this
purpose, and we won't try to generate HTML
output for these
The decision to validate is left to the back end.
Validation is performed on the output DOM
tree prior to output.
Unless I've missed something, this lets MarkM continue using HTML doc =
input with the HTML doc back end, but lets me use XML input with a =
validating XML back end.
Reactions and comments?
------=_NextPart_000_0108_01C14035.E046B860
Content-Type: text/html;
charset="iso-8859-1"
Content-Transfer-Encoding: quoted-printable
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML><HEAD>
<META http-equiv=3DContent-Type content=3D"text/html; =
charset=3Diso-8859-1">
<META content=3D"MSHTML 5.50.4807.2300" name=3DGENERATOR>
<STYLE></STYLE>
</HEAD>
<BODY bgColor=3D#ffffff>
<DIV><FONT face=3DArial size=3D2>Following last night's conversation =
with MarkM, I=20
have concluded that the move to pure XML documentation is too strong. =
MarkM,=20
very reasonably, wants to continue writing his documentation in =
JavaDoc-style=20
HTML (i.e. not XHTML or even well-formed XML). To me, JavaDoc was a =
source of=20
ideas, not a compatibility objective. I would like first to explain what =
motivated XML here, and then a resolution to our =
difficulty.</FONT></DIV>
<DIV><FONT face=3DArial size=3D2></FONT> </DIV>
<DIV><FONT face=3DArial size=3D2>The motivation for XML is that our =
experience with=20
the EROS documentation tree is that HTML is inadequate. HTML is great if =
the=20
only output you care about is HTML, but you can't get enough semantic =
tagging to=20
do anything *other* than HTML, so transformation becomes hard. Thus the =
move to=20
XML. This is all empirically motivated.</FONT></DIV>
<DIV><FONT face=3DArial size=3D2></FONT> </DIV>
<DIV><FONT face=3DArial size=3D2>I should add that subsequent to this =
move we are=20
coming to the conclusion that XSLT is completely inadequate. A tree =
processor=20
that is too weak to also process content (text) nodes simply isn't very =
useful=20
as a transformer to multiple output formats.</FONT></DIV>
<DIV><FONT face=3DArial size=3D2></FONT> </DIV>
<DIV><FONT face=3DArial size=3D2>The second problem is that students =
cannot=20
successfully write XML (or HTML) unless you validate the input every =
time you=20
run the tool.</FONT></DIV>
<DIV><FONT face=3DArial size=3D2></FONT> </DIV>
<DIV><FONT face=3DArial size=3D2>However, on reflection it proves that =
forcefully=20
integrating XML into CapIDL is too strong. Mark proposed something =
obvious=20
that may get us out of the box.</FONT></DIV>
<DIV><FONT face=3DArial size=3D2></FONT> </DIV>
<DIV><FONT face=3DArial size=3D2>First, he notes that JavaDoc passes =
through the=20
HTML documentation as quoted strings. If we continue this practice, then =
CapIDL=20
can be neutral about input format provided we make the following=20
commitments:</FONT></DIV>
<DIV><FONT face=3DArial size=3D2></FONT> </DIV>
<DIV><FONT face=3DArial size=3D2> @foo{} expansion is =
done using a=20
routine supplied</FONT></DIV>
<DIV><FONT face=3DArial size=3D2> =
by the back=20
end.</FONT></DIV>
<DIV><FONT face=3DArial size=3D2></FONT> </DIV>
<DIV><FONT face=3DArial size=3D2> IDL inputs using XML =
for=20
documentation will</FONT></DIV>
<DIV><FONT face=3DArial size=3D2> =
identify the=20
fact that they used XML for this</FONT></DIV>
<DIV><FONT face=3DArial size=3D2> =
purpose, and=20
we won't try to generate HTML</FONT></DIV>
<DIV><FONT face=3DArial size=3D2> =
output for=20
these</FONT></DIV>
<DIV><FONT face=3DArial size=3D2></FONT> </DIV>
<DIV><FONT face=3DArial size=3D2> The decision to =
validate is left=20
to the back end.</FONT></DIV>
<DIV><FONT face=3DArial size=3D2> =
Validation is=20
performed on the output DOM</FONT></DIV>
<DIV><FONT face=3DArial size=3D2> =
tree prior to=20
output.</FONT></DIV>
<DIV><FONT face=3DArial size=3D2></FONT> </DIV>
<DIV><FONT face=3DArial size=3D2>Unless I've missed something, this lets =
MarkM=20
continue using HTML doc input with the HTML doc back end, but lets me =
use XML=20
input with a validating XML back end.</FONT></DIV>
<DIV><FONT face=3DArial size=3D2></FONT> </DIV>
<DIV><FONT face=3DArial size=3D2>Reactions and =
comments?</FONT></DIV></BODY></HTML>
------=_NextPart_000_0108_01C14035.E046B860--