Re: [Xen-devel] [PATCH] docs/xl: Clarify documentation for mem-max and mem-set

[Lars Kurth <lars.kurth@xxxxxxxxxx>]

On 02/08/2018, 11:24, "George Dunlap" <george.dunlap@xxxxxxxxxx> wrote:

    On 08/01/2018 05:16 PM, Lars Kurth wrote:
    > 
    > 
    > On 01/08/2018, 16:41, "George Dunlap" <george.dunlap@xxxxxxxxxx> wrote:
    > 
    >     mem-set is the primary command that users will need to use and
    >     understand.  Move it first, and clarify the wording; also specify that
    >     you can't set the target higher than maxmem from the domain config.
    >     
    >     mem-max is actually a pretty useless command at the moment.  Clarify
    >     that users are not expected to use it; and document all of its quirky
    >     behavior.
    >     
    >     Signed-off-by: George Dunlap <george.dunlap@xxxxxxxxxx>
    >     ---
    >     I'm actully somewhat tempted to take out the entry for mem-max
    >     entirely -- it's not at all clear to me what anyone would use it for,
    >     and it's only likely to confuse people.
    > 
    > Should it be deprecated, if it isn't useful?
    >     
    >     CC: Ian Jackson <ian.jackson@xxxxxxxxxx>
    >     CC: Wei Liu <wei.liu2@xxxxxxxxxx>
    >     CC: Andrew Cooper <andrew.cooper3@xxxxxxxxxx>
    >     CC: Jan Beulich <jbeulich@xxxxxxxx>
    >     CC: Tim Deegan <tim@xxxxxxx>
    >     CC: Konrad Wilk <konrad.wilk@xxxxxxxxxx>
    >     CC: Stefano Stabellini <sstabellini@xxxxxxxxxx>
    >     CC: Julien Grall <julien.grall@xxxxxxx>
    >     CC: Lars Kurth <lars.kurth@xxxxxxxxxx>
    >     ---
    >      docs/man/xl.pod.1.in | 72 
++++++++++++++++++++++++++++++--------------
    >      1 file changed, 50 insertions(+), 22 deletions(-)
    >     
    >     diff --git a/docs/man/xl.pod.1.in b/docs/man/xl.pod.1.in
    >     index b74764dcd3..1d3dabf185 100644
    >     --- a/docs/man/xl.pod.1.in
    >     +++ b/docs/man/xl.pod.1.in
    >     @@ -393,40 +393,68 @@ less utilized than a high CPU workload.  
Consider yourself warned.
    >      
    >      =back
    >      
    >     -=item B<mem-max> I<domain-id> I<mem>
    >     +=item B<mem-set> I<domain-id> I<mem>
    >      
    >     -Specify the maximum amount of memory the domain is able to use, 
appending 't'
    >     -for terabytes, 'g' for gigabytes, 'm' for megabytes, 'k' for 
kilobytes and 'b'
    >     -for bytes.
    >     +Set the target for the domain's balloon driver.  Append 't' for
    > 
    > I would say Use instead of Append: if you are not a native speaker you 
could
    > be misled that the command appends memory.
    
    I'm afraid 'use' doesn't tell me what to do -- `set-max A t`? `set-max A
    2048 t`?  `set-max A t2048`?
    
    What about making a paragraph break and changing it to:
    
    "The default unit is kiB.  Add 't' to specify TiB, 'g' for GiB, 'm' for
    MiB, and 'b' for bytes (e.g., 2048m)."
    
    Alternate we could say `I<mem>[<unit>]`, but that seems to be getting a
    little clunky.

I will leave that up to you. It's just something I noticed but not a big deal. 

Lars 

_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxxxxxxxxx
https://lists.xenproject.org/mailman/listinfo/xen-devel