{"action":"opened","issue":{"url":"https://api.github.com/repos/tdwg/vocab/issues/25","labels_url":"https://api.github.com/repos/tdwg/vocab/issues/25/labels{/name}","comments_url":"https://api.github.com/repos/tdwg/vocab/issues/25/comments","events_url":"https://api.github.com/repos/tdwg/vocab/issues/25/events","html_url":"https://github.com/tdwg/vocab/issues/25","id":99447412,"number":25,"title":"Should specific formats be required or specified for human-readable documents?","user":{"login":"baskaufs","id":5765781,"avatar_url":"https://avatars.githubusercontent.com/u/5765781?v=3","gravatar_id":"","url":"https://api.github.com/users/baskaufs","html_url":"https://github.com/baskaufs","followers_url":"https://api.github.com/users/baskaufs/followers","following_url":"https://api.github.com/users/baskaufs/following{/other_user}","gists_url":"https://api.github.com/users/baskaufs/gists{/gist_id}","starred_url":"https://api.github.com/users/baskaufs/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/baskaufs/subscriptions","organizations_url":"https://api.github.com/users/baskaufs/orgs","repos_url":"https://api.github.com/users/baskaufs/repos","events_url":"https://api.github.com/users/baskaufs/events{/privacy}","received_events_url":"https://api.github.com/users/baskaufs/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":0,"created_at":"2015-08-06T14:21:58Z","updated_at":"2015-08-06T14:21:58Z","closed_at":null,"body":"In section 9, the [draft Standards Documentation Specification](https://github.com/tdwg/vocab/blob/master/tdwg-stds-spec.pdf) says \"all files in a standard must be in an open format for which parsers are commonly available\" and lists some acceptable formats. Section 11 says \"Normative human readable documents should be in XHTML format\".  I think the intent there was to make the standard easily accessible and easily viewable.  This recommendation hasn't always been followed, with some documents saved as Word documents (not an open format) or in open formats other than XHTML.  \r\n\r\nHTML seems like a nice format because it can be marked up in a standard way and anybody can view it in a browser.  But now MarkDown, GitHub Flavored MarkDown (GFM), and various wiki syntaxes are commonly used.  Should they be allowed?  If we continue to manage the standards repo at GitHub, then GFM would be very convenient.  But even with converters like PanDoc, it's hard to get a clean conversion between formats.  \r\n\r\nAt the moment, I'm thinking that specific allowed formats should not be proscribed in a Standards Documentation Standard.  One could simply say that the human-readable documents should be easily accessible via the Web, be in an open format, and easily viewable.  This would allow for MarkDown (in the context of GitHub), HTML (in the context of a \"normal\" website), or PDF (which on most computers when accessed via a web link will either be displayed directly in a browser or will launch an application that can display it).  "}}