Jonathan,
You requested to hear more opinions about the provisional status
issue. I think the highlighting of text as provisiona should be
eliminated for all the reasons that John Graybeal mentioned. It just
creates confusion.
If there is a feeling that newly proposed standards need more testing,
we should define a fixed beta release period for each release.
-Rich
On Thu, Jan 29, 2015 at 1:15 PM, Jeffrey F. Painter <painter1 at llnl.gov> wrote:
> Your sample color-coded table looks good. It's wider than before, but
> there's no harm in that.
> I also like your no-risk transition plan.
> - Jeff
>
>
> On 1/29/15 2:34 AM, Hattersley, Richard wrote:
>>
>> Hi Jeff,
>>
>> Thanks for taking a look. I'm greatly relieved to know that you find the
>> AsciiDoc version readable!
>>
>>> 1. ... Do we want to keep the policy on provisional changes? If so, how
>>> do we want to mark the changes?
>>
>> There were some excellent comments made on this topic back in March last
>> year. For me they made a clear case for moving from the current process to a
>> more conventional beta -> release -> bug-fix model. I would heartily support
>> such a change!
>>
>> But from a purely technical point of view, it is entirely possible to
>> preserve the current highlight/strikeout styles.
>>
>>> 2. ... the color-coded tables of chapter 9, are not reproduced in the
>>> AsciiDoc-based html page
>>
>> Well spotted! Rest assured though, it can be done. I saw such features as
>> high-risk, so before attempting the automated conversion I prepared a small,
>> hand-crafted sample to check what was possible:
>> - http://cf-metadata.github.io/cf.html#ortho_multi
>>
>>
>> Regards,
>> Richard
>>
>>
>> -----Original Message-----
>> From: Jeffrey F. Painter [mailto:painter1 at llnl.gov]
>> Sent: 27 January 2015 17:19
>> To: Hattersley, Richard; Gregory, Jonathan; cf-metadata at cgd.ucar.edu
>> Subject: Re: [CF-metadata] Editing/publishing workflow update
>>
>> 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 metoffi
>>>> c 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
--
Dr. Richard P. Signell (508) 457-2229
USGS, 384 Woods Hole Rd.
Woods Hole, MA 02543-1598
Received on Wed Feb 18 2015 - 05:22:37 GMT
