[PATCH v1] doc: change doc line length limit in contributors guide

[PATCH v1] doc: change doc line length limit in contributors guide

[John McNamara]

The DPDK documentation guidelines state that lines should be wrapped as
follows:

* The recommended style for the DPDK documentation is to put sentences on
  separate lines. This allows for easier reviewing of patches. ...
* Long sentences should be wrapped at 120 characters +/- 10 characters.
  They should be wrapped at words.

  http://dpdk.org/doc/guides/contributing/documentation.html#line-length

However, in practice, users almost never submit doc patches in this format.
Instead most users wrap their doc patches at 80 characters.

This patch updates the documentation contributors guide to reflect this
as the recommended guideline.

Signed-off-by: John McNamara <john.mcnamara@intel.com>
---
 doc/guides/contributing/documentation.rst | 36 +++++++++++--------------------
 1 file changed, 12 insertions(+), 24 deletions(-)

diff --git a/doc/guides/contributing/documentation.rst b/doc/guides/contributing/documentation.rst
index 4c85da7..0cb6010 100644
--- a/doc/guides/contributing/documentation.rst
+++ b/doc/guides/contributing/documentation.rst
@@ -282,33 +282,21 @@ The additional guidelines below reiterate or expand upon those guidelines.
 Line Length
 ~~~~~~~~~~~
 
-* The recommended style for the DPDK documentation is to put sentences on separate lines.
-  This allows for easier reviewing of patches.
-  Multiple sentences which are not separated by a blank line are joined automatically into paragraphs, for example::
+* 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.
 
-     Here is an example sentence.
-     Long sentences over the limit shown below can be wrapped onto
-     a new line.
-     These three sentences will be joined into the same paragraph.
+* Lines in literal blocks **must** by less than 80 characters since
+  they aren't wrapped by the document formatters and can exceed the page width
+  in PDF documents.
 
-     This is a new paragraph, since it is separated from the
-     previous paragraph by a blank line.
+  Long literal command lines can be shown wrapped with backslashes. For
+  example::
 
-  This would be rendered as follows:
-
-     *Here is an example sentence.
-     Long sentences over the limit shown below can be wrapped onto
-     a new line.
-     These three sentences will be joined into the same paragraph.*
-
-     *This is a new paragraph, since it is separated from the
-     previous paragraph by a blank line.*
-
-
-* Long sentences should be wrapped at 120 characters +/- 10 characters. They should be wrapped at words.
-
-* Lines in literal blocks must by less than 80 characters since they aren't wrapped by the document formatters
-  and can exceed the page width in PDF documents.
+     testpmd -l 2-3 -n 4 \
+             --vdev=virtio_user0,path=/dev/vhost-net,queues=2,queue_size=1024 \
+             -- -i --txqflags=0x0 --disable-hw-vlan --enable-lro \
+             --enable-rx-cksum --txq=2 --rxq=2 --rxd=1024  --txd=1024
 
 
 Whitespace
-- 
2.7.4

Re: [PATCH v1] doc: change doc line length limit in contributors guide

[Thomas Monjalon]

11/05/2017 16:09, John McNamara:
> The DPDK documentation guidelines state that lines should be wrapped as
> follows:
> 
> * The recommended style for the DPDK documentation is to put sentences on
>   separate lines. This allows for easier reviewing of patches. ...
> * Long sentences should be wrapped at 120 characters +/- 10 characters.
>   They should be wrapped at words.
> 
>   http://dpdk.org/doc/guides/contributing/documentation.html#line-length
> 
> However, in practice, users almost never submit doc patches in this format.
> Instead most users wrap their doc patches at 80 characters.
> 
> This patch updates the documentation contributors guide to reflect this
> as the recommended guideline.
> 
> Signed-off-by: John McNamara <john.mcnamara@intel.com>
> ---
> --- a/doc/guides/contributing/documentation.rst
> +++ b/doc/guides/contributing/documentation.rst
> @@ -282,33 +282,21 @@ The additional guidelines below reiterate or expand upon those guidelines.
>  Line Length
>  ~~~~~~~~~~~
>  
> -* The recommended style for the DPDK documentation is to put sentences on separate lines.
> -  This allows for easier reviewing of patches.
> -  Multiple sentences which are not separated by a blank line are joined automatically into paragraphs, for example::
> +* 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.

Why not keep the recommendation of separating sentences?

