Add Format Convention

[ericoporto]

fix #96

File is readable here: FORMAT.md

Leaving as draft for now. Please comment about the format, if it should be a separate document or part of CONTRIBUTING.md, topics that are missing...

[morganwillcock]

If the instructions are in a separate file then it might make sense to use a different name for the current CONTRIBUTING.md file, to make sure that people don't only look at that one (because it is treated as special within GitHub and gets a more prominent link).

One thing that is missing is the actual convention for the Markdown itself, e.g. whether to wrap the text at a particular line length or just use long lines, or whether to use spaces or HTML for inserting line breaks (or perhaps we even say not to insert line breaks?). The heading style is described but it also isn't clear whether someone could use the alternative syntax for a level 2 heading:

Page title
----------

It probably doesn't make sense to use it because there is no alternative syntax for a level 3 heading.

[ericoporto]

One thing that is missing is the actual convention for the Markdown itself,

Oh, this is a good thing I had not payed particular attention. A "General Markdown" chapter to talk on the specific convention for these details.

e.g. whether to wrap the text at a particular line length or just use long lines,

We use both currently, and I don't know how to standardize here. I love manually wrapping text, but I think it may be annoying if it's text that gets updated too often. Perhaps standardizing in long lines? I do prefer separating some comma separated sequences to be on different lines, like in "See also" case, because it's easier to diff in it specifically, so would be alright to have a special case for this?

whether to use spaces or HTML for inserting line breaks (or perhaps we even say not to insert line breaks?).

Using <br> is more visible and obvious. About not inserting line breaks, that is a possibility too, we could revise where we use <br> in the manual and see if it's really needed.

The heading style is described but it also isn't clear whether someone could use the alternative syntax for a level 2 heading

Great point, I think it's good to add a mention saying to never use that style.

[morganwillcock]

Because of the nature of using the wiki for the editing mechanism I don't think we would be able to mandate any function that cannot be performed without an editor, so if I had to pick I'd probably say that long lines are what is used (even though personally I would wrap the lines to get smaller diffs).

I'd also be in favour of removing any type of raw HTML or any "invisible" syntax like trailing spaces. Saying to just never use line breaks would make things simpler for editing. I'm not sure how much the current pages rely on them though.

It may actually be beneficial to try to avoid any syntax which requires back-tracking to parse, just in-case that the pages have to be manually parsed at some point in the future. If it ended up being something similar to Gemtext plus image and table syntax then easy custom tooling would be much more feasible.