Re: [Xen-devel] [PATCH 3/3] docs/cmdline: Rewrite the cpuid_mask_* section
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 --- CC: George Dunlap CC: Ian Jackson CC: Jan Beulich CC: Konrad Rzeszutek Wilk CC: Stefano Stabellini CC: Tim Deegan CC: Wei Liu CC: Julien Grall --- 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@lists.xenproject.org https://lists.xenproject.org/mailman/listinfo/xen-devel
Re: [Xen-devel] [PATCH 3/3] docs/cmdline: Rewrite the cpuid_mask_* section
>>> On 07.12.18 at 14:45, 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 Contents (but not formatting, due to my lack of markdown speak) Acked-by: Jan Beulich Jan ___ Xen-devel mailing list Xen-devel@lists.xenproject.org https://lists.xenproject.org/mailman/listinfo/xen-devel
Re: [Xen-devel] [PATCH 3/3] docs/cmdline: Rewrite the cpuid_mask_* section
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 >> --- >> CC: George Dunlap >> CC: Ian Jackson >> CC: Jan Beulich >> CC: Konrad Rzeszutek Wilk >> CC: Stefano Stabellini >> CC: Tim Deegan >> CC: Wei Liu >> CC: Julien Grall >> --- >> 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@lists.xenproject.org https://lists.xenproject.org/mailman/listinfo/xen-devel
Re: [Xen-devel] [PATCH 3/3] docs/cmdline: Rewrite the cpuid_mask_* section
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 --- CC: George Dunlap CC: Ian Jackson CC: Jan Beulich CC: Konrad Rzeszutek Wilk CC: Stefano Stabellini CC: Tim Deegan CC: Wei Liu CC: Julien Grall --- 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? Cheers, -- Julien Grall ___ Xen-devel mailing list Xen-devel@lists.xenproject.org https://lists.xenproject.org/mailman/listinfo/xen-devel