> +     testpmd -l 2-3 -n 4 \
> +             --vdev=virtio_user0,path=/dev/vhost-net,queues=2,queue_size=1024 \
> +             -- -i --txqflags=0x0 --disable-hw-vlan --enable-lro \
> +             --enable-rx-cksum --txq=2 --rxq=2 --rxd=1024  --txd=1024

Garbage?

Re: [PATCH v1] doc: change doc line length limit in contributors guide

[Mcnamara, John]

> -----Original Message-----
> From: Thomas Monjalon [mailto:thomas@monjalon.net]
> Sent: Thursday, May 11, 2017 4:23 PM
> To: Mcnamara, John <john.mcnamara@intel.com>
> Cc: dev@dpdk.org
> Subject: Re: [dpdk-dev] [PATCH v1] doc: change doc line length limit in
> contributors guide
> 
> ...
> > -* The recommended style for the DPDK documentation is to put sentences
> on separate lines.
> > -  This allows for easier reviewing of patches.
> > -  Multiple sentences which are not separated by a blank line are joined
> automatically into paragraphs, for example::
> > +* 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.
> 
> Why not keep the recommendation of separating sentences?

This isn't a recommendation. It is just pointing out that lines and sentences
are joined into paragraphs. Maybe that is obvious and doesn't need to be
stated.

> 
> > +     testpmd -l 2-3 -n 4 \
> > +             --vdev=virtio_user0,path=/dev/vhost-
> net,queues=2,queue_size=1024 \
> > +             -- -i --txqflags=0x0 --disable-hw-vlan --enable-lro \
> > +             --enable-rx-cksum --txq=2 --rxq=2 --rxd=1024  --txd=1024
> 
> Garbage?

I hope not. I took it from one of the examples in the docs to demonstrate
how a long command could be wrapped and still be functional. Should I
clarify that more, or remove it?

John

Re: [PATCH v1] doc: change doc line length limit in contributors guide

[Thomas Monjalon]

11/05/2017 18:11, Mcnamara, John:
> From: Thomas Monjalon [mailto:thomas@monjalon.net]
> > 
> > ...
> > > -* The recommended style for the DPDK documentation is to put sentences
> > on separate lines.
> > > -  This allows for easier reviewing of patches.
> > > -  Multiple sentences which are not separated by a blank line are joined
> > automatically into paragraphs, for example::
> > > +* 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.
> > 
> > Why not keep the recommendation of separating sentences?
> 
> This isn't a recommendation. It is just pointing out that lines and sentences
> are joined into paragraphs. Maybe that is obvious and doesn't need to be
> stated.

I'm talking about "The recommended style for the DPDK documentation is
to put sentences on separate lines."
I like this recommendation.

> > > +     testpmd -l 2-3 -n 4 \
> > > +             --vdev=virtio_user0,path=/dev/vhost-
> > net,queues=2,queue_size=1024 \
> > > +             -- -i --txqflags=0x0 --disable-hw-vlan --enable-lro \
> > > +             --enable-rx-cksum --txq=2 --rxq=2 --rxd=1024  --txd=1024
> > 
> > Garbage?
> 
> I hope not. I took it from one of the examples in the docs to demonstrate
> how a long command could be wrapped and still be functional. Should I
> clarify that more, or remove it?

Ah sorry, misreading the patch.

Re: [PATCH v1] doc: change doc line length limit in contributors guide

[Iremonger, Bernard]

> -----Original Message-----
> From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of Thomas Monjalon
> Sent: Thursday, May 11, 2017 6:18 PM
> To: Mcnamara, John <john.mcnamara@intel.com>
> Cc: dev@dpdk.org
> Subject: Re: [dpdk-dev] [PATCH v1] doc: change doc line length limit in
> contributors guide
> 
> 11/05/2017 18:11, Mcnamara, John:
> > From: Thomas Monjalon [mailto:thomas@monjalon.net]
> > >
> > > ...
> > > > -* The recommended style for the DPDK documentation is to put
> > > > sentences
> > > on separate lines.
> > > > -  This allows for easier reviewing of patches.
> > > > -  Multiple sentences which are not separated by a blank line are
> > > > joined
> > > automatically into paragraphs, for example::
> > > > +* 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.
> > >
> > > Why not keep the recommendation of separating sentences?
> >
> > This isn't a recommendation. It is just pointing out that lines and
> > sentences are joined into paragraphs. Maybe that is obvious and
> > doesn't need to be stated.
> 
> I'm talking about "The recommended style for the DPDK documentation is to
> put sentences on separate lines."
> I like this recommendation.

