I'm looking right now at a pdf version of the Conventions document which
I just built from the sources in github. It has yellow and pink
highlights which represent several years' worth of changes, going back
to version 1.4. The all-in-one-page web version is the same. But, due
to a bug in the build system, the highlighting doesn't show in the
multi-page web version.
- Jeff
On 1/27/15 10:05 AM, Seth McGinnis wrote:
> Speaking as Joe Average User, my impression is that the only purpose of
> marking changes as provisional is to highlight the differences between
> the current version of the spec and the previous version. (It also
> seems like provisional changes are automatically accepted whenever the
> version is incremented, because they're no longer highlighted.)
>
> That's valuable, but if the document is moving onto GitHub, we pretty
> much get that for free, don't we? There are a bunch of ways to compare
> commits and versions on the GitHub website, and you can do comparisons
> with more than just the previous version.
>
> So if that's true, that the point of marking changes as provisional is
> to highlight them, I think it would make sense to abandon that policy
> when moving the update workflow to GitHub. Instead, a simple how-to
> document or links to the appropriate GitHub pages for viewing diffs
> between versions would suffice.
>
> Cheers,
>
> --Seth
>
>
> On 1/27/15 10:18 AM, Jeffrey F. Painter wrote:
>> I've briefly looked at Richard's html example and AsciiDoc source.
>>
>> I'm impressed by the readability of the AsciiDoc source, something which
>> is lacking in DocBook. This would make it much more practical for
>> people to edit it without special software. We badly need that
>> capability. And in most respects the newly generated version of the
>> document looks good!
>>
>> At first glance I noticed two features which seem to be missing in the
>> html example. I'm not sure whether they are essential features, and I
>> don't know whether they can be supported with AsciiDoc. But if moving
>> to AsciiDoc means dropping them, I think we need a community consensus
>> in favor of that.
>>
>> 1. Most important, it has long been policy that all changes to the CF
>> Conventions document are provisional and are to be marked as such. The
>> example html document has no such markings. In the existing system,
>> changes are marked with a highlighting system which I find annoying to
>> read and some trouble to implement. So far, no change has been promoted
>> beyond provisional status. Do we want to keep the policy on provisional
>> changes? If so, how do we want to mark the changes?
>>
>> 2. Some semi-graphical features of the standard document, notably the
>> color-coded tables of chapter 9, are not reproduced in the
>> AsciiDoc-based html page which I see. But in the source code I can see
>> an attempt to reproduce them. If this is just a small bug somewhere,
>> then we can fix it. If reproducing such features requires major work,
>> or is impossible with AsciiDoc, we need to decide whether they are
>> important to us.
>>
>> - Jeff
>>
>> On 1/27/15 8:50 AM, Hattersley, Richard wrote:
>>> 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:cf-metadata-bounces at cgd.ucar.edu] On Behalf
>>> Of Jonathan Gregory
>>> Sent: 27 January 2015 16:32
>>> To: cf-metadata at cgd.ucar.edu
>>> 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"
>>> <richard.hattersley at metoffice.gov.uk> -----
>>>
>>>> Date: Tue, 27 Jan 2015 16:03:48 +0000
>>>> From: "Hattersley, Richard" <richard.hattersley at metoffice.gov.uk>
>>>> To: CF Metadata List <cf-metadata at 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.hattersley at metoffice.gov.uk<mailto:richard.hattersley at metoffic
>>>> e.gov.uk> Website: www.metoffice.gov.uk<http://www.metoffice.gov.uk/>
>>>>
>>>> _______________________________________________
>>>> 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
>>> _______________________________________________
>>> 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
Received on Tue Jan 27 2015 - 13:29:27 GMT
