Yes I'd support that. Restructured text is more powerful than Markdown for large documents. It is not without its quirks but can be worked around.
Also github + readthedocs is a very flexible publishing combination. It works very well for esgf-pyclient. Stephen. -- Stephen Pascoe from iPhone > On 11 Mar 2014, at 20:53, "Signell, Richard" <[email protected]> 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 > > > > -- > Dr. Richard P. Signell (508) 457-2229 > USGS, 384 Woods Hole Rd. > Woods Hole, MA 02543-1598 -- Scanned by iCritical. _______________________________________________ CF-metadata mailing list [email protected] http://mailman.cgd.ucar.edu/mailman/listinfo/cf-metadata
