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

[Julien Grall <julien.grall@xxxxxxx>]

Hi Andrew,

On 07/12/2018 15:24, Andrew Cooper wrote:
> 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.
I misread the commit message. It is explained well enough.

Cheers,

--
Julien Grall

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