-
Notifications
You must be signed in to change notification settings - Fork 44
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
Make URL clickable. #751
Make URL clickable. #751
Conversation
Signed-off-by: Marc-Etienne Vargenau <marc-etienne.vargenau@nokia.com>
In general we need to have
and not
because I think it was a restriction of the ISO standard formatting (IIRC). But maybe things have evolved; I'll ask around. |
Nice catch. Another different behavior between MkDocs and GitHub. GitHub can automatically render this to a clickable link: https://www.iana.org/ For the same result, MkDocs needs this: <https://www.iana.org/> See an example in https://spdx.github.io/spdx-spec/v3.0/model/Core/Datatypes/MediaType/ |
So I understand I should replace things like:
by
What should I do with things like:
Should I remove the link? We have such kind of links in e.g. (file docs/serializations.md in https://github.com/spdx/spdx-spec) |
I'd say we pause this one till we know (and test) the exact production process, so that we know what the requirements will be. It makes no sense to make changes now and have to make other changes later. |
Agree with @zvr on the pause, the knowledge of production process, and the test. With that, we should make the knowledge and the test available and accessible more to the spec contributors. (for example, how to set up a local test) More documentation on how spdx-3-model, spdx-spec, spec-parser, and mkdocs are working together to generate the final spec website are welcome. spdx/spdx-spec#946 is part of the attempt. |
Btw, it is totally understandable that we were not given the priority to such the documentation before this, since we were all focused on the release of 3.0. Now we have less pressure on that. |
@vargenau From the machine point of view, both are valid Markdown and will get rendered perfectly (and identically) with mkdocs. From the human point of view, the latter is more friendly for the human editor, less cluttered. It is less error-prone as well, because you don't have to worry about misspelling another URL.
If it is the ISO requirement to have the URL in clear (to make the URL visible when printed on paper), then we should expand it. It can be something like: RFC 2046 <https://www.ietf.org/rfc/rfc2046.txt> or in a style according to our style guide (which I'm not sure if we have one). |
So, the final outcome is that we can (and must) have links not showing, like:
which is written as:
and the production process will translate it to footnotes in the ISO standard. |
Co-authored-by: Alexios Zavras (zvr) <zvr+git@zvr.gr> Signed-off-by: Kate Stewart <13152682+kestewart@users.noreply.github.com>
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Changes look reasonable to me. Thanks for adding these.
All links are already got covered. We can close this PR. |
Thank you @vargenau for the PR, as we learn along the process about subtle differences between Markdown renderers. |
Closing PR, as links have been handled by other PRs. |
No description provided.