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
Received on Tue Jan 27 2015 - 11:05:52 GMT
