Re: Documentation, CVS, and Maven
Hi Martin, I've been trying to get some reasonably complex docbook (but not overly so) files for testing against Maven. Looks like you've done it for me? Is this something you could pass on so I could update the plugin? -- dIon Gillard, Multitask Consulting Blog: http://www.freeroller.net/page/dion/Weblog Work: http://www.multitask.com.au Martin Skopp [EMAIL PROTECTED] wrote on 04/04/2003 11:59:07 PM: On Fri, 2003-04-04 at 14:21, Jose Gonzalez Gomez wrote: The simple docbook is just a DTD based on docbook with a lot of trimmed tags for use in simple documentation. Maven provides limited support for this kind of docbook. Could you please post the URL of that DTD? What tools are you using to author docbook documentation? jEdit http://www.jedit.org/, with XML plugins installed. I have put one of our docbook files to maven and it worked more or less: * Easy tables worked, complex tables failed. * orderedlist, itemizedlist worked fine * Titles of sections inside sections did not show up in a different style/code, possibly a CSS problem. * screen and images/inlinegraphic failed * links (ulink) worked well * email failed * filename failed * menuchoice and keycap failed * FAQ (qandaset) failed Seems that the docbook-plugin fraction needs some programming support... ;-) I was actually impressed that it worked! -- Martin Skopp Riege Software International GmbH Support: mailto:[EMAIL PROTECTED], Information: http://www.riege.com This email is intended to be viewed with a nonproportional font. Public Key on http://www.keyserver.net, Key-ID: 3D4027B5 Fingerprint: 1970 C78D 9A1D 99FA 5CE4 5C0D 29E6 6A95 3D40 27B5 - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED] - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Documentation, CVS, and Maven
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]
Re: Documentation, CVS, and Maven
On Fri, 2003-04-04 at 13:22, Jose Gonzalez Gomez wrote: * docbook. Based on standards, lot of tools to output in a variety of formats, with limited support in maven for the simple version. Don't know the diff betw. docbook full+simple, but we use docbook here for such docs since we sometimes need to integrate images, tables, appendixes, indexes, table of content automatically etc. and sometimes we need to deliver PDF. DocBook does the job well - we use just a few tags but * it has more options than xdoc * it has less layout than html which makes it ideal for us here. Haven't looked into mavens docbook support, but that could be a point against it... -- Martin Skopp Riege Software International GmbH Support: mailto:[EMAIL PROTECTED], Information: http://www.riege.com This email is intended to be viewed with a nonproportional font. Public Key on http://www.keyserver.net, Key-ID: 3D4027B5 Fingerprint: 1970 C78D 9A1D 99FA 5CE4 5C0D 29E6 6A95 3D40 27B5 - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Documentation, CVS, and Maven
Martin, The simple docbook is just a DTD based on docbook with a lot of trimmed tags for use in simple documentation. Maven provides limited support for this kind of docbook. What tools are you using to author docbook documentation? Regards Jose Martin Skopp wrote: On Fri, 2003-04-04 at 13:22, Jose Gonzalez Gomez wrote: * docbook. Based on standards, lot of tools to output in a variety of formats, with limited support in maven for the simple version. Don't know the diff betw. docbook full+simple, but we use docbook here for such docs since we sometimes need to integrate images, tables, appendixes, indexes, table of content automatically etc. and sometimes we need to deliver PDF. DocBook does the job well - we use just a few tags but * it has more options than xdoc * it has less layout than html which makes it ideal for us here. Haven't looked into mavens docbook support, but that could be a point against it... - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Documentation, CVS, and Maven
Could you please post the URL of that DTD? Sure... !DOCTYPE article PUBLIC -//OASIS//DTD Simplified DocBook XML V1.0CR2//EN http://www.oasis-open.org/docbook/xml/simple/1.0CR2/sdocbook.dtd; Regards Jose - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
