[PATCH nft] doc: update nft list plural form parameters

[PATCH nft] doc: update nft list plural form parameters

[Fernando Fernandez Mancera]

Signed-off-by: Fernando Fernandez Mancera <ffmancera@riseup.net>
---
 doc/nft.txt | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/doc/nft.txt b/doc/nft.txt
index d162dad..36a92fe 100644
--- a/doc/nft.txt
+++ b/doc/nft.txt
@@ -256,6 +256,7 @@ TABLES
 [verse]
 {add | create} *table* ['family'] 'table' [ {flags 'flags'} ]
 {delete | list | flush} *table* ['family'] 'table'
+list *tables*
 delete *table* ['family'] handle 'handle'
 
 Tables are containers for chains, sets and stateful objects. They are identified
@@ -266,7 +267,8 @@ nfproto* keyword can be used to test which family (ipv4 or ipv6) context the
 packet is being processed in. When no address family is specified, *ip* is used
 by default. The only difference between add and create is that the former will
 not return an error if the specified table already exists while *create* will
-return an error.
+return an error. The plural form of list can be used to list all the existing
+tables.
 
 .Table flags
 [options="header"]
@@ -308,6 +310,7 @@ CHAINS
 [verse]
 {add | create} *chain* ['family'] 'table' 'chain' [ { type 'type' hook 'hook' [device 'device'] priority 'priority' ; [policy 'policy' ;] }]
 {delete | list | flush} *chain* ['family'] 'table' 'chain'
+list *chains*
 delete *chain* ['family'] 'table' handle 'handle'
 rename *chain* ['family'] 'table' 'chain' 'newname'
 
@@ -322,7 +325,7 @@ are specified, the chain is created as a base chain and hooked up to the network
 *create*:: Similar to the *add* command, but returns an error if the chain already exists.
 *delete*:: Delete the specified chain. The chain must not contain any rules or be used as jump target.
 *rename*:: Rename the specified chain.
-*list*:: List all rules of the specified chain.
+*list*:: List all rules of the specified chain. The plural form can be used to list all existing chains.
 *flush*:: Flush all rules of the specified chain.
 
 For base chains, *type*, *hook* and *priority* parameters are mandatory.
@@ -486,6 +489,7 @@ section describes nft set syntax in more detail.
 add *set* ['family'] 'table' 'set' { type 'type' ; [flags 'flags' ;] [timeout 'timeout' ;] [gc-interval 'gc-interval' ;] [elements = { 'element'[,...]
 } ;] [size size ;] [policy policy ;] [auto-merge auto-merge ;] }
 {delete | list | flush} *set* ['family'] 'table' 'set'
+list *sets*
 delete *set* ['family'] 'table' handle 'handle'
 {add | delete} *element* ['family'] 'table' 'set' { 'element'[,...] }
 
@@ -496,7 +500,7 @@ be tuned with the flags that can be specified at set creation time.
 [horizontal]
 *add*:: Add a new set in the specified table. See the Set specification table below for more information about how to specify a sets properties.
 *delete*:: Delete the specified set.
-*list*:: Display the elements in the specified set.
+*list*:: Display the elements in the specified set. The plural form can be used to list all the existing sets.
 *flush*:: Remove all elements from the specified set.
 *add element*:: Comma-separated list of elements to add into the specified set.
 *delete element*:: Comma-separated list of elements to delete from the specified set.
@@ -609,7 +613,8 @@ delete type ['family'] 'table' handle 'handle'
 
 Stateful objects are attached to tables and are identified by an unique name.
 They group stateful information from rules, to reference them in rules the
-keywords "type name" are used e.g. "counter name".
+keywords "type name" are used e.g. "counter name". The plural form can be used
+to list all exisiting stateful objects e.g "list counters".
 
 [horizontal]
 *add*:: Add a new stateful object in the specified table.
-- 
2.20.1

Re: [PATCH nft] doc: update nft list plural form parameters

[Pablo Neira Ayuso]

Cc'ing Duncan, he's been helping with reviewing documentation.

