Hi Andrew, I think the ability to easily add and maintain internal cross references is pretty essential for the specification, although such things could probably always be resolved with some pre/post-processing script. Might be easier in terms of support if its an already existing feature of the language and/or editing tools.
Prior to the plone-based cellml.org site all the CWML documentation was superseded by docbook versions - except the specifications. I think at the time we decided that docbook was the way to go forward but with limited resources and the complexity of the specifications we were happy to leave the source of the existing specifications in CWML, with the thought that future versions of the specification would be re-written using docbook. I have successfully used docbook with MathML for a couple of different projects. It all works pretty much as expected - at least I can't recall any major hassles :) Personally, I'd vote against 1, 3, and 6; and in favour of 4 or 5; and would be interested in 2 if someone could demonstrate a cross referencing solution. And agree with Andrew that 5 might be the easiest to get started with. Andre. 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 -- David Nickerson, PhD Research Fellow Division of Bioengineering Faculty of Engineering National University of Singapore Email: [EMAIL PROTECTED] _______________________________________________ cellml-discussion mailing list cellml-discussion@cellml.org http://www.cellml.org/mailman/listinfo/cellml-discussion
