Scholarly HTML website up at http://scholarlyhtml.org

I have set up a website for Scholarly HTML at http://scholarlyhtml.org. The site is intended to hold some key documents about Scholarly HTML, what it is, lists of tools etc. It will be populated as time allows. I will announce this on the Scholarly HTML mailing list now, and invite people from Beyond the PDF when it is a bit more mature.

We are going to continue with document authoring taking place over on the EtherPads provided by the Open Knowledge Foundation I will call for people to review and update documents from time to time, and when there is consensus I will post them to the site. I am happy to give other responsible adults those powers as well if they want them. The EtherPad entry point is: http://scholarly-html.okfnpad.org/1.

I am trying out a WordPress deployment pattern I have been thinking about for a while to use the WordPress ‘stack of posts’ as a version control mechanism every version of every document is a post, and is intended to be immutable (that’s a governance issue). There will be a WordPress page for each node in the site, but it won’t have any content, rather it will run a query to find the last post (as opposed to page) from a particular category. For example, The faq page at http://scholarlyhtml.org/faq/ runs a query to find the latest post labelled as faq eg http://scholarlyhtml.org/2011/03/25/faq-2011-03-25/. The point of this is to get a full revision history in a simple way.

My experience with EtherPad is that it is great for collaboration and awful for formatting, so I am proposing to use wiki-style markup in the pad making the job of publishing much easier. There are a number of such formats. I was introduced to asciidoc recently. It has rich formatting for technical documents and an established toolchain for creating HTML, PDF and EPUB. It is a bit finicky and I’m not sure if it is the best candidate for a format to support authoring of Scholarly HTML but it does seem to be more complete than many. Rending EtherPad documents is as easy as this:

curl http://okfnpad.org/ep/pad/export/schtml-core/latest?format=txt | asciidoc -vs - > core.html

That creates a core.html file. To post it to the site I can use this command to push the content to WordPress as an unpublished document with the category ‘core’:

blogpost.py -vu -d html -t "Scholarly HTML core" -c core post core.html

As I get time I will change the markup in the EtherPads over to asciidoc and invite the collaborators back to work on them happy to discuss alternative formatting arrangements if anyone objects to asciidoc.

Copyright Peter Sefton, 2011-04-15. Licensed under Creative Commons Attribution-Share Alike 2.5 Australia. <http://creativecommons.org/licenses/by-sa/2.5/au/>

This post was written in OpenOffice.org, using templates and tools provided by the Integrated Content Environment project.

  • Ian Barnes

    Hi Peter,

    For what it’s worth, I’ve been using Markdown for a few things recently and to me it looks more natural than asciidoc. More output options and more implementations too, at least according to that Wikipedia comparison page. Also better known I think.

    Ian

    • http://ptsefton.com ptsefton

      I looked at Markdown as part of pandoc, but it does not have table markup (uses plain HTML), and for the JISCPUB project pandoc was not suitable as its EPUB generation does not support internal links such as footnotes. Then again pandoc has an HTML input filter, and asciidoc does not seem to.

  • http://ptsefton.com ptsefton

    Test comment.