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 <[email protected]> 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:[email protected]] >> Sent: 27 January 2015 17:19 >> To: Hattersley, Richard; Gregory, Jonathan; [email protected] >> 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:[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@metoffi >>>> c 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 > > > _______________________________________________ > CF-metadata mailing list > [email protected] > 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 _______________________________________________ CF-metadata mailing list [email protected] http://mailman.cgd.ucar.edu/mailman/listinfo/cf-metadata
