Bug 698521

Description of problem:
According to BZ 693963 Comment 14, virsh freecell command help page and man page should be more clear.

Version-Release number of selected component (if applicable):
libvirt-0.8.7-18.el6.x86_64

How reproducible:
Always

Steps to Reproduce:

From BZ 693963 Comment 14,

(In reply to comment #13)
> Test in below environment:
> libvirt-0.8.7-18.el6.x86_64
> 
> # man virsh
> ...
>  freecell optional { --cellno cellno | --all }
>      Prints the available amount of memory on the machine or within a
>      NUMA cell if cellno is provided.  If --all is provided instead of
>      --cellno, then show the information on all NUMA cells.

I'm not sure how to make the man page any clearer, other than maybe:

freecell [{ [--cellno] cellno | --all }]

That is, there are three commands, the last with three spellings:

freecell            => total
freecell --all      => breakdown of all NUMA nodes
freecell --cellno 0 => single NUMA node
freecell 0          => single NUMA node
freecell --cellno=0 => single NUMA node

> 
>   OPTIONS
>     --cellno <number>  NUMA cell number

Hmm, this line in 'virsh help freecell' could be improved to show [--cellno]
rather than --cellno.

> 
> # virsh freecell --cellno
> error: expected syntax: --cellno <number>

Correct behavior.  --cellno requires an argument to go with the option.

> 
> # virsh freecell  foo000
> error: cell number has to be a number

Correct behavior.  Without either --cellno or --all, the first operand is
mapped to the first argument that takes an option, so this is equivalent to
freecell --cellno foo000, and foo000 is not a number.

> 
> According to above test and bug description, I notice ’man virsh‘ make a
> distinction between I<--cellno> and B<cellno>，But I wonder the cellno should be
> B<cellno> in the setentence 'if cellno is provided'. 

Possibly, but at this point, it's just documentation wording, and we're awfully
late.  We've already done what we hope to be the final spin for snap5; can we
instead spawn a new bug targetted for 6.2 that recommends further improvements
for virsh help (properly documenting that --cellno is optional) and man virsh
(tweaking the sentence), now that the real bug for 6.1 (the regression in
'freecell 0') has been fixed?
  
Actual results:
As above

Expected results:

According to BZ 693963,

1. # virsh help freecell 
...
--cellno <number>  NUMA cell number

> this line in 'virsh help freecell' could be improved to show [--cellno]
rather than --cellno.

2. # man virsh
...
1) freecell optional { --cellno cellno | --all }
> this line should make sure --cellno is optional for cellno

2) ’man virsh‘ make a distinction between I<--cellno> and B<cellno>，But I wonder the cellno should be B<cellno> in the setentence 'if cellno is provided'. 

Additional info: