Generate HTML term page(s) from normative document

[peterdesmet]

1. Move code to GitHub (Migrate DwC code #16)
2. Create a single normative RDF document (including current terms and history)
3. Develop a Python(?) script to generate the HTML term page(s) from the normative document. The pages are: http://rs.tdwg.org/dwc/terms/index.htm and http://rs.tdwg.org/dwc/terms/history/index.htm (and maybe others).
4. Generate document and see if it provides the same functionality as the current page
5. Test by making a change to the normative document and see if the page creates correctly. The script should throw relevant error messages.
6. Document how to use the script (including requirements).

[timrobertson100]

Perhaps just a stylesheet?

Tim,
Sent from my iPhone (which makes terrible auto-correct spelling mistakes)

On 5 Nov 2014, at 17:35, Peter Desmet notifications@github.com wrote:

Move code to GitHub (#16)
Create a single normative RDF document (including current terms and history)
Develop a Python(?) script to generate the HTML term page(s) from the normative document. The pages are: http://rs.tdwg.org/dwc/terms/index.htm and http://rs.tdwg.org/dwc/terms/history/index.htm (and maybe others).
Generate document and see if it provides the same functionality as the current page
Test by making a change to the normative document and see if the page creates correctly. The script should throw relevant error messages.
Document how to use the script (including requirements).
—
Reply to this email directly or view it on GitHub.

[peterdesmet]

I definitely want a stylesheet, but I'm not sure I understand you completely: do you think the rdf document + stylesheet would be enough to render it in a browser? I know nothing about RDF. 😊

[tucotuco]

It should be enough to render part of some pages, with the rest of the page
wrapped around it. There are two pages that need this kind of automated
rendering from the RDF:

http://rs.tdwg.org/dwc/terms/index.htm
http://rs.tdwg.org/dwc/terms/history/index.htm

On Wed, Nov 5, 2014 at 8:30 PM, Peter Desmet notifications@github.com
wrote:

I definitely want a stylesheet, but I'm not sure I understand you
completely: do you think the rdf document + stylesheet would be enough to
render it in a browser? I know nothing about RDF. [image: 😊]

—
Reply to this email directly or view it on GitHub
#17 (comment).

[mdoering]

we could use an XSLT as it is XML based rdf, but honestly I found that harder to read, maintain and Im not convinced it works fine on all browsers. A simple example are the IPT extensions which reference an XSLT for rendering: http://rs.gbif.org/core/dwc_occurrence.xml
I would go for a python script that uses an html template for rendering

[timrobertson100]

Fair enough - was just a suggestion.

There are some fairly mature static site generators now, which might be worth considering (e.g. they let you do common headers, footers, menus, static pages in MD syntax, and then plug in bits like a transformation of RDF-XML -> HTML). I haven't been involved in the design discussions, so I don't know how much of github TDWG plan to use (e.g. relying on the built in readme.MD transformations) versus just hosting of HTML on pages.github.io . If it is the later, a simple SSG might help, as you're likely to grow your own anyway (e.g. stitching in common headers and basic scaffolding stuff).

Disclosure: I've tinkered with SSGs, but not extensively so can't actually point at a preferred one. I'd like to explore assemble.io at some point though, and it looks like a good framework and build pipeline. No RDF->HTML support, but supports handlebar templating so I'd expect a simple template and grunt transformation would be very clean solution.

[peterdesmet]

FYI, I've listed some SSGs that could be useful in the documentation repository: https://github.com/tdwg/dwc-documentation/issues/3. My preference would go to something simple and not reinventing the wheel.

[mdoering]

A new https://github.com/tdwg/dwc/tree/dwc_cleanup/build folder was created that contains artifacts like yaml files, a cheetah template and the main update_terms.py script. That script now generates the terms/index.html file and all resource files (former downloads). See #68

The term version history is not maintained any longer as an RDF file and will be manually curated as the final html