docs: standards.md: add more rules: line wrapping and variables
PATCH v2 1/1 docs: standards.md: add more rules: line wrapping and variables
In reply to a message not in the archiveFrom: Michael Opdenacker <[email protected]>
Fix Markdown syntax too
Signed-off-by Michael Opdenacker <[email protected]>
--- documentation/standards.md | 43 ++++++++++++++++++++++++++++++++++---- 1 file changed, 39 insertions(+), 4 deletions(-)
documentation/standards.md +39 -4
@@ -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, tool and command names should be double tick-quoted. +For example, ``` ``conf/local.conf`` ``` is preferred over +`"conf/local.conf"`. + +### Variables + +Every variable should be mentioned with: -File names should be quoted as in the below example: + :term:`VARIABLE` - ``conf/local.conf`` +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`) -Using "conf/local/conf" would be wrong. +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
Signature · 1 line
2.25.1