Hi all,

Wanted to let you all know that after several months in the making I pushed my MarkDown conversion of the SPDX specification 2.1 to  https://github.com/spdx/spdx-spec/

Benefits

·         Working on GitHub and using MarkDown should make it easier for people to contribute either via Git, editing files online or by filling issue

·         Specification now be build as HTML, PDF, ePUB or Mobipocket

·         HTML version is now mobile friendly and PDF has a table of contents

·         Every change on master branch is automatically build and deployed as HTML to https://spdx.github.io/spdx-spec/ (using Travis CI)

Limitations

·         Simplified lay-out as MarkDown has some limitations compared to Google Docs. See for example table of contents – no section included due not being able to directly link to sections within different chapters

To Do

·         Write CONTRIBUTING.md  - explain to contributors how they can participate in shaping future version of the specification. Propose we discuss best workflow in the next call.

·         Minor issues - broken links, lay-out issues or spelling mistakes in original specification

·         Introduce workaround for MarkDown shortcomings in HTML version

·         Automate publishing of PDF, ePUB, Mobipocket to GitHub Releases for a new version of specification

·         Upgrade to GitBook 4.x when it becomes available

All fixes will be made on the development/2.1.1 branch. If you find something feel free to send me an email or raise an issue.

Regards,

Thomas Steenbergen

Principal Engineer Open Source Governance and Policy

HERE Deutschland GmbH, Place of Business: Invalidenstraße 116, 10115 Berlin, Germany – Commercial Register: Amtsgericht Charlottenburg, HRB 106443B - USt-IdNr.: DE 812 845 193 - Managing Directors: Michael Bültmann, Robertus A.J. Houben

Thomas,

This is excellent work. I want to link to the HTML spec from the website. Is it possible to label the 2.1 version so only that shows up on a link?

-        Jack

Hi,

Sorry did not find the time to reply to this thread earlier…

@all: Got asked this a couple times – Why Gitbook and not an alternative like Pandoc? My choice in GitBook was driven since I wanted to reduce the threshold for contributions. GitBook offered a defined format + structure, nice HTML output and a nice all-in-one solution including a WYSIWYG editor with GitHub upload (limited Git knowledge required). Could build this with PanDoc as well, have done so before but would have been more work and harder for others to maintain.

@Matjia: I should have been clearer in the limitation wording. Should have change “Simplified lay-out as MarkDown” to “Simplified lay-out as MarkDown and GitBook“

ToC simplification is because GitBook by default does not allow anchors in its ToC. I have tested several of the ToC plugins you link to but ones I tried either only worked in HTML or had issues. Will complete testing ToC plugins and ten pick one.

As part of fixing broken links I also inserting HTML anchors in MarkDown, hope I find the time to finish this change with next few days and push it to GitHub. My plan is to submit some pull requests to GitBook 4.x to fix some of the limitations I found.

@Jack @Trevor: Yes, it’s possible to build multiple versions on the gh-pages branch but uncommon way of working and think this may confuse users.  Topic was discussed in yesterday’s technical meeting current agreement was to have official releases on spdx.org. I am thinking to extend current Gulp build script with 2 new tasks 1) a task to automate deployment of an official release to spdx.org 2) a task to deploy any new release tag to GitHub Releases

Regards,

Thomas Steenbergen

Principal Engineer Open Source Governance and Policy

HERE Deutschland GmbH, Place of Business: Invalidenstraße 116, 10115 Berlin, Germany – Commercial Register: Amtsgericht Charlottenburg, HRB 106443B - USt-IdNr.: DE 812 845 193 - Managing Directors: Michael Bültmann, Robertus A.J. Houben