Skip to contentSkip to conversation

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

PATCH Superseded [email protected] 2 participants 2 messages May 27, 2022 – May 31, 2022

v1 of 2 Superseded Latest is v2 →

lore
Share & tools
lore
#0 lore raw

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

From: Michael Opdenacker <[email protected]>

Fix Markdown syntax too

---
 documentation/standards.md | 33 ++++++++++++++++++++++++++++++---
 1 file changed, 30 insertions(+), 3 deletions(-)
documentation/standards.md +30 -3
index 81aff5f193..8d5c4542af 100644
@@ -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.
+
+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.
+
+Exceptions are granted for file contents which 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
@@ -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.
+
+### 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`)
 
 ## ReStructured Text Syntax standards
 
Signature · 1 line
2.25.1
#1 lore raw

Hi Michael,

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

Quoted 14 lines · Michael Opdenacker via lists.yoctoproject.org

From: Michael Opdenacker <[email protected]>

Fix Markdown syntax too

---
  documentation/standards.md | 33 ++++++++++++++++++++++++++++++---
  1 file changed, 30 insertions(+), 3 deletions(-)
documentation/standards.md +0 -0
index 81aff5f193..8d5c4542af 100644

documentation/standards.md It is currently a work in progress. · line 15

Quoted 9 lines
documentation/standards.md +6 -0
@@ -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.

documentation/standards.md It is currently a work in progress. · line 19

Quoted 4 lines
documentation/standards.md +4 -0
+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.

documentation/standards.md It is currently a work in progress. · line 20

Quoted 1 line
documentation/standards.md +1 -0
+Exceptions are granted for file contents which lines

s/which/whose/ ?

Quoted 9 lines
documentation/standards.md +4 -0
+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:
 

documentation/standards.md in lower case: · line 49

Quoted 10 lines
documentation/standards.md +7 -1
  ### 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.

documentation/standards.md in lower case: · line 60

Quoted 13 lines
documentation/standards.md +8 -2
+### 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