Jeff, Thanks for picking up on the governance issue. One of the reasons I included chapter two was to demonstrate how a non-trivial change to the document could be handled.
The governance rules state that changes are to be "shown in the CF documents as provisional", but they do not mandate *how* they are to be shown. The combination of pull-request/commit history and the ability to view changes across versions(*) provides a very capable way to track, audit, and manage change. As you stated previously: > The more readable one doesn't follow the present policy - but maybe that > means the policy should be revised. If it's purely the wording, as opposed to the intent, of the policy that's getting in the way then I would agree. *) For example: https://github.com/cf-metadata/cf-conventions/compare/v1.6...master -----Original Message----- From: CF-metadata [mailto:[email protected]] On Behalf Of Jeffrey F. Painter Sent: 12 March 2014 00:20 To: John Graybeal Cc: Stephen Pascoe; CF metadata Subject: Re: [CF-metadata] Editing/publishing workflow For what I called "policies", see the preface to the CF Conventions document and the rules for changes at http://cf-pcmdi.llnl.gov/governance/governance-rules. Although it's all in there (except for the observed fact that nothing has ever left provisional status), I actually learned what I stated from people on the governance committee telling me that I hadn't done something right. For what I called the 'reST-based partial document', see http://cf-conventions.readthedocs.org/en/v1.6/ - Jeff On 3/11/14 5:10 PM, John Graybeal wrote: > Jeff, > > I couldn't find either the CF Conventions policies, or the 'reST-based > partial document at readthedocs.org'. Can you please provide more specific > pointers? > > John > > On Mar 11, 2014, at 14:08, Jeffrey F. Painter<[email protected]> wrote: > >> The issue of choosing a markup language to use is more involved than it >> might seem. >> >> Here's one of many issues which would have to be settled: >> >> Present CF Conventions policies require that all changes be provisional, and >> marked as such in the document, until determined to be permanent at a later >> time (this determination has never been made). >> That's the meaning of all the pink and yellow highlighting in the document >> at cf-pcmdi.llnl.gov. The version control system (presently svn) keeps >> track of differences, but that's not enough - the document itself has to be >> marked to show what is and isn't provisional. Getting that right is a >> significant part of the job of producing a new version of the document. >> >> So compare, for example, section 2.5.1 of the DocBook-based CF Conventions >> document at cf-pcmdi.llnl.gov (my apologies if the site gets blocked again!) >> with the same section in the reST-based partial document at readthedocs.org. >> The more readable one doesn't follow the present policy - but maybe that >> means the policy should be revised. >> >> - Jeff >> >> On 3/11/14 1:53 PM, Signell, Richard wrote: >>> Richard Hattersley started off this post showing how cool >>> restructured text was rendered: >>> http://cf-conventions.readthedocs.org/en/v1.6/ >>> >>> Why wouldn't we want to go this route? >>> >>> -Rich >>> >>> On Tue, Mar 11, 2014 at 4:47 PM,<[email protected]> wrote: >>>> 1. I think storing the conventions source in git is a great Idea >>>> which will make reviewing updated much easier 2. Markdown (github's wiki >>>> format) may not be the best option. What about latex? >>>> 3. Take a look at Pandoc for format conversion >>>> (http://johnmacfarlane.net/pandoc/). It works great for me and apparently >>>> supports docbook. >>>> >>>> Stephen. >>>> >>>> -- >>>> Stephen Pascoe from iPhone >>>> >>>> On 11 Mar 2014, at 20:29, "Jeffrey F. >>>> Painter"<[email protected]<mailto:[email protected]>> wrote: >>>> >>>> re word processor formats: I'm not going that way, but if I had, it >>>> wouldn't have involved proprietary software. I was tempted because there >>>> was no open-source XML editor which could usefully make sense of all >>>> features of the existing CF Conventions document. >>>> >>>> re markup languages: I haven't looked at any seriously, and most I've not >>>> looked at at all. Most of the CF Conventions document, like most any >>>> document, is simple stuff which anything can handle. But there are >>>> features which I'm not so sure about - custom tags, cross-references, and >>>> color-coded tables come to mind. If an alternative markup language can't >>>> do it all, then we have to consider how much we value the missing features. >>>> >>>> - Jeff >>>> >>>> On 3/11/14 1:14 PM, Chris Barker wrote: >>>> All, >>>> >>>> Converting to a simpler, more tractable markup format would be nice, but a >>>> couple comments: >>>> >>>>> A few months ago I looked into converting to a word processor format, but >>>>> it looked like a much bigger job than I could afford the time for. >>>> Please dont go that way anyway! XML may be a pain, but if you're going to >>>> make a change, make a change to a format that is easier to mange in a >>>> version control system, and doesn't require proprietary software to manage. >>>> >>>> >>>> I am willing to take an initial crack at putting the CF Conventions >>>> document in github format, if that's the missing piece. >>>> >>>> >>>> gitHub supports a number of different markup formats. Markdown is the >>>> default, and is nice an simple, but pretty limited. So take a look at the >>>> other options -- ReStructuredText (RST) may be a better option, for >>>> instance. >>>> >>>> -Chris >>>> >>>> >>>> >>>> John >>>> >>>> On Mar 11, 2014, at 09:44, "Jeffrey F. >>>> Painter"<[email protected]<mailto:[email protected]>> wrote: >>>> >>>>> Richard, >>>>> >>>>> We (meaning LLNL people) don't really have positive plans to stay in >>>>> DocBook format. It is simply less effort to use it than to identify and >>>>> convert to an alternative, if one exists. We recently bought a copy of >>>>> the XMLmind XML Editor, which makes in reasonably tractable to edit in >>>>> DocBook. >>>>> >>>>> I suspect that most markup languages won't do all features used in the CF >>>>> Conventions document. We may be able to work around that, but I'm not >>>>> sure of it. A few months ago I looked into converting to a word >>>>> processor format, but it looked like a much bigger job than I could >>>>> afford the time for. >>>>> >>>>> I would be delighted if you could do this better! You definitely have >>>>> the right idea for where we should be. And I hope that having this >>>>> discussion on the cf-metadata list will bring out some more good ideas. >>>>> For the next few weeks, I don't think we at LLNL will do more than make >>>>> the documents, and the Trac system, reliably available on the web again, >>>>> and put the document sources on github. >>>>> >>>>> - Jeff >>>>> >>>>> >>>>> On 3/11/14 3:22 AM, Hattersley, Richard wrote: >>>>>> Hi Jeff, >>>>>> >>>>>> That's excellent news. And thanks for the update - it'll save me >>>>>> duplicating your efforts. >>>>>> >>>>>> It looks like your current plans are for the source code to stay in >>>>>> DocBook format. Do you also have any plans to allow "instant" visual >>>>>> feedback? For example, to convert it to another format which can be >>>>>> rendered by GitHub (https://github.com/github/markup#markups) or >>>>>> reathedocs.org<http://reathedocs.org>? >>>>>> >>>>>> >>>>>> Richard >>>>>> >>>>>> >>>>>> -----Original Message----- >>>>>> From: CF-metadata >>>>>> [mailto:[email protected]<mailto:cf-metadata-bounc >>>>>> [email protected]>] On Behalf Of Jeffrey F. Painter >>>>>> Sent: 10 March 2014 20:04 >>>>>> To: [email protected]<mailto:[email protected]> >>>>>> Subject: Re: [CF-metadata] Editing/publishing workflow >>>>>> >>>>>> Several of us at LLNL agree that a github-based system is the way to go >>>>>> for the CF Conventions. And the previous messages on this thread turn >>>>>> out to be very timely! >>>>>> >>>>>> For background, over the last few months our Plone-based web site has >>>>>> become unmaintainable as we lost infrastructure support. Just a few >>>>>> days ago I gave up on fixing the system. Matthew Harris has been >>>>>> working on a new web site, located mostly at github. It should be up >>>>>> within a week. >>>>>> >>>>>> The CF Conventions "source code" has for many years been in in DocBook, >>>>>> an xml dialect. It is presently kept in a Subversion repository. We >>>>>> will very likely make this available on github. >>>>>> >>>>>> After the documents, the most important component of the CF Conventions >>>>>> web site is the Trac issue-tracking system. Last week I migrated it to >>>>>> a more recent version on a new machine. Over the next week I plan to >>>>>> migrate it to the latest production version. This will continue to be >>>>>> hosted at LLNL, but a link to it will be on the github site. >>>>>> >>>>>> I hope these changes will serve the CF community at least for the short >>>>>> run, so we can think seriously about what systems to use in the long run. >>>>>> >>>>>> - Jeff Painter >>>>>> >>>>>> On 3/10/14 7:20 AM, Signell, Richard wrote: >>>>>>> Richard, >>>>>>> >>>>>>> I think moving to github would be a huge improvement. The git >>>>>>> model and the tools that github provides would make it much >>>>>>> easier for other folks to propose changes, and for those changes to be >>>>>>> reviewed, >>>>>>> discussed and merged. I think Brian and a few others were also in >>>>>>> favor when we discussed this last fall, but we lacked someone to >>>>>>> carry the flag. >>>>>>> >>>>>>> -Rich >>>>>>> >>>>>>> On Mon, Mar 10, 2014 at 7:35 AM, Hattersley, Richard >>>>>>> <[email protected]<mailto:[email protected]>> >>>>>>> wrote: >>>>>>>> Hi all, >>>>>>>> >>>>>>>> I've recently been dipping into the UGRID conventions >>>>>>>> (https://github.com/ugrid-conventions/ugrid-conventions) and >>>>>>>> was struck by how pleasant the editing/publishing workflow was. >>>>>>>> Clearly from a content complexity point of view the UGRID >>>>>>>> conventions are smaller and simpler than CF so a direct >>>>>>>> comparison is not possible, but to help illustrate some of the >>>>>>>> possibilities I've prepared a cut-down demo version of the CF >>>>>>>> conventions document using GitHub and "Read the Docs". >>>>>>>> >>>>>>>> The published versions of the demo are available from: >>>>>>>> http://cf-conventions.readthedocs.org. I've set the default >>>>>>>> version to 1.6, but by using the options in the bottom-left >>>>>>>> corner of the page it is possible to view 1.7-draft.1 instead. >>>>>>>> There is also a PDF option, but that currently has a few quirks >>>>>>>> which I've not attempted to address. NB. By ticking a box in >>>>>>>> GitHub, these published versions are automatically updated whenever >>>>>>>> the underlying content changes. >>>>>>>> >>>>>>>> The underlying "source code" is defined using reStructuredText >>>>>>>> (reST) markup for processing by the Spinx document generator. It is >>>>>>>> hosted on GitHub at: >>>>>>>> https://github.com/cf-metadata/cf-conventions. I created the >>>>>>>> reST markup using an off-the-shelf HTML-to-reST converter but >>>>>>>> it did require some subsequent manual tweaks. >>>>>>>> >>>>>>>> I've also created a simple "pull request" to illustrate what >>>>>>>> happens when someone proposes a change: >>>>>>>> https://github.com/cf-metadata/cf-conventions/pull/1. NB. By >>>>>>>> default GitHub shows the changes in the source code, but it can >>>>>>>> also show a rendered version of the changes, much like the >>>>>>>> strikeout/highlight style used in the current workflow: >>>>>>>> https://github.com/cf-metadata/cf-conventions/pull/show/1/files >>>>>>>> /e7c84 >>>>>>>> 59#diff-e7c84590262562a10e9fb4cf714098d3 >>>>>>>> >>>>>>>> Is there interest in taking this further? >>>>>>>> >>>>>>>> >>>>>>>> Richard Hattersley >>>>>>>> Benevolent Dictator of Iris - a CF library for Python: >>>>>>>> www.scitools.org.uk/iris<http://www.scitools.org.uk/iris> >>>>>>>> Met Office FitzRoy Road Exeter Devon EX1 3PB United >>>>>>>> Kingdom >>>>>>>> Tel: +44 (0)1392 885702<tel:%2B44%20%280%291392%20885702> >>>>>>>> Email: >>>>>>>> [email protected]<mailto:[email protected]> >>>>>>>> Web: www.metoffice.gov.uk<http://www.metoffice.gov.uk> >>>>>>>> >>>>>>>> >>>>>>>> _______________________________________________ >>>>>>>> CF-metadata mailing list >>>>>>>> [email protected]<mailto:[email protected]> >>>>>>>> http://mailman.cgd.ucar.edu/mailman/listinfo/cf-metadata >>>>>>>> >>>>>> _______________________________________________ >>>>>> CF-metadata mailing list >>>>>> [email protected]<mailto:[email protected]> >>>>>> http://mailman.cgd.ucar.edu/mailman/listinfo/cf-metadata >>>>> _______________________________________________ >>>>> CF-metadata mailing list >>>>> [email protected]<mailto:[email protected]> >>>>> http://mailman.cgd.ucar.edu/mailman/listinfo/cf-metadata >>>> John Graybeal >>>> [email protected]<mailto:[email protected]> >>>> >>>> >>>> >>>> _______________________________________________ >>>> CF-metadata mailing list >>>> [email protected]<mailto:[email protected]> >>>> http://mailman.cgd.ucar.edu/mailman/listinfo/cf-metadata >>>> >>>> >>>> >>>> -- >>>> >>>> Christopher Barker, Ph.D. >>>> Oceanographer >>>> >>>> Emergency Response Division >>>> NOAA/NOS/OR&R (206) 526-6959 voice >>>> 7600 Sand Point Way NE (206) 526-6329 fax >>>> Seattle, WA 98115 (206) 526-6317 main reception >>>> >>>> [email protected]<mailto:[email protected]> >>>> _______________________________________________ >>>> CF-metadata mailing list >>>> [email protected]<mailto:[email protected]> >>>> http://mailman.cgd.ucar.edu/mailman/listinfo/cf-metadata >>>> -- >>>> Scanned by iCritical. >>>> _______________________________________________ >>>> 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 > John Graybeal > [email protected] > > > _______________________________________________ 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
