Hi Andrew, My vote is for DocBook - I used it a few years ago for a software manual without too many issues, and the tools have matured since then. Keep away from anything DSSSL based (including the DSSSL flavour of DocBook), otherwise we will create a dependency on needing a Lisp expert to sort out the stylesheets.
Another option would be to have our own simple XML markup language along with XSLT that produces DocBook (I know nothing about CWML - is it XML based? Can it be transformed into DocBook?) Regards, Dave On 7/11/2007 2:16 p.m., Andrew Miller wrote: > Hi, > > One issue which came up at today's meeting for people at Auckland > involved with CellML is how we will represent the next version of the > CellML specification. Having a 'source' format of the specification will > make it easier for us to propose specific changes to the document and so > will hopefully allow us to make progress towards the next version of CellML. > > There are a few different options out there which might be worth > exploring. Any feedback from the wider CellML community on the issue of > how we represent the 'source' of the specification which gets exchanged > would be very helpful, and after the close of discussions we will be > able to start preparing draft versions with proposed changes much more > easily. > > I have identified a few possible choices, and have included my views on > what potential benefits or pitfalls of different approaches will be: > > 1) Use HTML as is currently stored in the Plone Software Centre. > Pros: > * The source format can be directly visualised in the user's > browser, which reduces the complexity of the required development > environment. > * WYSIWYG type editing possible (although the cleanness and > consistency of such editors' output may be an issue). > * We already have the document in this format which we could use > as a starting point. > Cons: > * No automatic ability to generate section references by number > based on a reference by name in the source. > * Sophistication of automatic numbering limited to single > uninterrupted numbered lists with possible manual restarts if there is > intervening text. > * Diffs between different HTML versions are hard to read. > * Even if CSS is used, there will inevitably be some mixing of > style and content, which makes it harder to make sweeping changes to the > layout, and makes it harder to create good quality PDF / RTF / plain > text outputs. > > 2) Use reStructured text. > Pros: > * The unrendered reStructured format is quite readable, which > means that it is easy to learn by example, and also that diffs are more > readable. > * Easy to set reasonable and consistent style guidelines for > writing the specification in the reST source. > * Reasonable tool support, including in Trac and in ZWiki. > * Could convert to several types of output. > Cons: > * No section references by number based on reference by name in > the source. > * No automatic numbering aside from numbered lists (e.g. no counters). > * No easy way relate specific elements to specific style > instructions if we need to do this. > > 3) Use Warren's CWML language > Pros: > * We already have the document in this format which we could use > as a starting point. > * Reasonably clean markup in terms of header, section, and so on. > * Supports section references by name, which come out as > references by number. > * Can generate multiple output types. > * Embedded MathML equations can be used. > Cons: > * Non-standard. > * Warren's tools are out of date and need to be updated to be > useful for the current CellML site - potentially a large time investment. > * Need to manually create contents sections and the like as it is > at the moment. > > 4) Modify the W3C DSSSL based tools (see > http://www.w3.org/XML/1998/06/xmlspec-report-v21) used for their > specifications. > Pros: > * Allows for section references and generation of full > specification structure. > * Supports a lot of specification type metadata and concepts, and > will therefore delimit everything in specification very thoroughly. > * Used by the W3C for a large number of specifications, so > reasonably well field tested. > Cons: > * Potentially hard to read diffs if they change lots of sections > and therefore include parts of the markup. > * We will need to make some changes to make it non-W3C specific. > > 5) Use DocBook > Pros: > * DocBook widely implemented - lots of tools, several output formats. > * Lots of semantic markup elements for a lot of different types of > data. > * Automated section numbering and content page references. > * Content page generation > * With the MathML extension module, embedded MathML can be used - > I'm not sure how well this works in practice > Cons: > * Potentially hard to read diffs if they change lots of sections > and therefore include parts of the markup. > > 6) Use the IETF's xml2rfc tools > Pros: > * Widely tested. > * Section references. > Cons: > * We would have to update it so it isn't IETF specific. > * Text-only - no images except ASCII-art > * Potentially hard to read diffs if they change lots of sections > and therefore include parts of the markup. > > I personally favour options 4 and 5 - I think that option 5 might end up > being the easiest for us because of the wider tool-base. > > Best regards, > Andrew > > _______________________________________________ > cellml-discussion mailing list > cellml-discussion@cellml.org > http://www.cellml.org/mailman/listinfo/cellml-discussion > > > > _______________________________________________ cellml-discussion mailing list cellml-discussion@cellml.org http://www.cellml.org/mailman/listinfo/cellml-discussion
