Online license list omits important limitations

[recursivenomad]

Replaceable text, as presented in the online license list, does not accurately communicate what specific strings are permitted replacements, and may leave some users believing they are permitted to replace such text with any string of their choice.

This issue became apparent following a discussion here: https://github.com/spdx/license-list-XML/issues/1935

I think what was most confusing to me as a new user was:

• A link to explaining Matching Guidelines is not present on license text pages themselves (ie. the pages where the actual colour-coded replaceable text exists)
• The Matching Guidelines do not make clear that "replaceable text" is specifically replaceable text (my assumption was that "replaceable" was being used in the broadest sense of the term)

So from my initial usage, I would suggest presenting a similar note before any license text containing replaceable/omittable text, but ensuring it explains that blue certain text is omittable, and red certain text is replaceable with specific or generic strings. I think it would then be very helpful to link to the XML source following this notice, possibly explaining that such specific information can be found in the XML.

[goneall]

Thanks @recursivenomad for the suggestions.

@jlovejoy @swinslow @recursivenomad I could use some very specific wording suggestions, ideally a pull request to the HTML template files but some text suggestions would work.

[goneall]

I could use some volunteer help on this issue - it would be really nice if we had some hover text, but we would need to add some JavaScript to the templates for this purpose.

Anyone with good HTML / JavaScript skills available to help? BTW, there is a very related issue #135 which could be fixed at the same time.

[zvr]

Hover text can be as simple as declaring a title (no JS needed):

 Hello this is <span title="yes, mine!">my</span> test.

[goneall]

Hover text can be as simple as declaring a title (no JS needed):

Thanks @zvr - sounds easy enough!

Just need some specific text to add and we can update the templates.

[recursivenomad]

@goneall - I can offer my input as a new user referencing the online license list, but I'd think it best to defer to someone more familiar with the project for refining the final language:

A header after the "Notes" section on a license text's page, similar to:

Text in bold blue is omittable and may or may not be included in existing implementations of this license/text. Text in italic red is replaceable with specific strings; hover over such text to reveal existing substitutions. For specific and complete definitions, please view the source here (link to preferred source; for example: XML)

Substituting bold blue and italic red for whatever is ultimately decided by #135

Not sure if this is necessary, but if you choose to use the language above I make it available under CC0-1.0. I can also make a pull request if that is asked of me, if I'm pointed in the right direction for implementing this with minimal HTML knowledge.

[recursivenomad]

Note that the above phrase:

hover over such text to reveal existing substitutions

can be omitted if a more immediate solution is desired prior to implementing hoverable substitution information.

[swinslow]

@goneall Here's my suggestion for the language to be used for this, based on the formatting as it exists today (italics blue and standard red). For the moment I'm deferring on changes to the formatting as it looks like #135 is still open-ended (though important to address -- I just don't know offhand what would be preferred from an accessibility perspective).

Text in italicized blue is omittable (see Matching Guidelines B.3.5). License or exception text will match to the text for the specified identifier if it either includes or excludes this omittable text.

Text in red is replaceable (see Matching Guidelines B.3.4). License or exception text will match to the text for the specified identifier if it includes a permitted variant of this replaceable text. The permitted variants can be found in the corresponding regular expression located within the source XML text in the license-list-XML repo.

If the match regular expression will be visible in <span> text on the license list page itself, along the lines of @zvr's comment above, then I'd probably change the last sentence of the above to instead say something like:

The permitted variants can be found in the corresponding regular expression as shown in title text visible by hovering over the red text.

[jlovejoy]

+1 to @swinslow wording suggestion above. I think it would be great if the link to the XML went to the specific file for that license not just the repo. Is that possible?

[swinslow]

If this text will be included on each license / exception's individual page, then the link could go to:

• Licenses: https://github.com/spdx/license-list-XML/blob/main/src/0BSD.xml (replacing 0BSD with the corresponding identifier)
• Exceptions: https://github.com/spdx/license-list-XML/blob/main/src/exceptions/389-exception.xml (replacing 389-exception with the corresponding identifier)

[goneall]

I'm working on a solution with the wording provided and the hover text.

I struggled a bit with where to put the description text. It seems it should go right after the "Text" title but before the text. I added a separator line to distinguish the description from the actual text.

The hover text has the form: can be replaced with the pattern .{0,20} where .{0,20} is the pattern for the matches.

@swinslow @jlovejoy @recursivenomad - please review the approach and the screenshot below. Note that some of the style for text is not applied in the screenshot.

[recursivenomad]

I like the hierarchy, it makes sense to me. I think it could leave room for ambiguity over the beginning of certain license texts, though... If the legend were more clearly separate from the license text inside of a quote-block or box, and if the separation between legend and license text was labelled clearly to prevent ambiguity for screen readers as well, I think that could help enhance clarity in my mind.

I also like @swinslow's suggestion of linking to a source file somewhere. I'd be partial to not link it in the legend itself to keep things clean, but perhaps a small footnote or similar.

[goneall]

Thanks @recursivenomad for the suggestions. I added a blockquote and a box. For the blockquote I included a citation that points to the SPDX License Match Guidelines.

Here's a screenshot of the current rendering - let me know what you think:

@jlovejoy @swinslow Please review.

[swinslow]

I'm +1 on this -- thanks @goneall!

I could see some slight possibility for confusion if someone (or some script) thinks that the blockquote is actually part of the license text. But (1) I don't have a better suggestion for where else to put the blockquote; and (2) scripts should really be using https://github.com/spdx/license-list-data instead of scraping the website. So I'm good with this!