Jonathan,
Thanks for the rapid feedback.
Not all the formatting is quite right, as I am sure you know e.g. in
the examples, and especially in Appendix D.
Quite so. If this idea has wings then we'll need to record all these
deficiencies.
I see that the doc doesn't say which version it is.
It does at the top, but it's quite small. This is just the default
rendering style though so could be changed. I'm guessing normal books
don't care about the version that much!
I expect you're still working on it.
That remains to be seen... but I suspect so. ;-)
In the "official" version there is markup for changed text, as you
know. Is there a way to do this?
There is, but my current pipeline explicitly removes such things to
show the document in its "finalised" form.
Jeff Painter's opinion would be valuable.
Absolutely!
My main concern is review.
I see no reason why the current trac process couldn't remain for now.
Once the changes have been finalised on trac then someone (probably
either the originator or a maintainer) could submit those changes via
GitHub, with reference to the trac original.
However, there is the potential for even greater benefit if the trac
tickets themselves are moved to GitHub. This would allow inline
reviewing of proposed changes.
Either way, one or more people (e.g. Jeff) would need to be given
merge rights to the GitHub repo. (To be clear, I am not trying to get
myself on that list!)
Regards,
Richard
-----Original Message-----
From: CF-metadata [mailto:[email protected]] On Behalf
Of Jonathan Gregory
Sent: 27 January 2015 16:32
To: [email protected]
Subject: [CF-metadata] Editing/publishing workflow update
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"
<[email protected]> -----
Date: Tue, 27 Jan 2015 16:03:48 +0000
From: "Hattersley, Richard" <[email protected]>
To: CF Metadata List <[email protected]>
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:
[email protected]<mailto:richard.hattersley@metoffic
e.gov.uk> Website: www.metoffice.gov.uk<http://www.metoffice.gov.uk/>
_______________________________________________
CF-metadata mailing list
[email protected]
http://mailman.cgd.ucar.edu/mailman/listinfo/cf-metadata
----- End forwarded message -----
_______________________________________________
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
