Without making a choice at the moment, I want to highlight that the following are probably the most important aspects to consider in any of these:
1) can represent MathML in either content or presentation format and can render MathML in the HTML output using image replacements instead of expecting that the browser can render MathML (content or presentation) 2) automatic and nested section numbering and automatic generation of a table of contents 3) a reference mechanism so that citations (web or print) can be put together in one place and referenced through a document language citation mechanism 4) that human readable diffs between different versions of the document can be produced easily. One technology not on the list below is Latex. The pros and cons of this should be added also. On 7/11/2007, at 2:16 PM, 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
