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
