Re: [cellml-discussion] Representing the next version of the CellML Specification
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
Re: [cellml-discussion] Representing the next version of the CellMLSpecification
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) is the use of image based equations still required? if people are using a browser which is not capable of rendering MathML, either natively or via a plugin, they can browse the PDF version instead? Much like the current options for viewing the model mathematics in the model repository. ___ cellml-discussion mailing list cellml-discussion@cellml.org http://www.cellml.org/mailman/listinfo/cellml-discussion
Re: [cellml-discussion] Representing the next version of the CellML Specification
Matt wrote: 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 I presume that you include references by number to automatically numbered sections (without having to manually enter the numbers) as part of this requirement? I don't think that automatically numbered sections give us much without this (unless we are going to refer to sections by name in the text and have an anchored link, which is a bit unconventional and isn't great if someone wants to read a printed copy of the specification). 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. 7) LaTeX Pros: * Widely tested * Numerous output formats * Automated table of contents, section numbering, and section references Cons: * Would probably need to develop styles specifically for the specifications unless we can find one. * Math support is non-MathML. * Geared more towards typesetting rather than generation of HTML-type document * Potentially hard to read diffs if they change lots of sections and therefore include parts of the markup (although perhaps easier than XML, depending on taste and familiarity with each markup language). Best regards, Andrew 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
