Re: [cellml-discussion] Representing the next version of the CellML Specification
I don't know much (if anything!) about the solutions offered here, but: - the current HTML version is nice for viewing from a web browser, but if you have ever tried to print things out you will no doubt have noticed that it doesn't look great anymore. I remember that there used to be a 'proper' PDF version of the specifications. I really wish we still had something like that. - Besides the obvious (i.e. easy to use, easy to maintain, well-established technology, etc.), I am not too fussed about the solution we go for, as long as it is suitable for the end user (e.g. looks nice both on and off the web site). This being all said, and based on Andrew's pros/cons, I would personally vote for DocBook. Alan. ___ 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
On 8/11/2007, at 10:27 AM, Randall Britten wrote: Hi all Another option to add to the mix: using a Wiki. In this case, I would specifically suggest MediaWiki (a la Wikipedia). Pros: -Widely used, lots of user familiarity. -Easy collaboration: edits done via web interface. -Built in diffs and revision history. -Linking when done via web interface works well. -Can be rendered as PDF on demand (haven't tested this myself, but docs say it can be done). Cons: -Requires setup and maintenance of another content management system. Unsure: -Usually Mathml handled with LaTex substrings, not sure how to handle MathML in MediaWiki. For the purpose of presentation math, LaTex substrings get my vote. They are simple to express and their diffs in my opinion are easier to interpret than diffs of MathML/XML. More generally, I think XML source formats should be avoided if possible. Regards, Randall ___ 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: On 8/11/2007, at 10:27 AM, Randall Britten wrote: Hi all Another option to add to the mix: using a Wiki. In this case, I would specifically suggest MediaWiki (a la Wikipedia). Pros: -Widely used, lots of user familiarity. -Easy collaboration: edits done via web interface. -Built in diffs and revision history. -Linking when done via web interface works well. -Can be rendered as PDF on demand (haven't tested this myself, but docs say it can be done). Cons: -Requires setup and maintenance of another content management system. Unsure: -Usually Mathml handled with LaTex substrings, not sure how to handle MathML in MediaWiki. Also, the difference between this and the previous suggestions is that MediaWiki is a software package as much as a format - it is difficult to separate the format from the software package so that you can work with files on your local system and then render them (although perhaps it could be done with a little bit of PHP coding), which means that the wiki software imposes a highly centralised revision and change control model on us in addition to providing a format for the representation of the data. I am not sure that the wiki change-control system is very good for writing open specifications as part of a community effort - wikis are only efficient for collaboration if you have a policy of making changes and then discussing them afterwards, and changes need to be either 'rolled back' fairly quickly after they were applied, or manually corrected later. This won't really work if there are lots of different ways to do the same thing. People can copy and paste wiki pages to somewhere else to make a private branch, but that will lose all change control history. One thing we discussed at our Auckland meeting yesterday was the possibility of using a more distributed version control system. This approach looks promising, but before we can really ask the community to make a decision on this we need to set up some examples of how it could work, so I am planning on getting an informal example git repository up in the near future. The problem with MediaWiki-type format is that storing a format which cannot easily be converted directly to HTML with a command line tool doesn't really play well with this mode of specification development. Best regards, Andrew For the purpose of presentation math, LaTex substrings get my vote. They are simple to express and their diffs in my opinion are easier to interpret than diffs of MathML/XML. More generally, I think XML source formats should be avoided if possible. Regards, Randall ___ 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
Re: [cellml-discussion] Representing the next version of the CellML Specification
Randall Britten wrote: Hi all Another option to add to the mix: using a Wiki. In this case, I would specifically suggest MediaWiki (a la Wikipedia). Hi Randall, Pros: -Widely used, lots of user familiarity. Although MediaWiki mark-up is similar to MoinMoin and other wiki software have taken the idea, I am not sure that the exact same markup is widely used in terms of tool diversity. Wikipedia and other MediaWiki-powered sites are very popular, so that one particular software package may have been widely used compared to some of the other options (although HTML, DocBook, TeX, and ReST are also very ubiquitous). -Easy collaboration: edits done via web interface. -Built in diffs and revision history. -Linking when done via web interface works well. -Can be rendered as PDF on demand (haven't tested this myself, but docs say it can be done). Cons: -Requires setup and maintenance of another content management system. Also note that MediaWiki-style markup has many of the same cons as reStructuredText * No section references by number based on reference by name in the source. * No automatic numbering aside from numbered lists (e.g. no counters). Unsure: -Usually Mathml handled with LaTex substrings, not sure how to handle MathML in MediaWiki. As Matt said, this is an adequate representation of presentation mathematics (content mathematics would of course be represented in literal blocks, so any math representation is probably adequate). Matt also said More generally, I think XML source formats should be avoided if possible. I don't agree with that, because for many purposes XML does provide a very good compromise between tool simplicity and human readability, and often the unambiguous and simple rules aid both human and machine processing of the document. MathML is an example of where unaided human processing of an XML format becomes unwieldy and error prone, because the requirement for unambiguous mathematical mark-up ends making the language too verbose. However the same concerns don't apply when there are WYSIWYG editors (e.g. for HTML), or where the mark-up does not have to be so dense (for example, delimiting paragraphs, but having whole paragraphs as text nodes). In this case you can feasibly put the tags on their own lines and readability is not that bad (although following structural changes may be more difficult). Best regards, Andrew Regards, Randall -Original Message- From: [EMAIL PROTECTED] [mailto:cellml-discussion- [EMAIL PROTECTED] On Behalf Of Alan Garny Sent: Wednesday, 7 November 2007 9:46 p.m. To: 'CellML Discussion List' Subject: Re: [cellml-discussion] Representing the next version of the CellML Specification I don't know much (if anything!) about the solutions offered here, but: - the current HTML version is nice for viewing from a web browser, but if you have ever tried to print things out you will no doubt have noticed that it doesn't look great anymore. I remember that there used to be a 'proper' PDF version of the specifications. I really wish we still had something like that. - Besides the obvious (i.e. easy to use, easy to maintain, well- established technology, etc.), I am not too fussed about the solution we go for, as long as it is suitable for the end user (e.g. looks nice both on and off the web site). This being all said, and based on Andrew's pros/cons, I would personally vote for DocBook. Alan. ___ 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 ___ 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
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 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