+1 for this recommendation

> 
> > > > +     testpmd -l 2-3 -n 4 \
> > > > +             --vdev=virtio_user0,path=/dev/vhost-
> > > net,queues=2,queue_size=1024 \
> > > > +             -- -i --txqflags=0x0 --disable-hw-vlan --enable-lro \
> > > > +             --enable-rx-cksum --txq=2 --rxq=2 --rxd=1024
> > > > + --txd=1024
> > >
> > > Garbage?
> >
> > I hope not. I took it from one of the examples in the docs to
> > demonstrate how a long command could be wrapped and still be
> > functional. Should I clarify that more, or remove it?
> 
> Ah sorry, misreading the patch.

Regards,

Bernard.

Re: [PATCH v1] doc: change doc line length limit in contributors guide

[Mcnamara, John]

> -----Original Message-----
> From: Iremonger, Bernard
> Sent: Thursday, May 11, 2017 6:31 PM
> To: Thomas Monjalon <thomas@monjalon.net>; Mcnamara, John
> <john.mcnamara@intel.com>
> Cc: dev@dpdk.org
> Subject: RE: [dpdk-dev] [PATCH v1] doc: change doc line length limit in
> contributors guide
> 
> 
> > -----Original Message-----
> > From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of Thomas Monjalon
> > Sent: Thursday, May 11, 2017 6:18 PM
> > To: Mcnamara, John <john.mcnamara@intel.com>
> > Cc: dev@dpdk.org
> > Subject: Re: [dpdk-dev] [PATCH v1] doc: change doc line length limit
> > in contributors guide
> >
> > 11/05/2017 18:11, Mcnamara, John:
> > > From: Thomas Monjalon [mailto:thomas@monjalon.net]
> > > >
> > > > ...
> > > > > -* The recommended style for the DPDK documentation is to put
> > > > > sentences
> > > > on separate lines.
> > > > > -  This allows for easier reviewing of patches.
> > > > > -  Multiple sentences which are not separated by a blank line
> > > > > are joined
> > > > automatically into paragraphs, for example::
> > > > > +* 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.
> > > >
> > > > Why not keep the recommendation of separating sentences?
> > >
> > > This isn't a recommendation. It is just pointing out that lines and
> > > sentences are joined into paragraphs. Maybe that is obvious and
> > > doesn't need to be stated.
> >
> > I'm talking about "The recommended style for the DPDK documentation is
> > to put sentences on separate lines."
> > I like this recommendation.
> 
> +1 for this recommendation
> 

The problem is that almost no-one follows this recommendation.

An 80 character margin is a simple rule that most programming
editors can enforce or handle automatically.

It is also what is recommended in OpenStack:

    https://docs.openstack.org/contributor-guide/rst-conv/general-guidelines.html#lines-length

The kernel doc guidelines don't have a length rule but their docs
are wrapped at 80:

    https://www.kernel.org/doc/html/latest/_sources/doc-guide/sphinx.rst.txt

The current DPDK "single sentence per line plus wrap at ~120 characters"
guideline is unusual, not supported by editors and, with rare exceptions, not
followed by anyone.

As such I think the guidelines should reflect how people actually
write docs and submit patches, which is wrapping at 80 characters.

John

Re: [PATCH v1] doc: change doc line length limit in contributors guide

[Thomas Monjalon]

