Add documentation for Markdown headings used in spec generation

[bact]

Add a documentation about headings and formatting used in Markdown files for the specification generation.

This will allow contributors to better familiarise with the format that is expected from the spec-parser.

If there is an update in the spec-parser, this document should be updated as well.

Information about specific formatting to support localization can be added in the future.

[bact]

@zvr @goneall does this document best to be inside this spdx-3-model repo or in the spec-parser repo?

I can open new PR in spec-parser if it is more preferred (and close this one here).

[goneall]

Good catch @bact

[zvr]

I am not sure if we want to spend time trying to define everything.

We definitely need to also address multi-lingual content (maybe not right now, but in the future).

[goneall]

@zvr - Are you OK with merging this? From the tech call, we felt there was value in documenting this for those doing localization / internationalization for the model.

[kestewart]

Not sure we should leave a "Blah" in the text, but rest looks fine.

[zvr]

I'll review it in detail later this week, but it would be nice to define what our (long-term?) goal will be, @kestewart @goneall .

If we are to produce another PDF version, then my suggestion would be to limit the markdown that can be used, since currently I need to manually change some stuff to produce the PDF. If, on the other hand, we only care about the website (HTML version), then it's perfectly fine to leave "allow everything", as long as it renders fine.

From a quick look, we could add info on:

• links (all have to have text, no bare URLs)
• standardized formats (we have for RFCs, I don't remember whether there is already anything else)
• other languages sections