Re: [Xen-devel] xen-commandline document

["Jan Beulich" <JBeulich@xxxxxxxx>]

>>> On 15.01.19 at 11:22, <andrew.cooper3@xxxxxxxxxx> 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@xxxxxxxxxxxxxxxxxxxx
https://lists.xenproject.org/mailman/listinfo/xen-devel