Re: [Xen-devel] [PATCH 3/3] docs/cmdline: Rewrite the cpuid_mask_* section

[Andrew Cooper <andrew.cooper3@xxxxxxxxxx>]

On 07/12/2018 15:09, Julien Grall wrote:
> Hi Andrew,
>
> On 07/12/2018 13:45, Andrew Cooper wrote:
>> A large amount of the information here is obsolete since Xen 4.7
>>
>> To being with, however, this patch marks a change in style for section
>> headings, due to how HTML anchors are generated.  Having more than one
>> parameter per heading makes an awkward anchor, especially when brace
>> globbing
>> is used.  Furthermore, the misc suffixes such as (AMD only) get
>> included, as
>> do the escaping for the underscores.
>>
>> Markdown doesn't require escaped underscores in headings (I'm not
>> entirely
>> sure how we ended up with that style), so remove them and fully
>> expand the
>> glob syntax.  Also adjust com1,com2 while at it, which is the only other
>> multi-parameter heading.  Move the misc suffixes into an
>> "Applicability:" note
>> alongside the information about defaults.
>>
>> This results in the headings being unadorned, and identical to how
>> they are
>> expressed on the command line and in code.
>>
>> For cpuid_mask_cpu option, collapse the long line of almost identical
>> strings
>> using [] globbing.  The result is much shorter and clearer to read. 
>> Add a
>> warning that this option no longer masks all features on Fam15h and
>> above, due
>> to not making use of the leaf 7 masks.
>>
>> For the remainder of the cpuid_mask_* options, collapse them all
>> together into
>> a single description.
>>
>> Finally, leave an explicit note explaining that people should not be
>> using
>> these options for migration safety.
>>
>> Signed-off-by: Andrew Cooper <andrew.cooper3@xxxxxxxxxx>
>> ---
>> CC: George Dunlap <George.Dunlap@xxxxxxxxxxxxx>
>> CC: Ian Jackson <ian.jackson@xxxxxxxxxx>
>> CC: Jan Beulich <JBeulich@xxxxxxxx>
>> CC: Konrad Rzeszutek Wilk <konrad.wilk@xxxxxxxxxx>
>> CC: Stefano Stabellini <sstabellini@xxxxxxxxxx>
>> CC: Tim Deegan <tim@xxxxxxx>
>> CC: Wei Liu <wei.liu2@xxxxxxxxxx>
>> CC: Julien Grall <julien.grall@xxxxxxx>
>> ---
>>   docs/misc/xen-command-line.markdown | 60
>> +++++++++++++++++++------------------
>>   1 file changed, 31 insertions(+), 29 deletions(-)
>>
>> diff --git a/docs/misc/xen-command-line.markdown
>> b/docs/misc/xen-command-line.markdown
>> index 175d462..29fec20 100644
>> --- a/docs/misc/xen-command-line.markdown
>> +++ b/docs/misc/xen-command-line.markdown
>> @@ -277,7 +277,8 @@ Interrupts.  Specifying zero disables CMCI handling.
>>   Flag to indicate whether to probe for a CMOS Real Time Clock
>> irrespective of
>>   ACPI indicating none to be there.
>>   -### com1,com2
>> +### com1
>> +### com2
>
> Should not this belong to patch #1?

No.  This change isn't for markdown syntax issues.

It is for a change in how we express headings, and more logically fits
in this patch, as explained (hopefully well enough) in the commit message.

~Andrew

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