search

AMWA-TV / bcp-003

AMWA BCP-003 Security recommendations for NMOS APIs
https://specs.amwa.tv/bcp-003
Apache License 2.0
3 stars 3 forks source link

Footnotes? #24

Closed garethsb closed 5 years ago

garethsb commented 5 years ago

The links to footnotes in https://github.com/AMWA-TV/nmos-api-security/blob/v1.0-dev/best-practice-authorisation.md don't seem to do anything, and nor are the footnotes themselves rendered. Not sure that GitHub-flavour markdown supports footnotes out of the box?

NEOAdvancedTechnology commented 5 years ago

It seems to make little sense to have "invisible" footnotes in Markdown. Perhaps break out into visible Normative Reference section, and where possible have reference hyperlinks going directly to documents (such as RFCs).

peterbrightwell commented 5 years ago

These aren't really "footnotes", they are reference links -- they are helpful to save repetition, to avoid having target URLs in the body of the doc. And to save repetition.

We've used this approach many times before, e.g. the NMOS technical overview and BCP-003-01.

But the syntax was wrong for this document, so I've fixed all that and added a missing link.

As mentioned, you see a list of references in the Markdown but not in the rendered version. Personally I think that's ok.

garethsb commented 5 years ago

OK, hadn't seen this in IS-04 or IS-05, but makes sense now, thanks, Peter.