[Mono-list] Re: [Mono-hackers-list] Re: Patch for mcs
Richard Norman
normri@samc.com
Wed, 03 Nov 2004 10:15:09 -0800
This is a MIME message. If you are reading this text, you may want to
consider changing to a mail reader or gateway that understands how to
properly handle MIME multipart messages.
--=__PartBD9D783D.0__=
Content-Type: text/plain;
charset=us-ascii
Content-Transfer-Encoding: 7bit
I'm no expert in the XML comments area, but could someone explain the
exact issue here? I mean to me the easiest thing is to create the XML
file and parse that file into whatever format you want. It may be
processor intensive to do, but you would not do this at runtime. Only
once your application was complete.
So why could you not use the file after it was completed and serialized
to disk (this is what is planned right) ? Then you read the XML as a
string from disk and do any manipulation you want. Or are what you
trying to do is as soon as the comments are read from the sources, you
want to parse them immediately to another tool as the code is compiled
without the XML tags?
Please excuse me if this is a little ignorant of the situation, but I
have been trying to catch up with this thread for awhile, but I am
getting a little confused with the back and forth.
Richard Norman
Web/Application Developer
>>> mono-list-request@lists.ximian.com 11/2/2004 8:30:01 PM >>>
Message: 11
Date: Wed, 3 Nov 2004 09:58:59 +0530
From: Gaurav Vaish <gaurav.vaish@gmail.com>
Reply-To: Gaurav Vaish <gaurav.vaish@gmail.com>
To: Miguel de Icaza <miguel@ximian.com>
Cc: Atsushi Eno <atsushi@ximian.com>,
mono-list <mono-list@ximian.com>,
Mono Hackers <mono-hackers-list@ximian.com>,
marek safar <marek.safar@seznam.cz>
Subject: [Mono-list] Re: [Mono-hackers-list] Re: Patch for mcs
> Thanks for the explanation.
>
> Now the question is: how is this different from the /doc switch that
we
> are adding today to mcs?
Ok. Initially there may not be any different. However, the "/doc"
switch only produces XML-doc. And to format the XML-doc, you need to
create your own xslt -- the crude way in which NDoc works.
However, I want to give power to create any document-engine that
can work on the raw comment strings. See JavaDoc related links below.
>
> Would it be possible to instead just use the output produced by
> mcs /doc? My concern is that I do not want to add code to the
compiler
> without having a good reason for having it there.
No. The reason is -- it is very difficult to extend the "language"
of the doc-tool, I mean the elements understood by it.
> What are docklet and taglets?
Javadoc:
http://java.sun.com/j2se/1.4.2/docs/tooldocs/javadoc/
Towards the end of the page is a separate section on "Doclets" (not
APIs).
Doclet:
http://java.sun.com/j2se/1.4.2/docs/tooldocs/javadoc/overview.html
Taglet:
http://java.sun.com/j2se/1.4.2/docs/tooldocs/javadoc/taglet/overview.html
> So the issue is: woul d it not be best to focus our efforts on a
single
> solution? For example, adding chm support to Monodoc would be a
great
> addition.
That's fine. But then, the engine would work on the final XML that
it gets. Not an issue - NDoc works in the same manner. Has xslt to
convert XML into several HTMLs and then uses MS Help Compiler to
create CHM.
But that's just one extension. Tomorrow we may wish to create other
extension -- working on final XML may be more than a little pain.
Parsing it each and everytime with xslt to get a single HTML... it's
pain both for me and my processor.
Just for example, look at this:
http://xdoclet.sourceforge.net/xdoclet/index.html
It cannot work with the current inextensible "/doc" swtich. Where's
the power at program-level to understand new tags?
And to do so, you need raw comments and let the "Doclet" or "Taglet"
parse the raw information if required! It's not possible to keep on
extending "/doc" switch. Let everybody create their own custom Doclet
/ Taglet. Unleash the power!!!
--
Cheers,
Gaurav Vaish
http://csdoc.sf.net
-------------------
--=__PartBD9D783D.0__=
Content-Type: text/html;
charset=iso-8859-1
Content-Transfer-Encoding: quoted-printable
Content-Description: HTML
<HTML><HEAD>
<META http-equiv=3DContent-Type content=3D"text/html; charset=3Dwindows-125=
2">
<META content=3D"MSHTML 6.00.2900.2523" name=3DGENERATOR></HEAD>
<BODY style=3D"MARGIN: 4px 4px 1px; FONT: 10pt Tahoma">
<DIV>I'm no expert in the XML comments area, but could someone explain the =
exact issue here? I mean to me the easiest thing is to create the XML file =
and parse that file into whatever format you want. It may be processor =
intensive to do, but you would not do this at runtime. Only once your =
application was complete.</DIV>
<DIV> </DIV>
<DIV>So why could you not use the file after it was completed and =
serialized to disk (this is what is planned right) ? Then you read the XML =
as a string from disk and do any manipulation you want. Or are what you =
trying to do is as soon as the comments are read from the sources, you =
want to parse them immediately to another tool as the code is compiled =
without the XML tags?</DIV>
<DIV> </DIV>
<DIV>Please excuse me if this is a little ignorant of the situation, but I =
have been trying to catch up with this thread for awhile, but I am getting =
a little confused with the back and forth.</DIV>
<DIV> </DIV>
<DIV>Richard Norman</DIV>
<DIV>Web/Application Developer<BR><BR>>>> mono-list-request@lists.=
ximian.com 11/2/2004 8:30:01 PM >>><BR></DIV>
<DIV style=3D"COLOR: #000000"><BR>Message: 11<BR>Date: Wed, 3 Nov 2004 =
09:58:59 +0530<BR>From: Gaurav Vaish <gaurav.vaish@gmail.com><BR>Repl=
y-To: Gaurav Vaish <gaurav.vaish@gmail.com><BR>To: Miguel de Icaza =
<miguel@ximian.com><BR>Cc: Atsushi Eno <atsushi@ximian.com>,<BR=
> mono-list <mono-list@ximian.com>,<BR> =
Mono Hackers <mono-hackers-list@ximian.com>,<BR> &n=
bsp; marek safar <marek.safar@seznam.cz><BR>Subject: [Mono-list] Re: =
[Mono-hackers-list] Re: Patch for mcs<BR><BR>> Thanks for the explanatio=
n.<BR>> <BR>> Now the question is: how is this different from the =
/doc switch that we<BR>> are adding today to mcs?<BR><BR> =
Ok. Initially there may not be any different. However, the "/doc"<BR>switch=
only produces XML-doc. And to format the XML-doc, you need to<BR>create =
your own xslt -- the crude way in which NDoc works.<BR><BR> =
However, I want to give power to create any document-engine that<BR>can =
work on the raw comment strings. See JavaDoc related links below.<BR><BR>&g=
t; <BR>> Would it be possible to instead just use the output produced =
by<BR>> mcs /doc? My concern is that I do not want to add code to =
the compiler<BR>> without having a good reason for having it there.<BR><=
BR> No. The reason is -- it is very difficult to extend the =
"language"<BR>of the doc-tool, I mean the elements understood by it.<BR><BR=
>> What are docklet and taglets?<BR><BR>Javadoc:<BR> =
<A href=3D"http://java.sun.com/j2se/1.4.2/docs/tooldocs/javadoc/">http://ja=
va.sun.com/j2se/1.4.2/docs/tooldocs/javadoc/</A><BR><BR>Towards the end of =
the page is a separate section on "Doclets" (not APIs).<BR><BR>Doclet:<BR>&=
nbsp; <A href=3D"http://java.sun.com/j2se/1.4.2/docs/tooldocs/javadoc=
/overview.html">http://java.sun.com/j2se/1.4.2/docs/tooldocs/javadoc/overvi=
ew.html</A><BR>Taglet:<BR> <A href=3D"http://java.sun.com/j2se/=
1.4.2/docs/tooldocs/javadoc/taglet/overview.html">http://java.sun.com/j2se/=
1.4.2/docs/tooldocs/javadoc/taglet/overview.html</A><BR><BR><BR>> So =
the issue is: woul d it not be best to focus our efforts on a single<BR>>=
; solution? For example, adding chm support to Monodoc would be a =
great<BR>> addition.<BR><BR> That's fine. But then, the =
engine would work on the final XML that<BR>it gets. Not an issue - NDoc =
works in the same manner. Has xslt to<BR>convert XML into several HTMLs =
and then uses MS Help Compiler to<BR>create CHM.<BR><BR> But =
that's just one extension. Tomorrow we may wish to create other<BR>extensio=
n -- working on final XML may be more than a little pain.<BR>Parsing it =
each and everytime with xslt to get a single HTML... it's<BR>pain both for =
me and my processor.<BR><BR> Just for example, look at =
this:<BR> <A href=3D"http://xdoclet.sourceforge.net/xdocl=
et/index.html">http://xdoclet.sourceforge.net/xdoclet/index.html</A><BR><BR=
> It cannot work with the current inextensible "/doc" swtich. =
Where's<BR>the power at program-level to understand new tags?<BR><BR> =
And to do so, you need raw comments and let the "Doclet" or "Taglet"<BR>pa=
rse the raw information if required! It's not possible to keep on<BR>extend=
ing "/doc" switch. Let everybody create their own custom Doclet<BR>/ =
Taglet. Unleash the power!!!<BR><BR><BR>--<BR>Cheers,<BR>Gaurav Vaish<BR><A=
href=3D"http://csdoc.sf.net">http://csdoc.sf.net</A><BR>------------------=
-</DIV></BODY></HTML>
--=__PartBD9D783D.0__=--