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 <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.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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mailman.cgd.ucar.edu/pipermail/cf-metadata/attachments/20150127/d1f8095a/attachment-0001.html>
Received on Tue Jan 27 2015 - 10:13:11 GMT
