-
Notifications
You must be signed in to change notification settings - Fork 133
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Permit comments to be added to SPDX documents #22
Comments
On Tue, Aug 29, 2017 at 05:00:40PM +0000, Kate Stewart wrote:
In RDFa/XML…
RDFa and RDF/XML seem to be two separate things [1].
… - there is a specific term defined.
Do you mean rdfs:comment and such (e.g. [2]). Or CreatorComment [3]?
In tag:value - # - at start of line - need to be added to document.
Things like CreatorComment are already specified in both our
XML-serialized RDF and our tag:value format (see §2.10.5 and 2.10.6
[3]). Are you looking for a higher-level comment analogous to XML's
<!-- … --> [4]? I expect that's the best equivalent for a # line in a
tag:value file.
[1]: https://www.w3.org/wiki/RDFa_vs_RDFXML
[2]: https://github.com/spdx/spdx-spec/blame/cfa1b9d08903befdf03e669da6472707b7b60cb9/chapters/2-document-creation-information.md#L157
[3]: https://github.com/spdx/spdx-spec/blob/cfa1b9d08903befdf03e669da6472707b7b60cb9/chapters/2-document-creation-information.md#2.10
[4]: https://www.w3.org/TR/REC-xml/#sec-comments
|
rdfs:comment |
@wking - it was looking for the equivalent of higher-level comment to XML's. # seems like the best option. |
Do we actually define the tag/value syntax anywhere? This sounds like
another thing that could go in a common constructs chapter [1].
[1]: #16 (comment)
|
This is a large diff, but I aimed for restructuring/polishing without changing the end result. I did make a few minor, intentional changes: * Extended license-id to include appendix I.3 (deprecated licenses). We don't want folks using these in license expressions (because they're deprecated), but they are valid (or we would have removed them instead of just deprecating them). That means that in some cases the nature of a string is unclear. For example 'GPL-1.0+' could be the depreacted license-id, or it could be a simple-expression using the non-deprecated GPL-1.0 license-id and the + operator. I don't think that's a problem though, because I can't think of a case where the ambiguity would matter. * I've allowed + for license-ref (it used to be only for license-id). There could be external licenses which offer a choice between only-this-version and or-later grants, and allowing + for license-ref makes it easier to support those licenses as they transition into the SPDX License List. This isn't a big deal, but it avoids needing separate license-refs for the only-this-version and or-later grants if you need both. * I've added explicit whitespace handling, vs. the previous version which just discussed it in the text. That way the ABNF is the sole source of normative syntax information. * I've added enclosed-license-expression, so consumers like the tag:value format can suggest/require it. This allows for more precision in consumers (e.g. appendix V should be updated to require enclosed-license-expression), but I've left those other sections alone for this commit. Ideally the tag:value line would be moved to a separate section that defined the tag-value format, but we don't have such a section yet [1]. Also, it seems odd that there's no way to define an external license exception (LicenseExceptionRef?). But I haven't touched that in this commit. The RDF/XML bindings seem to have some holes around the + and WITH operators. I've left some FIXMEs where I think we need adjustments. [1]: spdx#22 (comment)
This is a large diff, but I aimed for restructuring/polishing without changing the end result. I did make a few minor, intentional changes: * Extended license-id to include appendix I.3 (deprecated licenses). We don't want folks using these in license expressions (because they're deprecated), but they are valid (or we would have removed them instead of just deprecating them). That means that in some cases the nature of a string is unclear. For example 'GPL-1.0+' could be the depreacted license-id, or it could be a simple-expression using the non-deprecated GPL-1.0 license-id and the + operator. I don't think that's a problem though, because I can't think of a case where the ambiguity would matter. * I've allowed + for license-ref (it used to be only for license-id). There could be external licenses which offer a choice between only-this-version and or-later grants, and allowing + for license-ref makes it easier to support those licenses as they transition into the SPDX License List. This isn't a big deal, but it avoids needing separate license-refs for the only-this-version and or-later grants if you need both. * I've added explicit whitespace handling, vs. the previous version which just discussed it in the text. That way the ABNF is the sole source of normative syntax information. * I've added enclosed-license-expression, so consumers like the tag:value format can suggest/require it. This allows for more precision in consumers (e.g. appendix V should be updated to require enclosed-license-expression), but I've left those other sections alone for this commit. Ideally the tag:value line would be moved to a separate section that defined the tag-value format, but we don't have such a section yet [1]. Also, it seems odd that there's no way to define an external license exception (LicenseExceptionRef?). But I haven't touched that in this commit. The RDF/XML bindings seem to have some holes around the + and WITH operators. I've left some FIXMEs where I think we need adjustments. [1]: spdx#22 (comment)
This is a large diff, but I aimed for restructuring/polishing without changing the end result. I did make a few minor, intentional changes: * Extended license-id to include appendix I.3 (deprecated licenses). We don't want folks using these in license expressions (because they're deprecated), but they are valid (or we would have removed them instead of just deprecating them). That means that in some cases the nature of a string is unclear. For example 'GPL-1.0+' could be the depreacted license-id, or it could be a simple-expression using the non-deprecated GPL-1.0 license-id and the + operator. I don't think that's a problem though, because I can't think of a case where the ambiguity would matter. * I've allowed + for license-ref (it used to be only for license-id). There could be external licenses which offer a choice between only-this-version and or-later grants, and allowing + for license-ref makes it easier to support those licenses as they transition into the SPDX License List. This isn't a big deal, but it avoids needing separate license-refs for the only-this-version and or-later grants if you need both. * I've added explicit whitespace handling, vs. the previous version which just discussed it in the text. That way the ABNF is the sole source of normative syntax information. * I've added enclosed-license-expression, so consumers like the tag:value format can suggest/require it. This allows for more precision in consumers (e.g. appendix V should be updated to require enclosed-license-expression), but I've left those other sections alone for this commit. Ideally the tag:value line would be moved to a separate section that defined the tag-value format, but we don't have such a section yet [1]. Also, it seems odd that there's no way to define an external license exception (LicenseExceptionRef?). But I haven't touched that in this commit. The RDF/XML bindings seem to have some holes around the + and WITH operators. I've left some FIXMEs where I think we need adjustments. The HTML comment avoids the ambiguous four-space indent after the list. Without the comment, it could be parsed as a code block (which is what we want) [2] or a second paragraph of the final list entry [3] (which is not what we want). The HTML comment closes the list to resolve the ambiguity. [1]: spdx#22 (comment) [2]: https://daringfireball.net/projects/markdown/syntax#precode "To produce a code block in Markdown, simply indent every line of the block by at least 4 spaces or 1 tab" [3]: https://daringfireball.net/projects/markdown/syntax#list "Each subsequent paragraph in a list item must be indented by either 4 spaces or one tab"
This is a large diff, but I aimed for restructuring/polishing without changing the end result. I did make a few minor, intentional changes: * Extended license-id to include appendix I.3 (deprecated licenses). We don't want folks using these in license expressions (because they're deprecated), but they are valid (or we would have removed them instead of just deprecating them). That means that in some cases the nature of a string is unclear. For example 'GPL-1.0+' could be the depreacted license-id, or it could be a simple-expression using the non-deprecated GPL-1.0 license-id and the + operator. I don't think that's a problem though, because I can't think of a case where the ambiguity would matter. * I've allowed + for license-ref (it used to be only for license-id). There could be external licenses which offer a choice between only-this-version and or-later grants, and allowing + for license-ref makes it easier to support those licenses as they transition into the SPDX License List. This isn't a big deal, but it avoids needing separate license-refs for the only-this-version and or-later grants if you need both. * I've added explicit whitespace handling, vs. the previous version which just discussed it in the text. That way the ABNF is the sole source of normative syntax information. * I've added enclosed-license-expression, so consumers like the tag:value format can suggest/require it. This allows for more precision in consumers (e.g. appendix V should be updated to require enclosed-license-expression), but I've left those other sections alone for this commit. Ideally the tag:value line would be moved to a separate section that defined the tag-value format, but we don't have such a section yet [1]. * I've added Gary's documentation for spdx:OrLaterOperator [2]; previously there was no way to represent the + operator in RDF/XML. Also, it seems odd that there's no way to define an external license exception (LicenseExceptionRef?). But I haven't touched that in this commit. The RDF/XML bindings seem to have a hole around the WITH operators. I've left a FIXME where I think we need adjustments. The HTML comment avoids the ambiguous four-space indent after the list. Without the comment, it could be parsed as a code block (which is what we want) [3] or a second paragraph of the final list entry [4] (which is not what we want). The HTML comment closes the list to resolve the ambiguity. [1]: spdx#22 (comment) [2]: spdx#37 (comment) [3]: https://daringfireball.net/projects/markdown/syntax#precode "To produce a code block in Markdown, simply indent every line of the block by at least 4 spaces or 1 tab" [4]: https://daringfireball.net/projects/markdown/syntax#list "Each subsequent paragraph in a list item must be indented by either 4 spaces or one tab"
This is a large diff, but I aimed for restructuring/polishing without changing the end result (much). I did make a few intentional changes: * Extended license-id to include appendix I.3 (deprecated licenses). We don't want folks using these in license expressions (because they're deprecated), but they are valid (or we would have removed them instead of just deprecating them). That means that in some cases the nature of a string is unclear. For example 'GPL-1.0+' could be the depreacted license-id, or it could be a simple-expression using the non-deprecated GPL-1.0 license-id and the + operator. I don't think that's a problem though, because I can't think of a case where the ambiguity would matter. * I've allowed + for license-ref (it used to be only for license-id). There could be external licenses which offer a choice between only-this-version and or-later grants, and allowing + for license-ref makes it easier to support those licenses as they transition into the SPDX License List. This isn't a big deal, but it avoids needing separate license-refs for the only-this-version and or-later grants if you need both. * I've added explicit whitespace handling, vs. the previous version which just discussed it in the text. That way the ABNF is the sole source of normative syntax information. * I've added enclosed-license-expression, so consumers like the tag:value format can suggest/require it. This allows for more precision in consumers (e.g. appendix V should be updated to require enclosed-license-expression), but I've left those other sections alone for this commit. Ideally the tag:value line would be moved to a separate section that defined the tag-value format, but we don't have such a section yet [1]. * I've added Gary's documentation for spdx:OrLaterOperator [2]; previously there was no way to represent the + operator in RDF/XML. * I've added Gary's documentation for spdx:WithExceptionOperator [3]. I think it's a bit odd that the XML operator represetation are using URLs instead of the SPDX IDs that the license expression syntax calls for. That means you cannot convert between the two representations without an ID <-> URL map. But we can address that later. * I've removed spdx:LicenseException, because we currently provide no other way for authors to define license exceptions. We do define a way for them to define their own licenses [4], and currently authors have to use that to give a LicenseRef to a license+exception pair if their exception is not in our list. Gary feels like we may return to this later (and I'd be happy giving users a way to define their own exceptions), but we're removing it for now [5]. The HTML comment avoids the ambiguous four-space indent after the list. Without the comment, it could be parsed as a code block (which is what we want) [6] or a second paragraph of the final list entry [7] (which is not what we want). The HTML comment closes the list to resolve the ambiguity. [1]: spdx#22 (comment) [2]: spdx#37 (comment) [3]: spdx#37 (comment) [4]: https://github.com/spdx/spdx-spec/blob/cfa1b9d08903befdf03e669da6472707b7b60cb9/chapters/6-other-licensing-information-detected.md#6.1 [5]: spdx#37 (comment) [6]: https://daringfireball.net/projects/markdown/syntax#precode "To produce a code block in Markdown, simply indent every line of the block by at least 4 spaces or 1 tab" [7]: https://daringfireball.net/projects/markdown/syntax#list "Each subsequent paragraph in a list item must be indented by either 4 spaces or one tab"
This is a large diff, but I aimed for restructuring/polishing without changing the end result (much). I did make a few intentional changes: * Extended license-id to include appendix I.3 (deprecated licenses). We don't want folks using these in license expressions (because they're deprecated), but they are valid (or we would have removed them instead of just deprecating them). That means that in some cases the nature of a string is unclear. For example 'GPL-1.0+' could be the depreacted license-id, or it could be a simple-expression using the non-deprecated GPL-1.0 license-id and the + operator. I don't think that's a problem though, because I can't think of a case where the ambiguity would matter. * I've allowed + for license-ref (it used to be only for license-id). There could be external licenses which offer a choice between only-this-version and or-later grants, and allowing + for license-ref makes it easier to support those licenses as they transition into the SPDX License List. This isn't a big deal, but it avoids needing separate license-refs for the only-this-version and or-later grants if you need both. * I've added explicit whitespace handling, vs. the previous version which just discussed it in the text. That way the ABNF is the sole source of normative syntax information. * I've added enclosed-license-expression, so consumers like the tag:value format can suggest/require it. This allows for more precision in consumers (e.g. appendix V should be updated to require enclosed-license-expression), but I've left those other sections alone for this commit. Ideally the tag:value line would be moved to a separate section that defined the tag-value format, but we don't have such a section yet [1]. * I've added Gary's documentation for spdx:OrLaterOperator [2]; previously there was no way to represent the + operator in RDF/XML. * I've added Gary's documentation for spdx:WithExceptionOperator [3]. I think it's a bit odd that the XML operator represetation are using URLs instead of the SPDX IDs that the license expression syntax calls for. That means you cannot convert between the two representations without an ID <-> URL map. But we can address that later. * I've removed spdx:LicenseException, because we currently provide no other way for authors to define license exceptions. We do define a way for them to define their own licenses [4], and currently authors have to use that to give a LicenseRef to a license+exception pair if their exception is not in our list. Gary feels like we may return to this later (and I'd be happy giving users a way to define their own exceptions), but we're removing it for now [5]. * I've fleshed out the documentation for the + operator to explain how it works with the AGPL-1.0. Without this explaination, I think there's a risk that folks misinterpret ${ROOT}-${BASE_VERSION}+ as "allows ${ROOT}-${VERSION} for any ${VERSION} >= ${BASE_VERSION}", but that's not true. Instead the proper interpretation is "allows ${ROOT}-${VERSION} and any other licenses allowed by ${ROOT-VERSION} which are based on 'any later version' grant". For example, if the AGPL-2.0 had not been released, you could distribute AGPL-1.0+ code under the GPL-3.0+, but *not* under the AGPL-3.0+. The HTML comment avoids the ambiguous four-space indent after the list. Without the comment, it could be parsed as a code block (which is what we want) [6] or a second paragraph of the final list entry [7] (which is not what we want). The HTML comment closes the list to resolve the ambiguity. [1]: spdx#22 (comment) [2]: spdx#37 (comment) [3]: spdx#37 (comment) [4]: https://github.com/spdx/spdx-spec/blob/cfa1b9d08903befdf03e669da6472707b7b60cb9/chapters/6-other-licensing-information-detected.md#6.1 [5]: spdx#37 (comment) [6]: https://daringfireball.net/projects/markdown/syntax#precode "To produce a code block in Markdown, simply indent every line of the block by at least 4 spaces or 1 tab" [7]: https://daringfireball.net/projects/markdown/syntax#list "Each subsequent paragraph in a list item must be indented by either 4 spaces or one tab"
This is a large diff, but I aimed for restructuring/polishing without changing the end result (much). I did make a few intentional changes: * Extended license-id to include appendix I.3 (deprecated licenses). We don't want folks using these in license expressions (because they're deprecated), but they are valid (or we would have removed them instead of just deprecating them). That means that in some cases the nature of a string is unclear. For example 'GPL-1.0+' could be the depreacted license-id, or it could be a simple-expression using the non-deprecated GPL-1.0 license-id and the + operator. I don't think that's a problem though, because I can't think of a case where the ambiguity would matter. * I've allowed + for license-ref (it used to be only for license-id). There could be external licenses which offer a choice between only-this-version and or-later grants, and allowing + for license-ref makes it easier to support those licenses as they transition into the SPDX License List. This isn't a big deal, but it avoids needing separate license-refs for the only-this-version and or-later grants if you need both. * I've added explicit whitespace handling, vs. the previous version which just discussed it in the text. That way the ABNF is the sole source of normative syntax information. * I've added enclosed-license-expression, so consumers like the tag:value format can suggest/require it. This allows for more precision in consumers (e.g. appendix V should be updated to require enclosed-license-expression), but I've left those other sections alone for this commit. Ideally the tag:value line would be moved to a separate section that defined the tag-value format, but we don't have such a section yet [1]. * I've added Gary's documentation for spdx:OrLaterOperator [2]; previously there was no way to represent the + operator in RDF/XML. * I've added Gary's documentation for spdx:WithExceptionOperator [3]. I think it's a bit odd that the XML operator represetation are using URLs instead of the SPDX IDs that the license expression syntax calls for. That means you cannot convert between the two representations without an ID <-> URL map. But we can address that later. * I've removed spdx:LicenseException, because we currently provide no other way for authors to define license exceptions. We do define a way for them to define their own licenses [4], and currently authors have to use that to give a LicenseRef to a license+exception pair if their exception is not in our list. Gary feels like we may return to this later (and I'd be happy giving users a way to define their own exceptions), but we're removing it for now [5]. * I've fleshed out the documentation for the + operator to explain how it works with the AGPL-1.0. Without this explaination, I think there's a risk that folks misinterpret ${ROOT}-${BASE_VERSION}+ as "allows ${ROOT}-${VERSION} for any ${VERSION} >= ${BASE_VERSION}", but that's not true. Instead the proper interpretation is "allows ${ROOT}-${VERSION} and any other licenses allowed by ${ROOT-VERSION} which are based on 'any later version' grant". For example, if the AGPL-2.0 had not been released, you could distribute AGPL-1.0+ code under the GPL-3.0+, but *not* under the AGPL-3.0+. The HTML comment avoids the ambiguous four-space indent after the list. Without the comment, it could be parsed as a code block (which is what we want) [6] or a second paragraph of the final list entry [7] (which is not what we want). The HTML comment closes the list to resolve the ambiguity. [1]: spdx#22 (comment) [2]: spdx#37 (comment) [3]: spdx#37 (comment) [4]: https://github.com/spdx/spdx-spec/blob/cfa1b9d08903befdf03e669da6472707b7b60cb9/chapters/6-other-licensing-information-detected.md#6.1 [5]: spdx#37 (comment) [6]: https://daringfireball.net/projects/markdown/syntax#precode "To produce a code block in Markdown, simply indent every line of the block by at least 4 spaces or 1 tab" [7]: https://daringfireball.net/projects/markdown/syntax#list "Each subsequent paragraph in a list item must be indented by either 4 spaces or one tab"
This is a large diff, but I aimed for restructuring/polishing without changing the end result (much). I did make a few intentional changes: * Extended license-id to include appendix I.3 (deprecated licenses). We don't want folks using these in license expressions (because they're deprecated), but they are valid (or we would have removed them instead of just deprecating them). That means that in some cases the nature of a string is unclear. For example 'GPL-1.0+' could be the depreacted license-id, or it could be a simple-expression using the more-recently-deprecated GPL-1.0 license-id and the + operator. I don't think that's a problem though, because I can't think of a case where the ambiguity would matter. * I've allowed + for license-ref (it used to be only for license-id). There could be external licenses which offer a choice between only-this-version and or-later grants, and allowing + for license-ref makes it easier to support those licenses as they transition into the SPDX License List. This isn't a big deal, but it avoids needing separate license-refs for the only-this-version and or-later grants if you need both. * I've added explicit whitespace handling, vs. the previous version which just discussed it in the text. That way the ABNF is the sole source of normative syntax information. * I've added a paragraph addressing casing, based on discussion in [1]. * I've added enclosed-license-expression, so consumers like the tag:value format can suggest/require it. This allows for more precision in consumers (e.g. appendix V should be updated to require enclosed-license-expression), but I've left those other sections alone for this commit. Ideally the tag:value line would be moved to a separate section that defined the tag-value format, but we don't have such a section yet [2]. * I've added Gary's documentation for spdx:OrLaterOperator [3]; previously there was no way to represent the + operator in RDF/XML. * I've added Gary's documentation for spdx:WithExceptionOperator [4]. I think it's a bit odd that the XML operator represetation are using URLs instead of the SPDX IDs that the license expression syntax calls for. That means you cannot convert between the two representations without an ID <-> URL map. But we can address that later. * I've removed spdx:LicenseException, because we currently provide no other way for authors to define license exceptions. We do define a way for them to define their own licenses [5], and currently authors have to use that to give a LicenseRef to a license+exception pair if their exception is not in our list. Gary feels like we may return to this later (and I'd be happy giving users a way to define their own exceptions), but we're removing it for now [6]. * I've fleshed out the documentation for the + operator to explain how it works with the AGPL-1.0. Without this explaination, I think there's a risk that folks misinterpret ${ROOT}-${BASE_VERSION}+ as "allows ${ROOT}-${VERSION} for any ${VERSION} >= ${BASE_VERSION}", but that's not true. Instead the proper interpretation is "allows ${ROOT}-${VERSION} and any other licenses allowed by ${ROOT-VERSION} which are based on 'any later version' grant". For example, if the AGPL-2.0 had not been released, you could distribute AGPL-1.0-or-later code under the GPL-3.0-or-later, but *not* under the AGPL-3.0-or-later. The HTML comment avoids the ambiguous four-space indent after the list. Without the comment, it could be parsed as a code block (which is what we want) [7] or a second paragraph of the final list entry [8] (which is not what we want). The HTML comment closes the list to resolve the ambiguity. [1]: spdx#63 [2]: spdx#22 (comment) [3]: spdx#37 (comment) [4]: spdx#37 (comment) [5]: https://github.com/spdx/spdx-spec/blob/cfa1b9d08903befdf03e669da6472707b7b60cb9/chapters/6-other-licensing-information-detected.md#6.1 [6]: spdx#37 (comment) [7]: https://daringfireball.net/projects/markdown/syntax#precode "To produce a code block in Markdown, simply indent every line of the block by at least 4 spaces or 1 tab" [8]: https://daringfireball.net/projects/markdown/syntax#list "Each subsequent paragraph in a list item must be indented by either 4 spaces or one tab"
We'll include this in the refactoring of base & profiles; some formats permit comments and others don't, so, lets discuss it there. |
I believe comments are supported in all serializations implemented and planned for 3.0 - so I'm going to close this issue. @kestewart if you think this is still an issue, feel free to reopen |
Comments in SPDX documents (depends on file formats).
In RDFa/XML - there is a specific term defined.
In tag:value - # - at start of line - need to be added to document. Entire line comments.
No middle of comment line in SPDX document.
Comments take the form of '#', as the first non-blank character, and continue to the end of line (marked by characters U+000D or U+000A) or end of file if there is no end of line after the comment marker. Comments are treated as white space.
⇒ Alexios recommends aligning with Turtle
What about SPDX-License-Identifier: ( ) in source code.
"#" ok if disallowed character? Need to check specification.
The text was updated successfully, but these errors were encountered: