docs: standards.md: add more rules: line wrapping and variables
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
@@ -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
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
Signed-off-by Michael Opdenacker <[email protected]>--- documentation/standards.md | 33 ++++++++++++++++++++++++++++++--- 1 file changed, 30 insertions(+), 3 deletions(-)documentation/standards.md +0
-0
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