Dear Richard Thank you very much for trying this out. It looks really good. Not all the formatting is quite right, as I am sure you know e.g. in the examples, and especially in Appendix D. I see that the doc doesn't say which version it is. I expect you're still working on it.
If this is easier than using docbook to generate the html and pdf then it sounds attractive. I have never used docbook. Jeff Painter's opinion would be valuable. In the "official" version there is markup for changed text, as you know. Is there a way to do this? In fact there is a question, which we've discussed before, about whether we should alter the rules for updates so we don't have to mark so many changes as provisional. At the moment, all changes ever since the first version are still shown as provisional because we have no rule for accepting them as permanent. If we change the rules, however, we might still want to show changes for a while, so a way to do it would be helpful. My main concern is review. CF changes are agreed in trac tickets, and the trac ticket should say exactly what text change is to be made. Once we reach that stage, we then have to decide who is going to make that change in the document source, when they are going to make it, and who will check that it has been done correctly. Up to now, one person (currently Jeff) has made all the changes, at once, and others have informally reviewed the html, for each version. These are governance issues, rather than software issues. Best wishes Jonathan ----- Forwarded message from "Hattersley, Richard" <richard.hatters...@metoffice.gov.uk> ----- > Date: Tue, 27 Jan 2015 16:03:48 +0000 > From: "Hattersley, Richard" <richard.hatters...@metoffice.gov.uk> > To: CF Metadata List <cf-metadata@cgd.ucar.edu> > Subject: [CF-metadata] Editing/publishing workflow update > > Dear all, > > Summary for the time-pressed reader: > - Some of us would like to simplify the workflow for editing the CF > conventions. > - I've made a work-in-progress demo here: > http://cf-metadata.github.io/cf-conventions.html. > - The demo is automatically built from AsciiDoc sources here: > https://github.com/cf-metadata/cf-conventions-asciidoc > - Feedback welcome! What's the appetite for exploring further? > > I've recently delved back into the options for simplifying and automating the > workflow for modifying the CF conventions document. This is in the light of > some useful discussion early last year, and a friendly nudge from Rich > Signell (thanks Rich!). > > In general, this has been an encouraging exploration. Fortunately we are not > at the technological vanguard of the publishing world - others with greater > resources (e.g. O'Reilly) have already paved the way. As a result I believe > we can achieve a very workable solution based around the AsciiDoc > format<http://asciidoctor.org/docs/what-is-asciidoc/>. > > There are three main problems I've been looking at: > > 1. How to get from the current DocBook sources to AsciiDoc? > > 2. How to make the authoring/reviewing process easier? > > 3. How to convert AsciiDoc to HTML and PDF? > > To get from DocBook to AsciiDoc I have extended an existing > solution<https://github.com/rhattersley/docbook2asciidoc> from O'Reilly. They > use the AsciiDoc format in their Atlas publishing platform so they have > already done most of the hard work. Where possible I'd like to get my > extensions merged into their original. > > The authoring/reviewing process relies on GitHub pull requests and their > built-in support for rendering AsciiDoc. This provides a good preview of the > document (although some features of the final HTML output are not rendered), > and an inline reviewing system. (NB. I've split the document into multiple > files, but that is not essential.) Once a change has been accepted the > corresponding HTML (and eventually PDF) is automatically rebuilt and pushed > to the demo website. > > To get from AsciiDoc to HTML/PDF I have used the excellent > asciidoctor<http://asciidoctor.org/> software for HTML and a sister project > for PDF. The HTML support is excellent but the PDF solution is less mature > (there is an alternative which might do better). That said, both projects are > under active support/development and are open to contribution. > > Questions, feedback, encouragement, offers of assistance and/or beer ... > they're all welcome! ;-) > > > Richard Hattersley AVD Expert Software Developer > Met Office FitzRoy Road Exeter Devon EX1 3PB United Kingdom > Tel: +44 (0)1392 885702 Fax: +44 (0)1392 885681 > Email: > richard.hatters...@metoffice.gov.uk<mailto:richard.hatters...@metoffice.gov.uk> > Website: www.metoffice.gov.uk<http://www.metoffice.gov.uk/> > > _______________________________________________ > CF-metadata mailing list > CF-metadata@cgd.ucar.edu > http://mailman.cgd.ucar.edu/mailman/listinfo/cf-metadata ----- End forwarded message ----- _______________________________________________ CF-metadata mailing list CF-metadata@cgd.ucar.edu http://mailman.cgd.ucar.edu/mailman/listinfo/cf-metadata
