docs: standards.md: add more rules: line wrapping and variables

From: Michael Opdenacker <michael.opdenacker@bootlin.com>

Fix Markdown syntax too

Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
---
 documentation/standards.md | 33 ++++++++++++++++++++++++++++++---
 1 file changed, 30 insertions(+), 3 deletions(-)

Hi Michael,

Thanks for extending this file so "rules" are explicit :)

On 5/27/22 18:32, Michael Opdenacker via lists.yoctoproject.org wrote:
> From: Michael Opdenacker <michael.opdenacker@bootlin.com>
> 
> Fix Markdown syntax too
> 
> Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
> ---
>   documentation/standards.md | 33 ++++++++++++++++++++++++++++++---
>   1 file changed, 30 insertions(+), 3 deletions(-)
> 
> diff --git a/documentation/standards.md b/documentation/standards.md
> index 81aff5f193..8d5c4542af 100644
> --- a/documentation/standards.md
> +++ b/documentation/standards.md
> @@ -7,6 +7,21 @@ It is currently a work in progress.
>   
>   ## Text standards
>   
> +### Line wrapping
> +
> +Source code for the documentation shouldn't have lines
> +wider than 80 characters. This makes patch lines more
> +readable and code easier to quote in e-mail clients.
> +

This also makes simple diffs harder to read (e.g. a typo which makes the 
line go above the 80 characters limit triggers a change in a lot of 
lines below the one currently being changed). Obviously, whatever the 
character limit, the same issue will arise. But just wanted to point it out.

> +If you have to include long commands or lines in configuration
> +files, provided the syntax makes this possible, split them
> +into multiple lines, using the ``\`` character.
> +

An example here would be great I think.

> +Exceptions are granted for file contents which lines

s/which/whose/ ?

> +cannot be split without infringing syntactic rules
> +or reducing readability, as well as for command output
> +which should be kept unmodified.
> +
>   ### Project names
>   
>   Project names should be capitalized in the same
> @@ -25,11 +40,23 @@ in lower case:
>   
>   ### File names
>   
> -File names should be quoted as in the below example:
> +File, tool and command names should be quoted as in
> +the below example:
> +
> +    ``conf/local.conf``
> +
> +Using `"conf/local/conf"` would be wrong.
> +

"""
File, tool and command names should be double tick-quoted. For example, 
``\`\`conf/local.conf\`\``` is preferred over `"conf/local.conf"`.
"""

I suggest this because it's not "wrong", it's just not something we'd 
like to have in newer patches.

Note the conf/local/conf typo to be fixed if yuou don't go for my 
suggestion.

> +### Variables
> +
> +Every variable should be mentioned with:
>   
> -     ``conf/local.conf``
> +    :term:`VARIABLE`
>   
> -Using "conf/local/conf" would be wrong.
> +This assumes that `VARIABLE` is described either
> +in the Yocto Project documentation variable index (`ref-manual/variables.rst`)
> +or in the BitBake User Manual
> +(`doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst`)
>   

I would add:

"""
If it is not yet described, the variable should be added to the glossary 
before or in the same patch it is used, so that `:term:` can be used.
"""

Cheers,
Quentin