Dear Jonathan,
Thank you for taking the time to have a look.
> I notice that the Examples are numbered consecutively throughout.
Thanks for the reminder! Yes - we definitely need to preserve the numbering scheme from the current document. This is something I've had my eye on for a while (
http://discuss.asciidoctor.org/Alternative-table-numbering-td2673.html) but I hadn't got around to raising it as an issue on GitHub. Thanks to _at_ocefpaf and yourself that oversight has now been rectified.
> there is explanatory text, which shouldn't be part of the example itself
Thanks - I've added your example to the relevant GitHub issue.
> You haven't got the provisional markup, as previously discussed. It would be useful to hear more opinions on whether we need provisional status or not (that is a separate email thread). Obviously it would make the doc simpler if we did not have to indicate changes.
I'm happy to engage more in that discussion, but I've already expressed an opinion so for now I've been taking a back seat to allow space for others, especially the committee, to have their say.
> Can you generate a PDF?
I can ... but there will probably need to be another thread of work to iron out any wrinkles in the PDF conversion software. Now that the single-page HTML version has made good progress I'll start to give that some attention.
> we need to be clear which of the agreed trac tickets you have implemented, since your version is not 1.6. Is it just as stated at the end of App G?
My version is based directly off the DocBook files on GitHub:
https://github.com/cf-convention/cf-convention.github.io/tree/master/Data/cf-conventions/cf-conventions-1.7/docbooksrc
Because the AsciiDoc form is generated by a conversion script it should be relatively straightforward to base it off a different set of DocBook files. For example, I'd like to run my conversion script on the previous versions of the conventions to allow easy comparison and a consistent, one-stop-shop for all versions.
Regards,
Richard
-----Original Message-----
From: CF-metadata [mailto:cf-metadata-bounces at cgd.ucar.edu] On Behalf Of Jonathan Gregory
Sent: 16 February 2015 11:54
To: cf-metadata at cgd.ucar.edu
Subject: Re: [CF-metadata] Editing/publishing workflow update
Dear Richard
This looks really beautiful. :-) Thank you for your hard work on it.
Looking through it quickly, I notice that the Examples are numbered consecutively throughout. This scheme has some attraction, but it's not been done like that previously, and it has the drawback that if a new example is inserted, all the subsequent ones will change their numbers. That could be confusing for people referring to different versions of the standard. So it may be better to stick to the current pattern of numbering them within each section. What do you think? Can you do it?
In some examples, there is explanatory text, which shouldn't be part of the example itself. For instance, in Example 31 in Sect 7.4, the part "This example shows ..." should appears as ordinary text within the example. This is Example
7.8 in CF version 1.6, for comparison.
You haven't got the provisional markup, as previously discussed. It would be useful to hear more opinions on whether we need provisional status or not (that is a separate email thread). Obviously it would make the doc simpler if we did not have to indicate changes.
To make a detailed comparison, I would find it most convenient to print it out.
Can you generate a PDF? Also to make such a comparison we need to be clear which of the agreed trac tickets you have implemented, since your version is not 1.6. Is it just as stated at the end of App G? Since 1.6 is dated 5 Dec 2011, your version would therefore include those tickets said to have been included since then, by Jeff I guess.
Best wishes
Jonathan
----- Forwarded message from "Hattersley, Richard" <richard.hattersley at metoffice.gov.uk> -----
> Date: Fri, 13 Feb 2015 08:49:10 +0000
> From: "Hattersley, Richard" <richard.hattersley at metoffice.gov.uk>
> To: CF Metadata List <cf-metadata at cgd.ucar.edu>
> Subject: Re: [CF-metadata] Editing/publishing workflow update
>
> re: http://cf-metadata.github.io/cf-conventions.html
>
> I've been tinkering in the evenings and now the AsciiDoc form of the conventions is somewhere near "alpha release" quality. It still has some small quirks here and there but the big issues should all be fixed.
>
> As ever, feedback/bug reports are very welcome.
>
> Regards,
> Richard
>
>
> -----Original Message-----
> From: CF-metadata [mailto:cf-metadata-bounces at cgd.ucar.edu] On Behalf
> Of Hattersley, Richard
> Sent: 04 February 2015 09:04
> To: CF Metadata List
> Subject: Re: [CF-metadata] Editing/publishing workflow update
>
> Dear all,
>
> I have a created a GitHub project to encapsulate the DocBook->AsciiDoc conversion.
> - https://github.com/cf-metadata/convert
>
> All contributions to this effort are very welcome. For example, it would be very helpful to compare the existing HTML version of the CF conventions[1] to the version generated from AsciiDoc[2] and record any flaws as GitHub issues[3]. Or if you would like to get involved at a technical level, then please feel free to submit pull requests updating the conversion process.
>
> [1] -
> http://cfconventions.org/Data/cf-conventions/cf-conventions-1.7/build/
> cf-conventions.html [2] -
> http://cf-metadata.github.io/cf-conventions.html
> [3] - https://github.com/cf-metadata/convert/issues
>
>
> Regards,
> Richard Hattersley
>
>
> -----Original Message-----
> From: CF-metadata [mailto:cf-metadata-bounces at cgd.ucar.edu] On Behalf
> Of Hattersley, Richard
> Sent: 29 January 2015 10:21
> To: Signell, Richard
> Cc: CF Metadata List
> Subject: Re: [CF-metadata] Editing/publishing workflow update
>
> > there is still a fair amount of work left to be done converting the document.
> > Is that something that will improve with your improvements to the
> > conversion tool, or will some community manual editing help be required?
>
> My current plan is to improve the conversion rather than use manual editing. That way the AsciiDoc version can be regarded as just another "rendered" version of the DocBook sources. I'd like to avoid having two "definitive" versions of the conventions at the same time.
>
> If all goes well (e.g. no technical hurdles) and a consensus for change can be reached then the final switch from DocBook to AsciiDoc should be relatively quick.
>
> > Also, will there be a way to get nice syntax highlighting in blocks
> > of code like example 21?
>
> Yes, but ... I don't think any of the normal syntax highlighting packages (e.g. pygments) have a specific mode for CDL. So either we pretend the example is in another language (which might well give excellent results) or we knock up an extension for CDL.
>
>
> Regards,
> Richard
>
>
> From: Signell, Richard [mailto:rsignell at usgs.gov]
> Sent: 27 January 2015 17:13
> To: Hattersley, Richard
> Cc: Filipe Pires Alvarenga Fernandes; CF Metadata List
> Subject: Re: [CF-metadata] Editing/publishing workflow update
>
> Richard,
> Wow, thanks for doing all this hard work for the CF community! ??
>
> I think Asciidoc is okay since it renders in Github and, as you say, has a richer model more analogous to docbook.
>
> Looking at:
> http://cf-metadata.github.io/cf-conventions.html
> it looks like there is still a fair amount of work left to be done converting the document. ?? ??Is that something that will improve with your improvements to the conversion tool, or will some community manual editing help be required?
>
> Also, will there be a way to get nice syntax highlighting in blocks of code like example 21?
>
> On Tue, Jan 27, 2015 at 11:33 AM, Hattersley, Richard <richard.hattersley at metoffice.gov.uk> wrote:
> Hi Filipe,
> ??
> Thanks for the encouragement!
> ??
> I choose AsciiDoc because it has a much richer data model than Markdown, and because that data model was deliberately aligned with that of DocBook. In the words of the great oracle of Wikipedia: ???AsciiDoc is a human-readable document format, semantically equivalent to DocBook XML???. This makes the conversion from DocBook relatively straightforward (although admittedly DocBook has a lot of features!) and avoids it being lossy.
> ??
> As for the offer of help ... thank you! If this idea gets enough support, my current plan is to collate the limitations/failures in the current conversion processes and start hacking at code. For now I???m not planning on editing the AsciiDoc files by hand. This is because I???m currently assuming that automatic conversion from DocBook to AsciiDoc is a Good Thing (tm) so we can re-use the same conversion to port all the prior versions to GitHub if necessary or if the latest DocBook version is updated in the meantime.
> ??
> Richard
> ??
> ??
> From: Filipe Pires Alvarenga Fernandes [mailto:ocefpaf at gmail.com]
> Sent: 27 January 2015 16:21
> To: Hattersley, Richard
> Cc: CF Metadata List
> Subject: Re: [CF-metadata] Editing/publishing workflow update ??
> These are wonderful news!?? The editing, tracking, and publishing workflow will be extremely easy if this is adopted.?? Not to say that it will be more democratic as well thanks to GitHub PRs.
> ??
> I have one question and two offer.
> ??
> Question: ??Why Asciidoc instead of Markdown? ??(I noticed that, like
> for markdon source, GitHub renders HTML from the Asciidoc source.?? This is nice for quick visualization.) ??
> Offers: ??I am available to help and to pay a beer ;-) ??
> PS: Loved the travis trick to push to gh-pages!
> ??
> On Tue, Jan 27, 2015 at 1:03 PM, Hattersley, Richard <richard.hattersley at metoffice.gov.uk> wrote:
> 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.
> ??
> 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 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 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.hattersley at metoffice.gov.uk?? Website:
> www.metoffice.gov.uk ??
>
> _______________________________________________
> CF-metadata mailing list
> CF-metadata at cgd.ucar.edu
> http://mailman.cgd.ucar.edu/mailman/listinfo/cf-metadata
> ??
>
> _______________________________________________
> CF-metadata mailing list
> CF-metadata at cgd.ucar.edu
> http://mailman.cgd.ucar.edu/mailman/listinfo/cf-metadata
>
>
>
>
> --
> Dr. Richard P. Signell ?? (508) 457-2229 USGS, 384 Woods Hole Rd.
> Woods Hole, MA 02543-1598
> _______________________________________________
> CF-metadata mailing list
> CF-metadata at cgd.ucar.edu
> http://mailman.cgd.ucar.edu/mailman/listinfo/cf-metadata
> _______________________________________________
> CF-metadata mailing list
> CF-metadata at cgd.ucar.edu
> http://mailman.cgd.ucar.edu/mailman/listinfo/cf-metadata
> _______________________________________________
> CF-metadata mailing list
> CF-metadata at cgd.ucar.edu
> http://mailman.cgd.ucar.edu/mailman/listinfo/cf-metadata
----- End forwarded message -----
_______________________________________________
CF-metadata mailing list
CF-metadata at cgd.ucar.edu
http://mailman.cgd.ucar.edu/mailman/listinfo/cf-metadata
Received on Wed Feb 18 2015 - 05:10:28 GMT
