xen-commandline document

xen-commandline document

[Juergen Gross]

Recently there have been several requests to add disclaimers
like "only applicable if CONFIG_xyz defined" to
docs/misc/xen-command-line.pandoc.

As that file will be used as source for the installed file
/usr/share/doc/xen/html/misc/xen-command-line.html there might be
a better alternative instead of adding such disclaimers: what if
we put such options in #ifdef CONFIG_xyz sections and let CPP
create a file with only those options documented which are
applicable to the installed hypervisor?

The source file used would be still available for the developer
(who should understand the #ifdefs) while on a Xen host only the
available options would be documented. For locations like

http://xenbits.xen.org/docs/unstable/misc/xen-command-line.html

we could use an "allyesconfig" for each architecture as config
source.

Thoughts?


Juergen

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

Re: xen-commandline document

[Andrew Cooper]

On 15/01/2019 09:23, Juergen Gross wrote:
> Recently there have been several requests to add disclaimers
> like "only applicable if CONFIG_xyz defined" to
> docs/misc/xen-command-line.pandoc.
>
> As that file will be used as source for the installed file
> /usr/share/doc/xen/html/misc/xen-command-line.html there might be
> a better alternative instead of adding such disclaimers: what if
> we put such options in #ifdef CONFIG_xyz sections and let CPP
> create a file with only those options documented which are
> applicable to the installed hypervisor?
>
> The source file used would be still available for the developer
> (who should understand the #ifdefs) while on a Xen host only the
> available options would be documented. For locations like
>
> http://xenbits.xen.org/docs/unstable/misc/xen-command-line.html
>
> we could use an "allyesconfig" for each architecture as config
> source.
>
> Thoughts?

allyesconfig doesn't work with mutually incompatible options, where one
of them will definitely be n

Overall, I'm fairly -1 to this idea.  I don't like the idea of merging
the xen/ and docs/ builds to be able to make this happen, and while it
may be fairly simple and easy in the ARGO case, it is most definitely
not in the XSM case.

There is a specific reason why documentation isn't written in C, and IMO
it should be kept that way.

~Andrew

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

Re: xen-commandline document

[Andrew Cooper]

On 15/01/2019 09:38, Andrew Cooper wrote:
> On 15/01/2019 09:23, Juergen Gross wrote:
>> Recently there have been several requests to add disclaimers
>> like "only applicable if CONFIG_xyz defined" to
>> docs/misc/xen-command-line.pandoc.
>>
>> As that file will be used as source for the installed file
>> /usr/share/doc/xen/html/misc/xen-command-line.html there might be
>> a better alternative instead of adding such disclaimers: what if
>> we put such options in #ifdef CONFIG_xyz sections and let CPP
>> create a file with only those options documented which are
>> applicable to the installed hypervisor?
>>
>> The source file used would be still available for the developer
>> (who should understand the #ifdefs) while on a Xen host only the
>> available options would be documented. For locations like
>>
>> http://xenbits.xen.org/docs/unstable/misc/xen-command-line.html
>>
>> we could use an "allyesconfig" for each architecture as config
>> source.
>>
>> Thoughts?
> allyesconfig doesn't work with mutually incompatible options, where one
> of them will definitely be n
>
> Overall, I'm fairly -1 to this idea.  I don't like the idea of merging
> the xen/ and docs/ builds to be able to make this happen, and while it
> may be fairly simple and easy in the ARGO case, it is most definitely
> not in the XSM case.
>
> There is a specific reason why documentation isn't written in C, and IMO
> it should be kept that way.

Furthermore, in XenServer at least, we ship two hypervisors (a release
and a debug one).  These have different options available, due to
CONFIG_DEBUG.

~Andrew

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

Re: xen-commandline document

[Juergen Gross]

On 15/01/2019 10:38, Andrew Cooper wrote:
> On 15/01/2019 09:23, Juergen Gross wrote:
>> Recently there have been several requests to add disclaimers
>> like "only applicable if CONFIG_xyz defined" to
>> docs/misc/xen-command-line.pandoc.
>>
>> As that file will be used as source for the installed file
>> /usr/share/doc/xen/html/misc/xen-command-line.html there might be
>> a better alternative instead of adding such disclaimers: what if
>> we put such options in #ifdef CONFIG_xyz sections and let CPP
>> create a file with only those options documented which are
>> applicable to the installed hypervisor?
>>
>> The source file used would be still available for the developer
>> (who should understand the #ifdefs) while on a Xen host only the
>> available options would be documented. For locations like
>>
>> http://xenbits.xen.org/docs/unstable/misc/xen-command-line.html
>>
>> we could use an "allyesconfig" for each architecture as config
>> source.
>>
>> Thoughts?
> 
> allyesconfig doesn't work with mutually incompatible options, where one
> of them will definitely be n
> 
> Overall, I'm fairly -1 to this idea.  I don't like the idea of merging
> the xen/ and docs/ builds to be able to make this happen, and while it
> may be fairly simple and easy in the ARGO case, it is most definitely
> not in the XSM case.
> 
> There is a specific reason why documentation isn't written in C, and IMO
> it should be kept that way.

Fair enough. :-)

So plan B:

Give the user an interface to obtain the .config used to create the
currently running hypervisor (I guess this was discussed at least once
before). I'd suggest an option for "xl info", but I'm open for other
interfaces.

Then add potential config restrictions to the command line parameter doc
(like already done for x86/arm) with a preamble telling the reader how
to read those restrictions.


Juergen

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

Re: xen-commandline document

[Jan Beulich]

>>> On 15.01.19 at 10:38, <andrew.cooper3@citrix.com> wrote:
> On 15/01/2019 09:23, Juergen Gross wrote:
>> Recently there have been several requests to add disclaimers
>> like "only applicable if CONFIG_xyz defined" to
>> docs/misc/xen-command-line.pandoc.
>>
>> As that file will be used as source for the installed file
>> /usr/share/doc/xen/html/misc/xen-command-line.html there might be
>> a better alternative instead of adding such disclaimers: what if
>> we put such options in #ifdef CONFIG_xyz sections and let CPP
>> create a file with only those options documented which are
>> applicable to the installed hypervisor?
>>
>> The source file used would be still available for the developer
>> (who should understand the #ifdefs) while on a Xen host only the
>> available options would be documented. For locations like
>>
>> http://xenbits.xen.org/docs/unstable/misc/xen-command-line.html 
>>
>> we could use an "allyesconfig" for each architecture as config
>> source.
>>
>> Thoughts?
> 
> allyesconfig doesn't work with mutually incompatible options, where one
> of them will definitely be n
> 
> Overall, I'm fairly -1 to this idea.  I don't like the idea of merging
> the xen/ and docs/ builds to be able to make this happen, and while it
> may be fairly simple and easy in the ARGO case, it is most definitely
> not in the XSM case.
> 
> There is a specific reason why documentation isn't written in C, and IMO
> it should be kept that way.

Which then, by extension, also makes it preferable for it to not
talk about C identifiers (here: manifest constants). See my other
reply in particular regarding the mentioning of the CONFIG_
prefixes.

Jan



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

Re: xen-commandline document

[Andrew Cooper]

On 15/01/2019 09:59, Juergen Gross wrote:
> On 15/01/2019 10:38, Andrew Cooper wrote:
>> On 15/01/2019 09:23, Juergen Gross wrote:
>>> Recently there have been several requests to add disclaimers
>>> like "only applicable if CONFIG_xyz defined" to
>>> docs/misc/xen-command-line.pandoc.
>>>
>>> As that file will be used as source for the installed file
>>> /usr/share/doc/xen/html/misc/xen-command-line.html there might be
>>> a better alternative instead of adding such disclaimers: what if
>>> we put such options in #ifdef CONFIG_xyz sections and let CPP
>>> create a file with only those options documented which are
>>> applicable to the installed hypervisor?
>>>
>>> The source file used would be still available for the developer
>>> (who should understand the #ifdefs) while on a Xen host only the
>>> available options would be documented. For locations like
>>>
>>> http://xenbits.xen.org/docs/unstable/misc/xen-command-line.html
>>>
>>> we could use an "allyesconfig" for each architecture as config
>>> source.
>>>
>>> Thoughts?
>> allyesconfig doesn't work with mutually incompatible options, where one
>> of them will definitely be n
>>
>> Overall, I'm fairly -1 to this idea.  I don't like the idea of merging
>> the xen/ and docs/ builds to be able to make this happen, and while it
>> may be fairly simple and easy in the ARGO case, it is most definitely
>> not in the XSM case.
>>
>> There is a specific reason why documentation isn't written in C, and IMO
>> it should be kept that way.
> Fair enough. :-)
>
> So plan B:
>
> Give the user an interface to obtain the .config used to create the
> currently running hypervisor (I guess this was discussed at least once
> before). I'd suggest an option for "xl info", but I'm open for other
> interfaces.
>
> Then add potential config restrictions to the command line parameter doc
> (like already done for x86/arm) with a preamble telling the reader how
> to read those restrictions.

Sorry to be blunt, but what problem are you actually trying to solve here?

Please can everyone stop second guessing the intelligence of our users. 
Sure - there will always be people who never read any of the docs (and
we can't help them), but for those who do will most likely understand,
and if not, ask a question.

I can, in principle, see the appeal of of customised documentation to
the current build, but it is substantially complicated to do.  Who is it
going to benefit in practice, and can anyone honestly say that it is a
higher priority work item than other things they are doing at the moment?

~Andrew

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

Re: xen-commandline document

[Andrew Cooper]

On 15/01/2019 10:19, Jan Beulich wrote:
>>>> On 15.01.19 at 10:38, <andrew.cooper3@citrix.com> wrote:
>> On 15/01/2019 09:23, Juergen Gross wrote:
>>> Recently there have been several requests to add disclaimers
>>> like "only applicable if CONFIG_xyz defined" to
>>> docs/misc/xen-command-line.pandoc.
>>>
>>> As that file will be used as source for the installed file
>>> /usr/share/doc/xen/html/misc/xen-command-line.html there might be
>>> a better alternative instead of adding such disclaimers: what if
>>> we put such options in #ifdef CONFIG_xyz sections and let CPP
>>> create a file with only those options documented which are
>>> applicable to the installed hypervisor?
>>>
>>> The source file used would be still available for the developer
>>> (who should understand the #ifdefs) while on a Xen host only the
>>> available options would be documented. For locations like
>>>
>>> http://xenbits.xen.org/docs/unstable/misc/xen-command-line.html 
>>>
>>> we could use an "allyesconfig" for each architecture as config
>>> source.
>>>
>>> Thoughts?
>> allyesconfig doesn't work with mutually incompatible options, where one
>> of them will definitely be n
>>
>> Overall, I'm fairly -1 to this idea.  I don't like the idea of merging
>> the xen/ and docs/ builds to be able to make this happen, and while it
>> may be fairly simple and easy in the ARGO case, it is most definitely
>> not in the XSM case.
>>
>> There is a specific reason why documentation isn't written in C, and IMO
>> it should be kept that way.
> Which then, by extension, also makes it preferable for it to not
> talk about C identifiers (here: manifest constants). See my other
> reply in particular regarding the mentioning of the CONFIG_
> prefixes.

There aren't C identifiers in the documentation.  There are direct
references to the other end-user-choosable options in Kconfig.

The fact they happen to use the CONFIG_ prefix is because that is the
easiest way to consistently refer to Kconfig, including how people
discuss the options in email replies, not because they also happen to be
the C identifiers as well.

~Andrew

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

Re: xen-commandline document

[Jan Beulich]

>>> On 15.01.19 at 11:25, <andrew.cooper3@citrix.com> wrote:
> On 15/01/2019 10:19, Jan Beulich wrote:
>>>>> On 15.01.19 at 10:38, <andrew.cooper3@citrix.com> wrote:
>>> On 15/01/2019 09:23, Juergen Gross wrote:
>>>> Recently there have been several requests to add disclaimers
>>>> like "only applicable if CONFIG_xyz defined" to
>>>> docs/misc/xen-command-line.pandoc.
>>>>
>>>> As that file will be used as source for the installed file
>>>> /usr/share/doc/xen/html/misc/xen-command-line.html there might be
>>>> a better alternative instead of adding such disclaimers: what if
>>>> we put such options in #ifdef CONFIG_xyz sections and let CPP
>>>> create a file with only those options documented which are
>>>> applicable to the installed hypervisor?
>>>>
>>>> The source file used would be still available for the developer
>>>> (who should understand the #ifdefs) while on a Xen host only the
>>>> available options would be documented. For locations like
>>>>
>>>> http://xenbits.xen.org/docs/unstable/misc/xen-command-line.html 
>>>>
>>>> we could use an "allyesconfig" for each architecture as config
>>>> source.
>>>>
>>>> Thoughts?
>>> allyesconfig doesn't work with mutually incompatible options, where one
>>> of them will definitely be n
>>>
>>> Overall, I'm fairly -1 to this idea.  I don't like the idea of merging
>>> the xen/ and docs/ builds to be able to make this happen, and while it
>>> may be fairly simple and easy in the ARGO case, it is most definitely
>>> not in the XSM case.
>>>
>>> There is a specific reason why documentation isn't written in C, and IMO
>>> it should be kept that way.
>> Which then, by extension, also makes it preferable for it to not
>> talk about C identifiers (here: manifest constants). See my other
>> reply in particular regarding the mentioning of the CONFIG_
>> prefixes.
> 
> There aren't C identifiers in the documentation.  There are direct
> references to the other end-user-choosable options in Kconfig.

There's nothing end-user-choosable in Kconfig, except for people
who build their own hypervisors instead of consuming distros.

Jan



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

Re: xen-commandline document

[Jan Beulich]

>>> On 15.01.19 at 11:22, <andrew.cooper3@citrix.com> wrote:
> On 15/01/2019 09:59, Juergen Gross wrote:
>> On 15/01/2019 10:38, Andrew Cooper wrote:
>>> On 15/01/2019 09:23, Juergen Gross wrote:
>>>> Recently there have been several requests to add disclaimers
>>>> like "only applicable if CONFIG_xyz defined" to
>>>> docs/misc/xen-command-line.pandoc.
>>>>
>>>> As that file will be used as source for the installed file
>>>> /usr/share/doc/xen/html/misc/xen-command-line.html there might be
>>>> a better alternative instead of adding such disclaimers: what if
>>>> we put such options in #ifdef CONFIG_xyz sections and let CPP
>>>> create a file with only those options documented which are
>>>> applicable to the installed hypervisor?
>>>>
>>>> The source file used would be still available for the developer
>>>> (who should understand the #ifdefs) while on a Xen host only the
>>>> available options would be documented. For locations like
>>>>
>>>> http://xenbits.xen.org/docs/unstable/misc/xen-command-line.html 
>>>>
>>>> we could use an "allyesconfig" for each architecture as config
>>>> source.
>>>>
>>>> Thoughts?
>>> allyesconfig doesn't work with mutually incompatible options, where one
>>> of them will definitely be n
>>>
>>> Overall, I'm fairly -1 to this idea.  I don't like the idea of merging
>>> the xen/ and docs/ builds to be able to make this happen, and while it
>>> may be fairly simple and easy in the ARGO case, it is most definitely
>>> not in the XSM case.
>>>
>>> There is a specific reason why documentation isn't written in C, and IMO
>>> it should be kept that way.
>> Fair enough. :-)
>>
>> So plan B:
>>
>> Give the user an interface to obtain the .config used to create the
>> currently running hypervisor (I guess this was discussed at least once
>> before). I'd suggest an option for "xl info", but I'm open for other
>> interfaces.
>>
>> Then add potential config restrictions to the command line parameter doc
>> (like already done for x86/arm) with a preamble telling the reader how
>> to read those restrictions.
> 
> Sorry to be blunt, but what problem are you actually trying to solve here?
> 
> Please can everyone stop second guessing the intelligence of our users. 
> Sure - there will always be people who never read any of the docs (and
> we can't help them), but for those who do will most likely understand,
> and if not, ask a question.
> 
> I can, in principle, see the appeal of of customised documentation to
> the current build, but it is substantially complicated to do.  Who is it
> going to benefit in practice, and can anyone honestly say that it is a
> higher priority work item than other things they are doing at the moment?

I have to admit that I don't understand the connection of your
reply to Jürgen's plan B proposal: He's no longer suggesting to
produce customized documentation. He's merely suggesting a
way for end users to be able to easily find out whether a given
config option is actually enabled in a hypervisor they hold in
their hands.

Jan


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

Re: xen-commandline document

[Juergen Gross]

On 15/01/2019 11:22, Andrew Cooper wrote:
> On 15/01/2019 09:59, Juergen Gross wrote:
>> On 15/01/2019 10:38, Andrew Cooper wrote:
>>> On 15/01/2019 09:23, Juergen Gross wrote:
>>>> Recently there have been several requests to add disclaimers
>>>> like "only applicable if CONFIG_xyz defined" to
>>>> docs/misc/xen-command-line.pandoc.
>>>>
>>>> As that file will be used as source for the installed file
>>>> /usr/share/doc/xen/html/misc/xen-command-line.html there might be
>>>> a better alternative instead of adding such disclaimers: what if
>>>> we put such options in #ifdef CONFIG_xyz sections and let CPP
>>>> create a file with only those options documented which are
>>>> applicable to the installed hypervisor?
>>>>
>>>> The source file used would be still available for the developer
>>>> (who should understand the #ifdefs) while on a Xen host only the
>>>> available options would be documented. For locations like
>>>>
>>>> http://xenbits.xen.org/docs/unstable/misc/xen-command-line.html
>>>>
>>>> we could use an "allyesconfig" for each architecture as config
>>>> source.
>>>>
>>>> Thoughts?
>>> allyesconfig doesn't work with mutually incompatible options, where one
>>> of them will definitely be n
>>>
>>> Overall, I'm fairly -1 to this idea.  I don't like the idea of merging
>>> the xen/ and docs/ builds to be able to make this happen, and while it
>>> may be fairly simple and easy in the ARGO case, it is most definitely
>>> not in the XSM case.
>>>
>>> There is a specific reason why documentation isn't written in C, and IMO
>>> it should be kept that way.
>> Fair enough. :-)
>>
>> So plan B:
>>
>> Give the user an interface to obtain the .config used to create the
>> currently running hypervisor (I guess this was discussed at least once
>> before). I'd suggest an option for "xl info", but I'm open for other
>> interfaces.
>>
>> Then add potential config restrictions to the command line parameter doc
>> (like already done for x86/arm) with a preamble telling the reader how
>> to read those restrictions.
> 
> Sorry to be blunt, but what problem are you actually trying to solve here?
> 
> Please can everyone stop second guessing the intelligence of our users. 
> Sure - there will always be people who never read any of the docs (and
> we can't help them), but for those who do will most likely understand,
> and if not, ask a question.
> 
> I can, in principle, see the appeal of of customised documentation to
> the current build, but it is substantially complicated to do.  Who is it
> going to benefit in practice, and can anyone honestly say that it is a
> higher priority work item than other things they are doing at the moment?

Why would this proposal be customised documentation?

I'm just suggesting to add information to the documentation and a way to
interprete that information. So like:

### credit2_runqueue (CONFIG_SCHED_CREDIT2)


Juergen


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