Lately I've been thinking about documentation, cvs and maven, and I'd like to hear opinions from you.
Here's the scenario:
* I want to document a software project using a subset of the
artifacts provided in the unified process, you know, capture
requirements using use cases, analysis and design using UML, etc
* I want this documentation to be easily integrated in cvs, so I
don't want them to be binary formats
* I want this documentation to be easily integrated in maven.So the candidates are html, xdoc and docbook (full or simple). Do you know any other alternative I should take into account?
Thougths about them:
* html. A good option, as long as all the people creating
documentation can share a stylesheet, and we can find a program to
edit the files that doesn't put garbage in the html code
* xdoc. The preferred documentation format for maven.
* docbook. Based on standards, lot of tools to output in a variety
of formats, with limited support in maven for the simple version.Questions about xdoc:
I have the impression, after taking a look at the maven source, that the main reason for adopting xdoc is simplicity and possibility of processing it with xml stylesheets to add the format and the banner and menu typical of maven projects. I find xdoc too simple for my needs. For example I have some documents where I have more than two levels of headers, while xdoc only support section and subsection (two levels).
Maven style is applied to headers, tables, and source code basically, am I right? So couldn't be the source for maven documentation a plain xhtml with h1 and h2 instead of section and subsection? This way maven wouldn't impose a restriction on levels or format of the document, and xml stylesheet for site generation could still be used. Maven could still provide a html stylesheet defining styles for h1 through h6, tables and pre.
Another question... is there any reason for mapping section and subsection to h3 and h4 instead of h1 and h2?
Regards Jose
--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
