Hi Jilayne,
None of my comments or documentation was intended to extend the scope of the
SPDX license markups beyond what we discussed at LinuxCon. Feel free to
propose any language in the template documentation that you feel brings it back
inline with the intended scope.
One important question for you – do you think we need to change any of the
technical aspects of the markup language from the proposal? The reason I ask
is that I am in the middle of writing the tools to translate the markup to text
and webpages and I will have some rework to do if we go a different direction.
Additional (somewhat lengthy) thoughts below:
>From my perspective, we can break the discussions into two parts:
1. The technical aspects of how we mark up optional text and variable text
2. How those markups are actually used for the SPDX standard licenses
I believe your concerns relate to #2. I don’t really have a strong opinion on
where to draw the line, so I’ll leave that up to the legal team as to where the
guidelines leave off and the markups begin. From a tool developer, the more
markup the better – but I can understand that there is way too much work
involved in agreeing on the license variability and marking up every standard
license.
Regardless of where the line is drawn, I believe we all agreed that having a
markup language to describe the optional and variable text is a good thing and
something which should be implemented. I believe quite strongly that the
markup language needs to be precise, standardized and documented so that both
humans and tools can interpret the markups in a consistent way. That is not to
say there should be guidelines outside of the markup itself. Even describing
when to use the markup language can be stated in less precise guidelines. I’m
only stating an opinion that once you decide to use the variable and optional
markup language, it has to be done in a consistent way. An example of where
this is required is the tools that generate the SPDX license pages for the SPDX
website. For example, if license A uses ‘{{‘ to describe the rules and license
B uses ‘<<’, the tool that generates the web pages would have to support both +
any additional character other authors may come up with in the future –
generally an impossible programming problem to make work in all cases.
My comments and suggestions all relate to technical aspects on how we mark up
optional text (#1 above). From that perspective, Daniel’s proposal on optional
text seems more natural to me and can include a wider variety scenarios for use
of optional and variable text. It does expand the scope of text we can cover by
allowing variable text to be embedded within optional text.
Gary
From: Jilayne Lovejoy [mailto:[email protected]]
Sent: Thursday, September 12, 2013 9:56 AM
To: Gary O'Neall
Cc: [email protected]; [email protected]; [email protected]
Subject: Re: optional sections in license
so, I feel like we may be expanding this effort or at least not incorporating
the matching guidelines we already have. I thought the idea was to let the
guidelines (see: http://spdx.org/spdx-license-list/matching-guidelines ) guide
tool makers in determining how to match licenses and that we would only provide
mark-up in a license template where there was variable text within the license
itself (e.g. BSD, Apache 1.1) or other ambiguous scenarios (basically, to
provide more specific guidance as to guideline #1). We had discussed at the
Collab Summit meeting on this topic, the desire to balance giving clear-enough
guidance to tool makers and other SPDX document creators, yet not creating such
a narrow set of requirements that would stifle innovation by toolmakers.
For example, the discussion here seems to indicate providing mark-up around any
copyright notice - I thought we had decided that could be dealt with via the
guideline (see #9 and #10 on previous link). If we provide the markup
suggested here, then it seems we will end up with markup on EVERY license, as
pretty much every license has a title, which we have a guideline about (see
#11). So, if we end up marking up the copyright notice, title, text that is
really an addendum, then where do we draw the line? Do we also end up providing
mark-up illustrating the rules on punctuation, bullets and numbering, and so
on? IN which case, why have the guidelines at all?
I'm not suggesting that what Gary and Daniel have proposed here is a bad idea
and I will defer to those with more technical backgrounds, but just trying to
keep some containment on this project - i.e. keep it somewhat simple and stick
to what we have already done, as we can always add complexity later.
If we are going to add more markup to the templates than we originally
discussed, then such rules or markup should perhaps tie to the written
guidelines in some way? I do think having a written explanation and rationale
for the matching guidelines is helpful and necessary (rather than ending up
with templates alone and the guidelines getting sort of left behind, which is
where it feels we might be headed)
thoughts?
Jilayne
SPDX Legal Team lead
On Sep 9, 2013, at 10:49 AM, Gary O'Neall <[email protected]> wrote:
Hi Daniel,
I agree with your proposal for requiring the name of the rule first - it will
make the parsing more straightforward for both humans and computers.
I went back through the meeting notes and found one more syntax difference.
The character following the field was a colon ':' rather than an equals sign
'='. I believe this was to make it consistent with the SPDX tag/value syntax.
Let me know if you're ok with this.
Below is an update to the 1.2 spec (also attached) incorporating these changes
along with the text formatting characters for the original and example text.
If we close on these changes at tomorrow's tech team meeting, I can update the
tools software and produce a new license list in time for Linuxcon.
Gary
----------------------
Appendix II. License Template
Certain sections of a license vary as they are used. Some of this variability
is by design (think of the BSD family of licenses). In other cases it is due to
small changes in licenses as they are copied and propagated. The License
Template describes which sections of the license can be varied and which
sections have standard text.
Standard License List Template Download
The SPDX Standard License List will maintain a template for each of the
licenses in the SPDX Standard License List. The download location for the
current version can be found in the link at the bottom of the page
spdx.org/licenses.
Standard License List Template
RDFa Access: The template text for the standard license can be accessed using
the RDF tag licenseTemplate on the web page containing the standard license.
Template Format
A template is composed of text with zero or more rules embedded in it. A rule
is a variable section of a license wrapped between double angle brackets
“<<>>”. The first tag identifies type of rule followed by additional fields
for that rule type. Each field is separated with a semi-colon “;”.
Fields begin with a case sensitive tag followed by a colon “:”.
Rule Types:
• beginOptional: Optional - All text after this rule and before the
endOptional rule is not required for a valid license match but can be
optionally supplied.
o beginOptional Fields:
§ name: name of the field in the template.
This field is required.
o Example: <<beginOptional;name:copyright>>Copyright ©
optional text<<endOptional>>
o The optional text may include one or more variable
rules. Nest of more than one optional text is not allowed.
• endOptional: Denotes the end of an optional text block. Must be
preceeded by a beginOptional rule. No additional keywords.
• var: Variable text - text matching the regular express must be
supplied to be a valid license
o Fields:
§ original: the original text of the rule. It
should be the first field. It is required.
§ match: a POSIX ERE regular
expression (see below). This field is required.
§ name: name of the field in the template.
This field is required.
§ example: another example of the use of the
text. This field is optional.
o Example: <<var;name:copyright;original: <year>
<owner>;match:.+;example:John Doe>>
The POSIX ERE regular expression has the following restrictions and extensions:
● Semicolons are escaped with \;
● POSIX Bracket Extensions are not allowed
The text fields original and example may contain the following formatting
characters:
• \n – newline
• \t – tab
----------------------
-----Original Message-----
From: .dmg [mailto:[email protected]] On Behalf Of D M German
Sent: Monday, September 09, 2013 6:48 AM
To: Gary O'Neall
Cc: [email protected]; [email protected]; [email protected]
Subject: Re: optional sections in license
Gary> Hi Daniel,
Gary> After thinking about this, I tend to agree that it is more
straightforward Gary> to use the beginOptional and endOptional tags. This
would allow for more Gary> straightforward embedding of variable rules within
optional text. To Gary> simplify the parsing, I would like to restrict the
level and type of Gary> nesting. Proposal:
Yes, and it also makes it simpler to add big sections of optinal text (like the
appendices/addenda/etc).
Gary> - Optional text can embed variable rules
agreed.
Gary> - variable rules cannot embed optional text
So then we don't need the type=required|optional tag in a variable rule, now we
can just wrap it in an beginOptional/endOptional.
Gary> - variable rules cannot embed other variable rules
I totally agree.
Gary> One modification to the rules and optional tag syntax - on one of the
calls Gary> we discussed changing the special characters to '<<' and '>>' from
'{{' and Gary> '}}' since we are not technically using the Mustache syntax.
If it is OK Gary> with you, let's change to the << >> special characters.
I agree too. Let us use << >> instead of {{ }}
One more suggestion, now we have:
- rules (to match variable sections
- beginOptional/endOptional
I feel it would be good to make sure the first token of a <<...>> is the type
of rule. I suggest this:
<<beginOptional;name=uniqueNameInLicense>>
<<endOptional>>
<<var;name=uniqueNameInLicense;...
so the first token is a type of rule. The second is the name (endOptional does
not nened one), and the rest is as required... for example, this is the bsd2:
<<beginOptional;name=copyrightSection>>
Copyright (c) <<var;name=copyright;original= <year>
<owner>;match=.+;example=John Doe>> All rights reserved.
<<endOptional>
Gary> All - let us know if you disagree with the proposed syntax changes for
Gary> optional text. Since we would like to implement this by LinuxConn, we'll
Gary> need feedback by end of day Monday.
Gary> Thanks,
Gary> Gary
Gary> -----Original Message-----
Gary> From: .dmg [mailto:[email protected]] On Behalf Of D M German Gary>
Sent: Friday, September 06, 2013 5:40 PM Gary> To: [email protected];
[email protected] Gary> Cc: [email protected];
[email protected] Gary> Subject: optional sections in license
Gary> Hi Gary, Jilayne, rest of the SPDX technical and legal teams.
Gary> I have been thinking about the optional sections of licenses. I think it
is Gary> not worth it to create a template rule to match optional sections of
known Gary> text
Gary> Template rules were supposed to be intended for sections that are
expected Gary> to vary, not simply sections that can be omitted. I just feel
it Gary> over-complicates things.
Gary> What do you think about specifying variable sections with some sort of
begin Gary> and end marker, and indicate that they optional sections of a
template Gary> cannot be embedded into another one (to avoid recursion).
Gary> For example, something like this (the name will uniquely identify the
Gary> section).
Gary> {{beginOptional;name=anyUniqueName}}
Gary> Text that is optional, including some template rules (for variable
sections Gary> in the optional text)
Gary> {{endOptional}
Gary> For example, the BSD-2 is currently specified as follows:
Gary> {{original=Copyright (c) <year> <owner>\nAll rights Gary>
reserved.;match=Copyright \(c\) .+All rights Gary>
reserved.;name=copyrigh;type=optional;example=Copyright (C) 2013 John Gary>
Doe\nAll rights reserved.}}
Gary> but I think it makes more sense to specify it like this:
Gary> {{beginOptional;name=copyrightStatement}}
Gary> Copyright (c) {{original=<year>
Gary> <owner>.;match=.+;name=copyright;type=optional;example=2013 John Doe}}
All Gary> rights reserved.
Gary> {{endOptional}
Gary> what do you think?
Gary> --dmg
Gary> --
Gary> Daniel M. German "I see no good reason why the
views given in this volume
should shock the religious
Charles Darwin -> feelings of anyone."
Gary> http://turingmachine.org/
Gary> http://silvernegative.com/
Gary> dmg (at) uvic (dot) ca
Gary> replace (at) with @ and (dot) with .
--
Daniel M. German "El pasado es una engañosa utopía
y nada fue tan grato o tan terrible
Germán Dehesa -> como lo recordamos en el presente."
http://turingmachine.org/
http://silvernegative.com/
dmg (at) uvic (dot) ca
replace (at) with @ and (dot) with .
<license template updated proposal 9-9-2013.docx>
_______________________________________________
Spdx-tech mailing list
[email protected]
https://lists.spdx.org/mailman/listinfo/spdx-tech
