Skip to content
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.

Sign up for GitHub

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

Jump to bottom

Metadata: license #4366

Open
toastal opened this issue Oct 12, 2022 · 9 comments
Open

Metadata: license #4366

toastal opened this issue Oct 12, 2022 · 9 comments

Comments

@toastal
Copy link

toastal commented Oct 12, 2022

I'd like to be able to specify a license for a document. Ideally it would be in the format like:

= My Document
:author: toastal
:license: CC BY-SA 4.0 (https://creativecommons.org/licenses/by-sa/4.0/)
@mojavelinux
Copy link
Member

mojavelinux commented Oct 12, 2022 •
edited

There's definitely nothing stopping you from doing this. If you want this to be propagated to the built-in HTML converter, you'd need to use the attribute name copyright. If you prefer to use the name license, you'd need to use an extension or extended converter to inject it into the HTML.

UPDATE: I now realize that by using copyright, it would end up putting the license text in the copyright meta tag, which is not really correct. So that's not the right recommendation.

@mojavelinux mojavelinux mentioned this issue Oct 12, 2022
Closed
@toastal
Copy link
Author

toastal commented Oct 12, 2022

attribute name copyright

Ah ha. I hadn't seen this one and it didn't come up in my search.

@toastal toastal closed this as completed Oct 12, 2022
@toastal
Copy link
Author

toastal commented Oct 12, 2022 •
edited

Seems there's a rel attribute for license, and it mentions that copyright is a synonym but should be avoided https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel#attr-license

@toastal toastal reopened this Oct 12, 2022
@mojavelinux
Copy link
Member

mojavelinux commented Oct 12, 2022 •
edited

I now recall why we have not yet implemented this. The license meta tag is a link to a license, not arbitrary text. And it's just not clear how exactly that's going to work. If you can provide a more complete example, we might be able to consider it.

@toastal
Copy link
Author

toastal commented Oct 12, 2022 •
edited

In the context of a lot of projects, you may just be linking /LICENSE.txt which would be your specific copy of a license. The copyright is separate I believe which is why, say, the MIT license template has Copyright <YEAR> <COPYRIGHT HOLDER> even though the license is MIT. I'm not going to claim to be a historian 😅, but my assumption would be that the SPDX license title are a result of trying to simplify a system of disparate licenses at some point and unify along a common vernacular we use now like MPL-2.0, 0BSD, etc. (and after reading now, their document says "The SPDX License List includes a standardized short identifier, the full name, the license text, and a canonical permanent URL for each license and exception.").

With the w3 spec (https://html.spec.whatwg.org/multipage/links.html#link-type-license) says historically rel=copyright must be a synonym license when used with rel. Although <meta name="copyright"> appears to be nonstandard, it seems so reasonable to use.

The link should still point to either the exact license like https://my.url/LICENCE.txt or a relative URL, or there a publicly hosted version URL like: https://www.mozilla.org/en-US/MPL/2.0/ or https://creativecommons.org/licenses/by-sa/4.0/ or https://spdx.org/licenses/BSD-3-Clause-No-Nuclear-Warranty.html.

So my new spitball'd idea borrowing from https://asciidoctor.org/ would be:

= My Document
:author: toastal
:copyright: © Copyright {author} 2022
:license: CC BY-SA 4.0 <https://creativecommons.org/licenses/by-sa/4.0/>
<head>
	<title>My Document</title>
	<meta name="author" content="toastal">
	<meta name="copyright" content="© Copyright toastal 2022">
	<link rel="license"title="CC BY-SA 4.0" href="https://creativecommons.org/licenses/by-sa/4.0/">
</head>
<body>
   <!-- ... -->
	<footer id="footer">
		<p>
			<small id="copyright">© Copyright toastal 2022<small><br>
			<small id="license">Content licensed under <a href="https://creativecommons.org/licenses/by-sa/4.0/">CC BY 4.0</a></small>
		</p>
	</footer>
</body>

or

:license: 0BSD </LICENCE.txt>
<link rel="license" title="0BSD" href="/LICENSE.txt">
<small id="license">Content licensed under <a href="/LICENSE.txt">0BSD</a></small>

so...

:license: LABEL OR SHORT CODE <URL TO LICENSE>

It seems parentheses are common enough in license names that it's not a good sigil pair. I would consider it a failure and invalid parse without the <URL TO LICENSE> block.

This said and while aesthetically less pleasing, it has emerged that it would be smarter to make the URL go first as a requirement and the label inside some sigil pair or everything that follows the URL, as a <link> without title is valid and the anchor can just repeat itself <a href="url">url</a>.

:license: <URL TO LICENSE> <LABEL OR SHORT CODE>
:license: /LICENCE.txt OBSD
<link rel="license" title="0BSD" href="/LICENSE.txt">
<small id="license">Content licensed under <a href="/LICENSE.txt">0BSD</a></small>
:license: /LICENCE.txt
<link rel="license" href="/LICENSE.txt">
<small id="license">Content licensed under <a href="/LICENSE.txt">/LICENSE.txt</a></small>

and/or you could be even more creative

:license: /LICENCE.txt BSD Zero Clause License <OBSD>
<link rel="license" title="BSD Zero Clause License" href="/LICENSE.txt">
<small id="license">Content licensed under <a href="/LICENSE.txt"><abbr title="BSD Zero Clause License">0BSD</abbr></a></small>

@mojavelinux
Copy link
Member

Thanks for providing that analyze. Lots of interesting stuff in there.

I could definitely get behind the syntax:

:license: <URL> <text>

The <text> part is optional. We'd split on the first space.

It seems as though you're asking for both a metadata tag (<link>) and a tag in the body <small>. I would be more comfortable not trying to mess with the footer because it already has a very fixed focus on providing only the last updated text, so trying to shoehorn something in there now would likely be too disruptive for the existing HTML converter. We could definitely consider that addition for the new HTML converter, though. So let's focus on the metatag in this issue.

@mojavelinux
Copy link
Member

I'd like to clarify that this is achievable today using docinfo. Here's how that would work. First, you'd define a pair of attributes in your document.

:license-url: /LICENSE.txt
:license-title: 0BSD
:docinfo: shared

Then you'd define docinfo.html as follows:

<link rel="license" title="{license-title}" href="{license-url}">

Then you'd define docinfo-footer.html as follows:

<small id="license">Content licensed under <a href="{license-url}">{license-title}</small>

This might make a nice addition to the docs.

It's not as nice as having support for a license attribute, to be sure. But it's doable.

@toastal
Copy link
Author

toastal commented Oct 13, 2022

:license: <URL> <text>

The more I think about this though, I don't think the SPDX identifier, while common in programming circles, should be the a user's goto or recommended, but instead the full license name like :license: https://spdx.org/licenses/0BSD.html BSD Zero Clause License.

I will definitely look at the docinfo file docs and see if it can solve some of my immediate problems.

@mojavelinux
Copy link
Member

I don't think the SPDX identifier, while common in programming circles, should be the a user's goto or recommended,

The nice part about this proposal is that it doesn't require it. Because of how the license metadata tag is specified, the URL is required. But the text can be anything that will go in the title attribute. That's why I think it makes sense to put the required part first.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
2 participants
@mojavelinux @toastal