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.

• To fix Update README and CONTRIBUTING with markdown format #354

--

Current Table of contents:

• Overview
• Directory organisation
• File content structure and formatting
  • Model file example
• Syntax
  • Classes
  • Datatypes
  • Individuals
  • Properties
  • Vocabularies
• Writing style
• Localisation
  • Localisation example

[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

[bact]

All three additions suggested by @zvr is added:

• 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)
  • So far we only have one for IETF RFCs.
• other languages sections
  • With a Japanese example by @NorioKobota taken from Add Japanese Translation for spdx-3-model repo. #898

Suggestions already incorporated. Will made another request for review.

[zvr]

@bact a couple of suggestions:

• change the filename, since it now suggests something about the SPEC benchmark ;-). Maybe format.md ?
• separate the other-language stuff to translations.md
• ideally we would like to have another doc describing our git branching strategy (not necessarily in this PR)

Maybe move everything to a DOCS subdirectory instead of top-level?

[bact]

Thank you @zvr. I have updated the document, separating it to two files as suggested.

Also move them to a new docs/, together with few other docs.

[zvr]

We can merge this, and improve it later.

Still missing, for example: the file where translations will provide the headings in their own language. But I haven't fully worked it out yet, so no need to wait and block this.