From eb633e611d8ba7d3805b1c5c9db7b46016d6025e Mon Sep 17 00:00:00 2001
From: Michael Opdenacker <michael.opdenacker@bootlin.com>
Date: Fri, 27 May 2022 18:27:28 +0200
Subject: [PATCH] docs: standards.md: add more rules: line wrapping and
 variables

Fix Markdown syntax too

(From yocto-docs rev: f836a2fbe401865d3e9af691d71de97e9c5df70a)

Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
---
 documentation/standards.md | 43 ++++++++++++++++++++++++++++++++++----
 1 file changed, 39 insertions(+), 4 deletions(-)

diff --git a/documentation/standards.md b/documentation/standards.md
index 81aff5f193..abdebc82bf 100644
--- a/documentation/standards.md
+++ b/documentation/standards.md
@@ -7,6 +7,29 @@ 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.
+
+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.
+
+Here is an example:
+
+    $ scripts/install-buildtools \
+      --without-extended-buildtools \
+      --base-url https://downloads.yoctoproject.org/releases/yocto \
+      --release yocto-4.0.1 \
+      --installer-version 4.0.1
+
+Exceptions are granted for file contents whose lines
+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
@@ -23,13 +46,25 @@ in lower case:
 * When used in a cross-reference title. Such
   titles are usually in lower case.
 
-### File names
+### File, tool and command names
 
-File names should be quoted as in the below example:
+File, tool and command names should be double tick-quoted.
+For example, ``` ``conf/local.conf`` ``` is preferred over
+`"conf/local.conf"`.
 
-     ``conf/local.conf``
+### Variables
 
-Using "conf/local/conf" would be wrong.
+Every variable should be mentioned with:
+
+    :term:`VARIABLE`
+
+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`)
+
+If it is not described yet, the variable should be added to the
+glossary before or in the same patch it is used, so that `:term:` can be used.
 
 ## ReStructured Text Syntax standards