On Thu, Apr 04, 2019 at 01:41:58PM +0200, Fernando Fernandez Mancera wrote:
> Signed-off-by: Fernando Fernandez Mancera <ffmancera@riseup.net>
> ---
>  doc/nft.txt | 13 +++++++++----
>  1 file changed, 9 insertions(+), 4 deletions(-)
> 
> diff --git a/doc/nft.txt b/doc/nft.txt
> index d162dad..36a92fe 100644
> --- a/doc/nft.txt
> +++ b/doc/nft.txt
> @@ -256,6 +256,7 @@ TABLES
>  [verse]
>  {add | create} *table* ['family'] 'table' [ {flags 'flags'} ]
>  {delete | list | flush} *table* ['family'] 'table'
> +list *tables*
>  delete *table* ['family'] handle 'handle'
>  
>  Tables are containers for chains, sets and stateful objects. They are identified
> @@ -266,7 +267,8 @@ nfproto* keyword can be used to test which family (ipv4 or ipv6) context the
>  packet is being processed in. When no address family is specified, *ip* is used
>  by default. The only difference between add and create is that the former will
>  not return an error if the specified table already exists while *create* will
> -return an error.
> +return an error. The plural form of list can be used to list all the existing
> +tables.

Not sure we need this sentence, I mean, not sure if reader will
correlate this with 'list tables'.

Probably just adding:

list *tables*

and so on, for other objects in the [verse] area is just enough.

Thanks!

Re: [PATCH nft] doc: update nft list plural form parameters

[Fernando Fernandez Mancera]

Hi,

On 4/4/19 2:01 PM, Pablo Neira Ayuso wrote:
> Cc'ing Duncan, he's been helping with reviewing documentation.
> 
> On Thu, Apr 04, 2019 at 01:41:58PM +0200, Fernando Fernandez Mancera wrote:
>> Signed-off-by: Fernando Fernandez Mancera <ffmancera@riseup.net>
>> ---
>>  doc/nft.txt | 13 +++++++++----
>>  1 file changed, 9 insertions(+), 4 deletions(-)
>>
>> diff --git a/doc/nft.txt b/doc/nft.txt
>> index d162dad..36a92fe 100644
>> --- a/doc/nft.txt
>> +++ b/doc/nft.txt
>> @@ -256,6 +256,7 @@ TABLES
>>  [verse]
>>  {add | create} *table* ['family'] 'table' [ {flags 'flags'} ]
>>  {delete | list | flush} *table* ['family'] 'table'
>> +list *tables*
>>  delete *table* ['family'] handle 'handle'
>>  
>>  Tables are containers for chains, sets and stateful objects. They are identified
>> @@ -266,7 +267,8 @@ nfproto* keyword can be used to test which family (ipv4 or ipv6) context the
>>  packet is being processed in. When no address family is specified, *ip* is used
>>  by default. The only difference between add and create is that the former will
>>  not return an error if the specified table already exists while *create* will
>> -return an error.
>> +return an error. The plural form of list can be used to list all the existing
>> +tables.
> 
> Not sure we need this sentence, I mean, not sure if reader will
> correlate this with 'list tables'.
> 
> Probably just adding:
> 
> list *tables*
> 
> and so on, for other objects in the [verse] area is just enough.
> 

But do you think we need to keep the stateful objects one? If not, how
should we state that a plural form can be used with stateful objects?
Thanks!

>> @@ -609,7 +613,8 @@  delete type ['family'] 'table' handle 'handle'
>>  
>>  Stateful objects are attached to tables and are identified by an unique name.
>>  They group stateful information from rules, to reference them in rules the
>> -keywords "type name" are used e.g. "counter name".
>> +keywords "type name" are used e.g. "counter name". The plural form can be used
>> +to list all exisiting stateful objects e.g "list counters".
>>  
>>  [horizontal]
>>  *add*:: Add a new stateful object in the specified table.
> Thanks!
> 

Re: [PATCH nft] doc: update nft list plural form parameters

[Pablo Neira Ayuso]

On Thu, Apr 04, 2019 at 02:08:42PM +0200, Fernando Fernandez Mancera wrote:
> On 4/4/19 2:01 PM, Pablo Neira Ayuso wrote:
> > Not sure we need this sentence, I mean, not sure if reader will
> > correlate this with 'list tables'.
> > 
> > Probably just adding:
> > 
> > list *tables*
> > 
> > and so on, for other objects in the [verse] area is just enough.
> > 
> 
> But do you think we need to keep the stateful objects one? If not, how
> should we state that a plural form can be used with stateful objects?

You can probably show the explicitly

list counters
list quotas

