[dpdk-dev,1/1] doc: correct Vhost Sample Application guide

  correct sample console commands

Fixes: d0dff9ba445e ("doc: sample application user guide"
Fixes: 9bc23cb8209c ("doc: add vhost-user to sample guide")
Fixes: 43866bf71d58 ("doc: fix vhost sample parameter")
Signed-off-by: Bernard Iremonger <bernard.iremonger@intel.com>
---
 doc/guides/sample_app_ug/vhost.rst | 40 +++++++++++++++++++-------------------
 1 file changed, 20 insertions(+), 20 deletions(-)
  

On 12/9/2015 8:36 PM, Iremonger, Bernard wrote:
> correct sample console commands
>
> Fixes: d0dff9ba445e ("doc: sample application user guide"
> Fixes: 9bc23cb8209c ("doc: add vhost-user to sample guide")
> Fixes: 43866bf71d58 ("doc: fix vhost sample parameter")
> Signed-off-by: Bernard Iremonger <bernard.iremonger@intel.com>
Acked-by: Huawei Xie <huawei.xie@intel.com>

Thanks.
[...]
  

> -----Original Message-----
> From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of Bernard Iremonger
> Sent: Wednesday, December 9, 2015 12:36 PM
> To: dev@dpdk.org
> Subject: [dpdk-dev] [PATCH 1/1] doc: correct Vhost Sample Application
> guide
> 
> correct sample console commands
> 
> Fixes: d0dff9ba445e ("doc: sample application user guide"
> Fixes: 9bc23cb8209c ("doc: add vhost-user to sample guide")
> Fixes: 43866bf71d58 ("doc: fix vhost sample parameter")
> Signed-off-by: Bernard Iremonger <bernard.iremonger@intel.com>

Hi Bernard,

Thanks for that. One comment (in several places):


>      .. code-block:: console
> 
> -        user@target:~$ ./build/app/vhost-switch -c f -n 4 --huge-dir /mnt/huge -- -p 0x1 --dev-basename usvhost
> +        user@target:~$ ./build/app/vhost-switch -c f -n 4 --socket-mem 1024 --huge-dir /mnt/huge -- -p 0x1 --dev-basename usvhost

These long lines in code blocks don't render correctly in the PDF docs. The 
Documentation Guidelines suggest using a commandline line continuation
to maintain functionality within an 80 char doc limit:

   http://dpdk.org/doc/guides/contributing/documentation.html#code-and-literal-block-sections

So something like this:

    user@target:~$ ./build/app/vhost-switch -c f -n 4 --socket-mem 1024 --huge-dir /mnt/huge -- -p 0x1 --dev-basename usvhost

Could be written as:

    user@target:~$ ./build/app/vhost-switch -c f -n 4 --socket-mem 1024 \
                         --huge-dir /mnt/huge -- -p 0x1 --dev-basename usvhost

Or: 

    user@target:~$ ./build/app/vhost-switch -c f -n 4 \
                                            --socket-mem 1024 \
                                            --huge-dir /mnt/huge \
                                            -- -p 0x1 --dev-basename usvhost

Regards,

John.
--
  

> -----Original Message-----
> From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of Bernard Iremonger
> Sent: Wednesday, December 9, 2015 12:36 PM
> To: dev@dpdk.org
> Subject: [dpdk-dev] [PATCH 1/1] doc: correct Vhost Sample Application
> guide
> 
> correct sample console commands
> 
> Fixes: d0dff9ba445e ("doc: sample application user guide"
> Fixes: 9bc23cb8209c ("doc: add vhost-user to sample guide")
> Fixes: 43866bf71d58 ("doc: fix vhost sample parameter")
> Signed-off-by: Bernard Iremonger <bernard.iremonger@intel.com>
> ---
>  doc/guides/sample_app_ug/vhost.rst | 40 +++++++++++++++++++--------------
>
> ...
> 
>      Redistribution and use in source and binary forms, with or without @@
> -386,13 +386,13 @@ Running the Sample Code
> 
>      .. code-block:: console
> 
> -        user@target:~$ ./build/app/vhost-switch -c f -n 4 --huge-dir /


Also, as a general note, not just to this document/patch.

I don't think the "user@target:~$" prefixes used in some DPDK
Doc commandlines is useful.

It prevents a straight copy and paste for testing, it makes the
literal block lines longer than they should be, it isn't used
consistently everywhere, it is visually distracting (in some
cases it is longer than the command being shown), and it isn't
always correct (I presume in the above case of "user@target" you
would need run the application as sudo if you are a non root
user).

Any objections to removing these as documents are updated?


John
  

2015-12-09 14:50, Mcnamara, John:
> Also, as a general note, not just to this document/patch.
> 
> I don't think the "user@target:~$" prefixes used in some DPDK
> Doc commandlines is useful.
> 
> It prevents a straight copy and paste for testing, it makes the
> literal block lines longer than they should be, it isn't used
> consistently everywhere, it is visually distracting (in some
> cases it is longer than the command being shown), and it isn't
> always correct (I presume in the above case of "user@target" you
> would need run the application as sudo if you are a non root
> user).
> 
> Any objections to removing these as documents are updated?

Generally speaking, +1 to remove extra bytes :)
  

Hi John,

<snip>

> Hi Bernard,
> 
> Thanks for that. One comment (in several places):
> 
> 
> >      .. code-block:: console
> >
> > -        user@target:~$ ./build/app/vhost-switch -c f -n 4 --huge-dir
> /mnt/huge -- -p 0x1 --dev-basename usvhost
> > +        user@target:~$ ./build/app/vhost-switch -c f -n 4
> > + --socket-mem 1024 --huge-dir /mnt/huge -- -p 0x1 --dev-basename
> > + usvhost
> 
> These long lines in code blocks don't render correctly in the PDF docs. The
> Documentation Guidelines suggest using a commandline line continuation to
> maintain functionality within an 80 char doc limit:
> 
>    http://dpdk.org/doc/guides/contributing/documentation.html#code-and-
> literal-block-sections
> 
> So something like this:
> 
>     user@target:~$ ./build/app/vhost-switch -c f -n 4 --socket-mem 1024 --
> huge-dir /mnt/huge -- -p 0x1 --dev-basename usvhost
> 
> Could be written as:
> 
>     user@target:~$ ./build/app/vhost-switch -c f -n 4 --socket-mem 1024 \
>                          --huge-dir /mnt/huge -- -p 0x1 --dev-basename usvhost
> 
> Or:
> 
>     user@target:~$ ./build/app/vhost-switch -c f -n 4 \
>                                             --socket-mem 1024 \
>                                             --huge-dir /mnt/huge \
>                                             -- -p 0x1 --dev-basename usvhost
> 
> Regards,
> 
> John.
> --

I will use a command line continuation character to stay within 80 character limit.

Regards,

Bernard.
  

Hi John,
<snip>

> 2015-12-09 14:50, Mcnamara, John:
> > Also, as a general note, not just to this document/patch.
> >
> > I don't think the "user@target:~$" prefixes used in some DPDK Doc
> > commandlines is useful.
> >
> > It prevents a straight copy and paste for testing, it makes the
> > literal block lines longer than they should be, it isn't used
> > consistently everywhere, it is visually distracting (in some cases it
> > is longer than the command being shown), and it isn't always correct
> > (I presume in the above case of "user@target" you would need run the
> > application as sudo if you are a non root user).
> >
> > Any objections to removing these as documents are updated?
> 
> Generally speaking, +1 to remove extra bytes :)

I will remove the "user@target:~$"  prefixes in this document.

Regards,

Bernard.
  

On Wed, Dec 09, 2015 at 04:14:01PM +0000, Iremonger, Bernard wrote:
> Hi John,
> <snip>
> 
> > 2015-12-09 14:50, Mcnamara, John:
> > > Also, as a general note, not just to this document/patch.
> > >
> > > I don't think the "user@target:~$" prefixes used in some DPDK Doc
> > > commandlines is useful.
> > >
> > > It prevents a straight copy and paste for testing, it makes the
> > > literal block lines longer than they should be, it isn't used
> > > consistently everywhere, it is visually distracting (in some cases it
> > > is longer than the command being shown), and it isn't always correct
> > > (I presume in the above case of "user@target" you would need run the
> > > application as sudo if you are a non root user).
> > >
> > > Any objections to removing these as documents are updated?
> > 
> > Generally speaking, +1 to remove extra bytes :)
> 
> I will remove the "user@target:~$"  prefixes in this document.

I'd personally suggest to keep the "$ " prefix, or "# " if it needs
root privilege. Which is a convention to paste commands.

	--yliu