Topics

MarkDown conversion of specification live on SPDX GitHub


Thomas Steenbergen
 

 

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

 

 

 


Matija Šuklje
 

Die 03. 07. 17 et hora 20.53.18 Steenbergen, Thomas scripsit:
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/
Brilliant! Thank you.

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
ToC with sections or subchapters of whatever depth should be doable and not
an issue with MarkDown itself, but with whatever software generates the
HTML/PDF/ePub/… from MarkDown.

There seems to be several ToC plugins for GitBook:
https://plugins.gitbook.com/browse?q=toc

e.g. this one:
https://plugins.gitbook.com/plugin/simple-page-toc
has a `maxDepth` option, with which you can select how deep it should go. The
default seems to be 3 levels (i.e. subsubsection).

For in-sentence references this would probably work:
https://stackoverflow.com/questions/5319754/cross-reference-named-anchor-in-markdown

Potentially useful for footnotes as well:
https://plugins.gitbook.com/plugin/footnote-string-to-number

· Introduce workaround for MarkDown shortcomings in HTML version
AFAIK simply using HTML tags is always a workaround in MarkDown.


cheers,
Matija
--
gsm: tel:+386.41.849.552
www: http://matija.suklje.name
xmpp: matija.suklje@...
sip: sip:matija_suklje@...


Kate Stewart
 

Great work Thomas!

Thank you very much for your efforts to get our current (and future) specifications
into a more community friendly format!  :-)

Kate

On Mon, Jul 3, 2017 at 3:53 PM, Steenbergen, Thomas <thomas.steenbergen@...> wrote:

 

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

 

 

 


_______________________________________________
Spdx mailing list
Spdx@...
https://lists.spdx.org/mailman/listinfo/spdx



Manbeck, Jack
 

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

 

 

From: spdx-bounces@... [mailto:spdx-bounces@...] On Behalf Of Steenbergen, Thomas
Sent: Monday, July 03, 2017 4:53 PM
To: spdx@...
Cc: opensource@...
Subject: MarkDown conversion of specification live on SPDX GitHub

 

 

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

 

 

 

 


W. Trevor King
 

On Thu, Jul 06, 2017 at 02:38:24PM +0000, Manbeck, Jack via Spdx wrote:
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?
Once appoach to that would be having gulp build master and and all
tags (that have Markdown content), instead of just building master.
For example:

https://spdx.github.io/spdx-spec/

would be the master build,

https://spdx.github.io/spdx-spec/2.1.1-rc1/

would be a build of the 2.1.1-rc1 tag if/when that tag is made,

https://spdx.github.io/spdx-spec/2.1.1/

would be abuild of the 2.1.1 release if/when that tag is made, etc.
I'm happy to help with tooling for this if it sounds useful.

Cheers,
Trevor

--
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy


Brad Edmondson
 

+1 for continuous build (I think that's what gulp is), and it gives you linkable tags for free. Very nice.

--
Brad Edmondson, Esq.
512-673-8782 | brad.edmondson@...

On Mon, Jul 10, 2017 at 1:41 PM, W. Trevor King <wking@...> wrote:
On Thu, Jul 06, 2017 at 02:38:24PM +0000, Manbeck, Jack via Spdx wrote:
> 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?

Once appoach to that would be having gulp build master and and all
tags (that have Markdown content), instead of just building master.
For example:

  https://spdx.github.io/spdx-spec/

would be the master build,

  https://spdx.github.io/spdx-spec/2.1.1-rc1/

would be a build of the 2.1.1-rc1 tag if/when that tag is made,

  https://spdx.github.io/spdx-spec/2.1.1/

would be abuild of the 2.1.1 release if/when that tag is made, etc.
I'm happy to help with tooling for this if it sounds useful.

Cheers,
Trevor

--
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy

_______________________________________________
Spdx mailing list
Spdx@...
https://lists.spdx.org/mailman/listinfo/spdx



Thomas Steenbergen
 

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

 

From: <spdx-bounces@...> on behalf of Brad Edmondson <brad.edmondson@...>
Reply-To: "brad.edmondson@..." <brad.edmondson@...>
Date: Monday 10 July 2017 at 22:54
To: "W. Trevor King" <wking@...>
Cc: "opensource@..." <opensource@...>, "spdx@..." <spdx@...>
Subject: Re: MarkDown conversion of specification live on SPDX GitHub

 

+1 for continuous build (I think that's what gulp is), and it gives you linkable tags for free. Very nice.


--

Brad Edmondson, Esq.
512-673-8782 | brad.edmondson@...

 

On Mon, Jul 10, 2017 at 1:41 PM, W. Trevor King <wking@...> wrote:

On Thu, Jul 06, 2017 at 02:38:24PM +0000, Manbeck, Jack via Spdx wrote:
> 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?

Once appoach to that would be having gulp build master and and all
tags (that have Markdown content), instead of just building master.
For example:

  https://spdx.github.io/spdx-spec/

would be the master build,

  https://spdx.github.io/spdx-spec/2.1.1-rc1/

would be a build of the 2.1.1-rc1 tag if/when that tag is made,

  https://spdx.github.io/spdx-spec/2.1.1/

would be abuild of the 2.1.1 release if/when that tag is made, etc.
I'm happy to help with tooling for this if it sounds useful.

Cheers,
Trevor

--
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy

_______________________________________________
Spdx mailing list
Spdx@...
https://lists.spdx.org/mailman/listinfo/spdx

 


W. Trevor King
 

On Wed, Jul 12, 2017 at 03:25:22PM +0000, Steenbergen, Thomas wrote:
@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<https://github.com/spdx/spdx-spec/releases>
This works. And for folks who want to pass references around and who
do not need the GitBook additions, you can use GitHub's source browser
and it's default Markdown rendering. For example, [1,2].

Cheers,
Trevor

[1]: https://github.com/spdx/spdx-spec/blob/231b27009182d92d6ec06582c71ad307d10dc0a6/chapters/appendix-IV-SPDX-license-expressions.md#3-exception-with-operator
[2]: https://github.com/spdx/spdx-spec/blame/231b27009182d92d6ec06582c71ad307d10dc0a6/chapters/appendix-IV-SPDX-license-expressions.md#L90

--
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy


Matija Šuklje
 

Die 12. 07. 17 et hora 15.25.22 scripsis:
@all: Got asked this a couple times – Why Gitbook and not an alternative
like Pandoc?
[…]
@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“
That makes a lot of sense. And again, huge kudos for all the time you invested
in this migration and above all with gathering more contributions in mind.

If none of the ToC plugins work, we could try to modify one, or as a last
resort, simply make the chapters hierarchy flat. What do you think?


cheers,
Matija
--
gsm: tel:+386.41.849.552
www: http://matija.suklje.name
xmpp: matija.suklje@...
sip: sip:matija_suklje@...