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:[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
