[cellml-discussion] Representing the next version of the CellML Specification

[David Brooks]

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 at cellml.org
> http://www.cellml.org/mailman/listinfo/cellml-discussion
>
>
>
>