12/05/2017 11:10, Mcnamara, John:
> From: Iremonger, Bernard
> > From: Thomas Monjalon
> > > 11/05/2017 18:11, Mcnamara, John:
> > > > From: Thomas Monjalon [mailto:thomas@monjalon.net]
> > > > >
> > > > > ...
> > > > > > -* The recommended style for the DPDK documentation is to put
> > > > > > sentences
> > > > > on separate lines.
> > > > > > -  This allows for easier reviewing of patches.
> > > > > > -  Multiple sentences which are not separated by a blank line
> > > > > > are joined
> > > > > automatically into paragraphs, for example::
> > > > > > +* 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.
> > > > >
> > > > > Why not keep the recommendation of separating sentences?
> > > >
> > > > This isn't a recommendation. It is just pointing out that lines and
> > > > sentences are joined into paragraphs. Maybe that is obvious and
> > > > doesn't need to be stated.
> > >
> > > I'm talking about "The recommended style for the DPDK documentation is
> > > to put sentences on separate lines."
> > > I like this recommendation.
> > 
> > +1 for this recommendation
> > 
> 
> The problem is that almost no-one follows this recommendation.
> 
> An 80 character margin is a simple rule that most programming
> editors can enforce or handle automatically.
> 
> It is also what is recommended in OpenStack:
> 
>     https://docs.openstack.org/contributor-guide/rst-conv/general-guidelines.html#lines-length
> 
> The kernel doc guidelines don't have a length rule but their docs
> are wrapped at 80:
> 
>     https://www.kernel.org/doc/html/latest/_sources/doc-guide/sphinx.rst.txt
> 
> The current DPDK "single sentence per line plus wrap at ~120 characters"
> guideline is unusual, not supported by editors and, with rare exceptions, not
> followed by anyone.
> 
> As such I think the guidelines should reflect how people actually
> write docs and submit patches, which is wrapping at 80 characters.

I am OK with 80 characters.
However, I think we should keep trying to explain that it is better
to wrap at the end of a sentence.

Example:
This long sentence with a lot of words which does not mean anything will wrap
at 80 characters and continue on the second line. Then a new sentence starts
and ends on the third line.

It would be better like that:
This long sentence with a lot of words which does not mean anything will wrap
at 80 characters and continue on the second line.
Then a new sentence starts and ends on the third line.

Re: [PATCH v1] doc: change doc line length limit in contributors guide

[Shreyansh Jain]

Sorry for the triviality, once again:

On Thursday 11 May 2017 07:39 PM, John McNamara wrote:
> The DPDK documentation guidelines state that lines should be wrapped as
> follows:
>

[..]

>
> -     Here is an example sentence.
> -     Long sentences over the limit shown below can be wrapped onto
> -     a new line.
> -     These three sentences will be joined into the same paragraph.
> +* Lines in literal blocks **must** by less than 80 characters since
                                     ^^^^^
                 "...blocks **must** be less than ..."

> +  they aren't wrapped by the document formatters and can exceed the page width
> +  in PDF documents.

[...]

 From [1]:
"Quis custodiet ipsos custodes?".

"DPDK custodes" :) (Sorry for my pathetic latin)

[1] http://dpdk.org/ml/archives/dev/2017-May/065655.html

-
Shreyansh

Re: [PATCH v1] doc: change doc line length limit in contributors guide

[Mcnamara, John]

> -----Original Message-----
> From: Thomas Monjalon [mailto:thomas@monjalon.net]
> Sent: Friday, May 12, 2017 10:24 AM
> ,,,
>
> > The current DPDK "single sentence per line plus wrap at ~120 characters"
> > guideline is unusual, not supported by editors and, with rare
> > exceptions, not followed by anyone.
> >
> > As such I think the guidelines should reflect how people actually
> > write docs and submit patches, which is wrapping at 80 characters.
> 
> I am OK with 80 characters.
> However, I think we should keep trying to explain that it is better to
> wrap at the end of a sentence.
> 
> Example:
> This long sentence with a lot of words which does not mean anything will
> wrap at 80 characters and continue on the second line. Then a new sentence
> starts and ends on the third line.
> 
> It would be better like that:
> This long sentence with a lot of words which does not mean anything will
> wrap at 80 characters and continue on the second line.
> Then a new sentence starts and ends on the third line.

This is essentially the same problem as the current guideline: that this
is an artificial way of writing text, it isn't supported by editors,
and is unlikely to be followed in practice.

The first example is the way people write text and the way text is submitted
in patches so the guidelines should reflect this.

John

Re: [PATCH v1] doc: change doc line length limit in contributors guide

[Thomas Monjalon]

