(I moved this discussion onto it's own page --BillRehm)
I moved this discussion from "FileFormat" to DocumentationFileFormat.
Never forget that keywords in this system are always context-sensitive, and that "FileFormat" would mean something totally different if mentioned from another part of this web. - MarkusPeter
How about defining a Unix-Man page like format using XML and also defining rendering rules or a mapping to HTML? - MarkusPeter
Actually, I was thinking that everything would eventually be defined in XML, although we might want to start with HTML, since most of us are already familiar with it. Since XML is expected to support the HTML DTD, we should be able to "port up" easily, once the tools are available.
RE: XML and javadoc/polardoc
Once we're using XML, we should be able to define a nice DTD that doesn't just render @Author or @Version, but uses them as metadata. This would be nice, don't you think? -BillRehm
Are there any recommended (free) (java) SGML tools?
What is the ETA on XML or tools for it?
-BenKnowles
SGML is dead. Long live XML. (At least in the context of Internet standards--SGML is still used in the publishing industry). I'm working on XML tools right now; I'll make a DTD for JOS documentation part of my testing. We'll have to start with an XML format for documentation rather than HTML because HTML doesn't carry enough information. In XML, tags specify the exact semantics of each piece of information: this is the author, this is a class name, this is a filename, etc. It's trivial to convert "down" to HTML or some other display format, but it's impossible to convert "up" from HTML if the information is not there to begin with. --LeeDanielCrocker
I was wondering if anybody got a look at this yet?
http://www.edu.uni-klu.ac.at/~nmikula/NXP/
-- BillRehm
Looks good. License is currently "email-ware", and that'd have to be clarified/modified. I haven't d/led it though, as I've barely any idea of XML. (I'm just learning SGML...sigh). Are there any web tutorials on XML? (or are they already in the reading list?)
--BenKnowles
Lee, I see your point. I guess I was thinking about a javadoc-style tool that we could change the rules on & regenerate when we had XML editors/parsers/browsers. That would still only solve things for the source code.
Here's an interesting informal proposal for a Java XML API:
http://xml.datachannel.com/xml/dev/index.html
I just added these 2 links to DataFormats in Readings --BillRehm
I strongly encourage the usage of XML from the very beginning. Note that documentation not only means API documentation but also end-user documentation... And this type of documentation can not be generated automatically, and I guess we will not find anybody who rewrites that part of the documentation in XML then... XML is ably to carry more information - actually every information we decide to be part of the documentation. I fear, should we use HTML, we will soon reach the point, where using XML would not only have contained certain information more "explicitely", but also, where we find it impossible to put the information we need into HTML files while still keeping a simple and logical DocumentationFileFormat .
-- MarkusPeter
|
Content of these pages are owned and copyrighted by the poster.
|
|
Hosted by:
|
|