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
[email protected]
http://www.cellml.org/mailman/listinfo/cellml-discussion
