spdx@lists.spdx.org | MarkDown conversion of specification live on SPDX GitHub

Home Messages Hashtags Subgroups

Date Date 1 - 9 of 9

MarkDown conversion of specification live on SPDX GitHub

Thomas Steenbergen #1106 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
More All Messages By This Member
Matija Šuklje #1107 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@...
More All Messages By This Member
Kate Stewart #1108 Great work Thomas! Thank you very much for your efforts to get our current (and future) specifications into a more community friendly format! :-) Kate toggle quoted message Show quoted text 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
More All Messages By This Member
Manbeck, Jack #1109 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 toggle quoted message Show quoted text 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
More All Messages By This Member
W. Trevor King #1112 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 signature.asc signature.asc
More All Messages By This Member
Brad Edmondson #1113 +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@... toggle quoted message Show quoted text 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
More All Messages By This Member
Thomas Steenbergen #1114 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@... toggle quoted message Show quoted text 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
More All Messages By This Member
W. Trevor King #1115 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 signature.asc signature.asc
More All Messages By This Member
Matija Šuklje #1116 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@... signature.asc signature.asc
More All Messages By This Member

1 - 9 of 9

1

Previous Topic Next Topic

Home Hashtags Subgroups Terms