16/05/2017 16:20, Mcnamara, John:
> 
> > -----Original Message-----
> > From: Thomas Monjalon [mailto:thomas@monjalon.net]
> > Sent: Friday, May 12, 2017 10:24 AM
> > ,,,
> >
> > > The current DPDK "single sentence per line plus wrap at ~120 characters"
> > > guideline is unusual, not supported by editors and, with rare
> > > exceptions, not followed by anyone.
> > >
> > > As such I think the guidelines should reflect how people actually
> > > write docs and submit patches, which is wrapping at 80 characters.
> > 
> > I am OK with 80 characters.
> > However, I think we should keep trying to explain that it is better to
> > wrap at the end of a sentence.
> > 
> > Example:
> > This long sentence with a lot of words which does not mean anything will
> > wrap at 80 characters and continue on the second line. Then a new sentence
> > starts and ends on the third line.
> > 
> > It would be better like that:
> > This long sentence with a lot of words which does not mean anything will
> > wrap at 80 characters and continue on the second line.
> > Then a new sentence starts and ends on the third line.
> 
> This is essentially the same problem as the current guideline: that this
> is an artificial way of writing text, it isn't supported by editors,
> and is unlikely to be followed in practice.
> 
> The first example is the way people write text and the way text is submitted
> in patches so the guidelines should reflect this.

You are the doc maintainer, it's your call :)

Re: [PATCH v1] doc: change doc line length limit in contributors guide

[Yuanhan Liu]

On Tue, May 16, 2017 at 02:20:58PM +0000, Mcnamara, John wrote:
> 
> 
> > -----Original Message-----
> > From: Thomas Monjalon [mailto:thomas@monjalon.net]
> > Sent: Friday, May 12, 2017 10:24 AM
> > ,,,
> >
> > > The current DPDK "single sentence per line plus wrap at ~120 characters"
> > > guideline is unusual, not supported by editors and, with rare
> > > exceptions, not followed by anyone.
> > >
> > > As such I think the guidelines should reflect how people actually
> > > write docs and submit patches, which is wrapping at 80 characters.
> > 
> > I am OK with 80 characters.
> > However, I think we should keep trying to explain that it is better to
> > wrap at the end of a sentence.
> > 
> > Example:
> > This long sentence with a lot of words which does not mean anything will
> > wrap at 80 characters and continue on the second line. Then a new sentence
> > starts and ends on the third line.
> > 
> > It would be better like that:
> > This long sentence with a lot of words which does not mean anything will
> > wrap at 80 characters and continue on the second line.
> > Then a new sentence starts and ends on the third line.
> 
> This is essentially the same problem as the current guideline: that this
> is an artificial way of writing text, it isn't supported by editors,
> and is unlikely to be followed in practice.
> 
> The first example is the way people write text and the way text is submitted
> in patches so the guidelines should reflect this.

+1 for the first one :)

And,

Reviewed-by: Yuanhan Liu <yuanhan.liu@linux.intel.com>

	--yliu

Re: [PATCH v1] doc: change doc line length limit in contributors guide

[Thomas Monjalon]

22/05/2017 08:44, Yuanhan Liu:
> On Tue, May 16, 2017 at 02:20:58PM +0000, Mcnamara, John wrote:
> > 
> > 
> > > -----Original Message-----
> > > From: Thomas Monjalon [mailto:thomas@monjalon.net]
> > > Sent: Friday, May 12, 2017 10:24 AM
> > > ,,,
> > >
> > > > The current DPDK "single sentence per line plus wrap at ~120 characters"
> > > > guideline is unusual, not supported by editors and, with rare
> > > > exceptions, not followed by anyone.
> > > >
> > > > As such I think the guidelines should reflect how people actually
> > > > write docs and submit patches, which is wrapping at 80 characters.
> > > 
> > > I am OK with 80 characters.
> > > However, I think we should keep trying to explain that it is better to
> > > wrap at the end of a sentence.
> > > 
> > > Example:
> > > This long sentence with a lot of words which does not mean anything will
> > > wrap at 80 characters and continue on the second line. Then a new sentence
> > > starts and ends on the third line.
> > > 
> > > It would be better like that:
> > > This long sentence with a lot of words which does not mean anything will
> > > wrap at 80 characters and continue on the second line.
> > > Then a new sentence starts and ends on the third line.
> > 
> > This is essentially the same problem as the current guideline: that this
> > is an artificial way of writing text, it isn't supported by editors,
> > and is unlikely to be followed in practice.
> > 
> > The first example is the way people write text and the way text is submitted
> > in patches so the guidelines should reflect this.
> 
> +1 for the first one :)
> 
> And,
> 
> Reviewed-by: Yuanhan Liu <yuanhan.liu@linux.intel.com>

I disagree but I have applied it ;)
(with the fix from Shreyansh)