Hi all, So what's the status of the effort to move the CF editing process to GitHub?
There's a Trac ticket (#92) that has been accepted, but that hasn't yet been added to the v1.7 draft. I'd like to get it added to the draft document on the CF website so that I have an easy (and official) place to reference the new syntax when discussing the files I need to use it for. Is there anything I can do to help that process along? Thanks, --Seth On 2/13/15 1:49 AM, Hattersley, Richard wrote: > 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:[email protected]] 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:[email protected]] 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:[email protected]] 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 > <[email protected]> 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:[email protected]] > 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 > <[email protected]> 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: > [email protected] Website: www.metoffice.gov.uk > > > _______________________________________________ CF-metadata mailing > list [email protected] > http://mailman.cgd.ucar.edu/mailman/listinfo/cf-metadata > > > _______________________________________________ CF-metadata mailing > list [email protected] > 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 [email protected] > http://mailman.cgd.ucar.edu/mailman/listinfo/cf-metadata > _______________________________________________ CF-metadata mailing > list [email protected] > http://mailman.cgd.ucar.edu/mailman/listinfo/cf-metadata > _______________________________________________ CF-metadata mailing > list [email protected] > http://mailman.cgd.ucar.edu/mailman/listinfo/cf-metadata > _______________________________________________ CF-metadata mailing list [email protected] http://mailman.cgd.ucar.edu/mailman/listinfo/cf-metadata
