Bug 34116 - Example XML syntax for Ant manual + matching XSLs
Summary: Example XML syntax for Ant manual + matching XSLs
Status: NEW
Alias: None
Product: Ant
Classification: Unclassified
Component: Documentation (show other bugs)
Version: 1.7.0
Hardware: Other other
: P2 enhancement (vote)
Target Milestone: ---
Assignee: Ant Notifications List
Depends on:
Reported: 2005-03-21 23:56 UTC by Dominique Devienne
Modified: 2008-11-24 03:58 UTC (History)
0 users

ZIP file with XML+XSL files (+comparison HTML files) (12.20 KB, application/octet-stream)
2005-03-21 23:57 UTC, Dominique Devienne
Updated XSLs (13.01 KB, application/octet-stream)
2005-03-22 18:52 UTC, Dominique Devienne

Note You need to log in before you can comment on or make changes to this bug.
Description Dominique Devienne 2005-03-21 23:56:51 UTC
As I've written, I think XML+XSL is the way to go for the future Ant 
documentation. Enclosed are the preliminary results of my recent 
experimentation with defining an XML vocabulary (no DTD or schema, and one 
might be impossible given the choices I'm made...) with matching XSLs.

There's a processing instructions so it loads in an XSL compatible browser. The 
HTML files are original Ant ones for comparison. Note that IE garbles the XML 
because it does not preserve whitespace-only nodes (needs special setup to load 
conformant XSL engine) and that I did not finish the <ant> XML doc example, as 
I was not expecting such a weird example format.

So far I've mostly mimicked the existing Ant docs, but once we have semantic in 
the documentation, we can go crazy with the formatting.

Also enclosed is a XML+XSL prototype for the WHATSNEW file. Provides neat 
little features.

Both of these are addressing the Ant doc issue from the other spectrum I 
started with introspecting the tasks/types from the AntLib definition. This 
will eventually spit more XML to be merged with the manually maintained docs 
(to complement them).

Please feel free to comment or ask questions. Thanks, --DD
Comment 1 Dominique Devienne 2005-03-21 23:57:50 UTC
Created attachment 14529 [details]
ZIP file with XML+XSL files (+comparison HTML files)
Comment 2 Jan Mat 2005-03-22 09:39:53 UTC
Nice stuff in it. Especially the google and bugzilla search :-)

When looking into the WHATSNEW I played a little bit the these templates. It
would be nice if the taskname could be linked to the manual page. Because it´s
not easy to find the right link destination (CoreTypes|OptionalTasks|...) I
adopted the google search.

I didn´t change the WHATSNEW.xml, but made two modifications in the XSL:

1) a new template

  <xsl:template name="w:manual">
    <xsl:param name="name"/>
      <xsl:value-of select="$name" />

2) call of that template 
   <xsl:template match="*[starts-with(namespace-uri(), 'antlib:')]">     

-  <span class="tag"><xsl:value-of select="local-name()" /></span>
+  <span class="tag">
+    <xsl:call-template name="w:manual">
+      <xsl:with-param name="name" select="local-name()"/>
+    </xsl:call-template>
+  </span>

When looking into the manual I see a problem with more complex examples. E.g. in
<script> (last example).
Comment 3 Dominique Devienne 2005-03-22 16:01:19 UTC
I know the formatting of the examples is still a bit broken. I've fixed one 
value-of into a copy of already, but there's still whitespace issues. It's 
strange, because this XSL code is derived from a stylesheets that correctly 
styles whole build files. I'll investigate.

Nice idea about linking to a Google search for Ant external cross-ref to other 
tasks. I was thinking of creating links, but I wanted to postpone this until 
the final structure of the manual emerges.

I was hoping for some comment on the XML manual files though (and also the 
whatsnew vocab too). Too verbose? Should be able to have a DTD/Schema? Etc...

Or put another way, is this prototype going in the right direction or not? And 
should I persue it or abandon it because it's not what the community wants. --DD
Comment 4 Stefan Bodewig 2005-03-22 16:30:10 UTC
I'm looking forward to (not really ;-) eight+ hours of train driving tomorrow and
will come back after that.
Comment 5 Dominique Devienne 2005-03-22 18:52:41 UTC
Created attachment 14540 [details]
Updated XSLs

Fixed the example space issue + add build.xml. --DD