[PATCH] doc/contributing: update RST text-wrapping guidelines

[PATCH] doc/contributing: update RST text-wrapping guidelines

[Bruce Richardson]

Update and clarify the guidelines on how to wrap lines in our RST docs.
We no longer limit lines to just 80 characters, and what is more
important that line length is the wrapping of sentences, starting a new
sentence on a new line, and wrapping at punctuation.

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
---
 doc/guides/contributing/documentation.rst | 16 +++++++++++-----
 1 file changed, 11 insertions(+), 5 deletions(-)

diff --git a/doc/guides/contributing/documentation.rst b/doc/guides/contributing/documentation.rst
index 4eb62fc36a..9c90efb4ac 100644
--- a/doc/guides/contributing/documentation.rst
+++ b/doc/guides/contributing/documentation.rst
@@ -234,12 +234,18 @@ The most common guidelines for writing RST text are detailed in the
 The additional guidelines below reiterate or expand upon those guidelines.
 
 
-Line Length
-~~~~~~~~~~~
+Line Length and Wrapping
+~~~~~~~~~~~~~~~~~~~~~~~~
 
-* Lines in sentences should be less than 80 characters and wrapped at
-  words. Multiple sentences which are not separated by a blank line are joined
-  automatically into paragraphs.
+* Documentation lines should be less than 100 characters.
+
+* Each sentence should start on a new line.
+  Multiple sentences, which are not separated by a blank line,
+  are joined automatically into paragraphs.
+
+* Wrap sentences at punctuation points, for example, at a comma.
+  If no punctuation, put the newline at a logical point in the sentence,
+  for example, at the end of a clause before an "and" or "but".
 
 * Lines in literal blocks should be less than 80 characters
   since they are not wrapped by the document formatters.
-- 
2.39.2

Re: [PATCH] doc/contributing: update RST text-wrapping guidelines

[Ferruh Yigit]

On 11/3/2023 1:29 PM, Bruce Richardson wrote:
> Update and clarify the guidelines on how to wrap lines in our RST docs.
> We no longer limit lines to just 80 characters, and what is more
> important that line length is the wrapping of sentences, starting a new
> sentence on a new line, and wrapping at punctuation.
> 
> Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
> 

Acked-by: Ferruh Yigit <ferruh.yigit@amd.com>

Re: [PATCH] doc/contributing: update RST text-wrapping guidelines

[Thomas Monjalon]

03/11/2023 14:42, Ferruh Yigit:
> On 11/3/2023 1:29 PM, Bruce Richardson wrote:
> > Update and clarify the guidelines on how to wrap lines in our RST docs.
> > We no longer limit lines to just 80 characters, and what is more
> > important that line length is the wrapping of sentences, starting a new
> > sentence on a new line, and wrapping at punctuation.
> > 
> > Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
> 
> Acked-by: Ferruh Yigit <ferruh.yigit@amd.com>

I'm doing a lot of such minor improvement when merging patches.
I believe it makes doc more confortable to read and update.

Acked-by: Thomas Monjalon <thomas@monjalon.net>

Re: [PATCH] doc/contributing: update RST text-wrapping guidelines

[David Marchand]

On Fri, Nov 3, 2023 at 2:29 PM Bruce Richardson
<bruce.richardson@intel.com> wrote:
>
> Update and clarify the guidelines on how to wrap lines in our RST docs.
> We no longer limit lines to just 80 characters, and what is more
> important that line length is the wrapping of sentences, starting a new
> sentence on a new line, and wrapping at punctuation.
>
> Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>

Acked-by: Ferruh Yigit <ferruh.yigit@amd.com>
Acked-by: Thomas Monjalon <thomas@monjalon.net>

Applied, thanks.

-- 
David Marchand