Regarding using the repository to show changes - this wasn't practical
with the svn repository because it wasn't public. Very soon the DocBook
sources will be visible to everyone on github.
The preface to the CF Conventions document does specify how provisional
changes are to be displayed, and it specifies a highlighting system.
But we have a procedure for changing that. Maybe this can be the first
new ticket after I finish upgrading the Trac system on its new host
(I've upgraded from 0.10 to 0.12, and will finish with 1.0).
You may have gathered that I don't think the highlighting system has
worked as well as originally intended, so I would welcome a change -
whether or not we continue to use DocBook, etc.
On a higher level, my point in bringing this up was that there are a lot
of issues and complexities we have to consider before changing the
language or format used for the CF Conventions document. More will
appear if anyone tries to do a complete conversion.
- Jeff
On 3/12/14 4:30 AM, Hattersley, Richard wrote:
> 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:cf-metadata-bounces at cgd.ucar.edu] 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<painter1 at llnl.gov> 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,<stephen.pascoe at stfc.ac.uk> 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"<painter1 at llnl.gov<mailto:painter1 at llnl.gov>> 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"<painter1 at llnl.gov<mailto:painter1 at llnl.gov>> 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:cf-metadata-bounces at cgd.ucar.edu<mailto:cf-metadata-bounc
>>>>>>> es at cgd.ucar.edu>] On Behalf Of Jeffrey F. Painter
>>>>>>> Sent: 10 March 2014 20:04
>>>>>>> To: cf-metadata at cgd.ucar.edu<mailto:cf-metadata at cgd.ucar.edu>
>>>>>>> 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
>>>>>>>> <richard.hattersley at metoffice.gov.uk<mailto:richard.hattersley at metoffice.gov.uk>> 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: richard.hattersley at metoffice.gov.uk<mailto:richard.hattersley at metoffice.gov.uk> Web: www.metoffice.gov.uk<http://www.metoffice.gov.uk>
>>>>>>>>>
>>>>>>>>>
>>>>>>>>> _______________________________________________
>>>>>>>>> CF-metadata mailing list
>>>>>>>>> CF-metadata at cgd.ucar.edu<mailto: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<mailto: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<mailto:CF-metadata at cgd.ucar.edu>
>>>>>> http://mailman.cgd.ucar.edu/mailman/listinfo/cf-metadata
>>>>> John Graybeal
>>>>> jbgraybeal at mindspring.com<mailto:jbgraybeal at mindspring.com>
>>>>>
>>>>>
>>>>>
>>>>> _______________________________________________
>>>>> CF-metadata mailing list
>>>>> CF-metadata at cgd.ucar.edu<mailto:CF-metadata at cgd.ucar.edu>
>>>>> 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
>>>>>
>>>>> Chris.Barker at noaa.gov<mailto:Chris.Barker at noaa.gov>
>>>>> _______________________________________________
>>>>> CF-metadata mailing list
>>>>> CF-metadata at cgd.ucar.edu<mailto:CF-metadata at cgd.ucar.edu>
>>>>> http://mailman.cgd.ucar.edu/mailman/listinfo/cf-metadata
>>>>> --
>>>>> Scanned by iCritical.
>>>>> _______________________________________________
>>>>> 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
>> John Graybeal
>> jbgraybeal at mindspring.com
>>
>>
>>
> _______________________________________________
> CF-metadata mailing list
> CF-metadata at cgd.ucar.edu
> http://mailman.cgd.ucar.edu/mailman/listinfo/cf-metadata
Received on Wed Mar 12 2014 - 11:41:59 GMT
