Message ID | 20220527163249.558316-1-michael.opdenacker@bootlin.com |
---|---|
State | New |
Headers | show |
Series | docs: standards.md: add more rules: line wrapping and variables | expand |
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
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. + +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