etc.

Re: [PATCH nft] doc: update nft list plural form parameters

[Duncan Roe]

On Thu, Apr 04, 2019 at 02:01:23PM +0200, Pablo Neira Ayuso wrote:
> Cc'ing Duncan, he's been helping with reviewing documentation.
>
> On Thu, Apr 04, 2019 at 01:41:58PM +0200, Fernando Fernandez Mancera wrote:
> > Signed-off-by: Fernando Fernandez Mancera <ffmancera@riseup.net>
> > ---
> >  doc/nft.txt | 13 +++++++++----
> >  1 file changed, 9 insertions(+), 4 deletions(-)
> >
> > diff --git a/doc/nft.txt b/doc/nft.txt
> > index d162dad..36a92fe 100644
> > --- a/doc/nft.txt
> > +++ b/doc/nft.txt
> > @@ -256,6 +256,7 @@ TABLES
> >  [verse]
> >  {add | create} *table* ['family'] 'table' [ {flags 'flags'} ]
> >  {delete | list | flush} *table* ['family'] 'table'
> > +list *tables*
> >  delete *table* ['family'] handle 'handle'
> >
> >  Tables are containers for chains, sets and stateful objects. They are identified
> > @@ -266,7 +267,8 @@ nfproto* keyword can be used to test which family (ipv4 or ipv6) context the
> >  packet is being processed in. When no address family is specified, *ip* is used
> >  by default. The only difference between add and create is that the former will
> >  not return an error if the specified table already exists while *create* will
> > -return an error.
> > +return an error. The plural form of list can be used to list all the existing
> > +tables.
>
> Not sure we need this sentence, I mean, not sure if reader will
> correlate this with 'list tables'.
>
> Probably just adding:
>
> list *tables*
>
> and so on, for other objects in the [verse] area is just enough.
>
> Thanks!

Hi Pablo,

I had no trouble understanding the sentence, but wouldn't it be clearer to
change it to simply

*list tables* lists all the existing tables.

Sorry for late reply - a bit behind with my emails.

Cheers ... Duncan.

Re: [PATCH nft] doc: update nft list plural form parameters

[Pablo Neira Ayuso]

On Mon, Apr 08, 2019 at 11:21:54AM +1000, Duncan Roe wrote:
> On Thu, Apr 04, 2019 at 02:01:23PM +0200, Pablo Neira Ayuso wrote:
> > Cc'ing Duncan, he's been helping with reviewing documentation.
> >
> > On Thu, Apr 04, 2019 at 01:41:58PM +0200, Fernando Fernandez Mancera wrote:
> > > Signed-off-by: Fernando Fernandez Mancera <ffmancera@riseup.net>
> > > ---
> > >  doc/nft.txt | 13 +++++++++----
> > >  1 file changed, 9 insertions(+), 4 deletions(-)
> > >
> > > diff --git a/doc/nft.txt b/doc/nft.txt
> > > index d162dad..36a92fe 100644
> > > --- a/doc/nft.txt
> > > +++ b/doc/nft.txt
> > > @@ -256,6 +256,7 @@ TABLES
> > >  [verse]
> > >  {add | create} *table* ['family'] 'table' [ {flags 'flags'} ]
> > >  {delete | list | flush} *table* ['family'] 'table'
> > > +list *tables*
> > >  delete *table* ['family'] handle 'handle'
> > >
> > >  Tables are containers for chains, sets and stateful objects. They are identified
> > > @@ -266,7 +267,8 @@ nfproto* keyword can be used to test which family (ipv4 or ipv6) context the
> > >  packet is being processed in. When no address family is specified, *ip* is used
> > >  by default. The only difference between add and create is that the former will
> > >  not return an error if the specified table already exists while *create* will
> > > -return an error.
> > > +return an error. The plural form of list can be used to list all the existing
> > > +tables.
> >
> > Not sure we need this sentence, I mean, not sure if reader will
> > correlate this with 'list tables'.
> >
> > Probably just adding:
> >
> > list *tables*
> >
> > and so on, for other objects in the [verse] area is just enough.
> >
> > Thanks!
> 
> Hi Pablo,
> 
> I had no trouble understanding the sentence, but wouldn't it be clearer to
> change it to simply
> 
> *list tables* lists all the existing tables.

Thanks, this is what Fernando has done in v2, all good :-)