Re: [PATCH 1/1] Documentation: kbuild: explicitly document missing prompt

[Stephen Brennan <stephen.s.brennan@oracle.com>]

Nathan Chancellor <nathan@kernel.org> writes:

> Hi Stephen,
>
> On Tue, Aug 20, 2024 at 10:09:46AM -0700, Stephen Brennan wrote:
>> There are a few lines in the kbuild-language.rst document which
>> obliquely reference the behavior of config options without prompts.
>> But there is nothing in the obvious location that explicitly calls
>> out that users cannot edit config options unless they have a prompt.
>
> Sure, I think the mention of "non-visible symbols" plus "no prompts
> anywhere" in the select section is both a little cryptic to people who
> are not pretty familiar with Kconfig and slightly disjoint from the
> prompt section, so some clarification and expansion would not be a bad
> idea! I do have some suggestions for the wording below.
>
>> Signed-off-by: Stephen Brennan <stephen.s.brennan@oracle.com>
>> ---
>>  Documentation/kbuild/kconfig-language.rst | 3 +++
>>  1 file changed, 3 insertions(+)
>> 
>> diff --git a/Documentation/kbuild/kconfig-language.rst b/Documentation/kbuild/kconfig-language.rst
>> index 1fb3f5e6193c3..8e9306b599cd3 100644
>> --- a/Documentation/kbuild/kconfig-language.rst
>> +++ b/Documentation/kbuild/kconfig-language.rst
>> @@ -54,40 +54,43 @@ applicable everywhere (see syntax).
>>  
>>  - type definition: "bool"/"tristate"/"string"/"hex"/"int"
>>  
>>    Every config option must have a type. There are only two basic types:
>>    tristate and string; the other types are based on these two. The type
>>    definition optionally accepts an input prompt, so these two examples
>>    are equivalent::
>>  
>>  	bool "Networking support"
>>  
>>    and::
>>  
>>  	bool
>>  	prompt "Networking support"
>>  
>>  - input prompt: "prompt" <prompt> ["if" <expr>]
>>  
>>    Every menu entry can have at most one prompt, which is used to display
>>    to the user. Optionally dependencies only for this prompt can be added
>>    with "if".
>> +  If a prompt is not set, then the config option cannot be changed by the user.
>
> Would "not present" be cleared than "not set"? It might also be worth
> calling out here no prompt means a "non-visible" symbol since you
> brought up the document brings that term up and does not really tell you
> what it means.

I realized this exact issue re: "non-visible" upon re-reading the cover
letter & patch after sending, so I 100% agree.

> Perhaps something like this might be just as clear while being
> consistent with the terminology? Feel free to disagree though!
>
>   If a prompt is not present, the config option is a non-visible symbol,
>   meaning its value cannot be directly changed by the user (such as
>   altering the value in ``.config``) and the option will not appear in
>   any config menus. Its value can only be set via "default" and "select"
>   (see below).

I think this better than my suggestion :)

I'll send a v2 with that wording.

Thanks,
Stephen

>> +  It will not appear in any menu, and even edits to ``.config`` cannot alter it.
>> +  It can still be set via "default" and "select" (see below).
>>  
>>  - default value: "default" <expr> ["if" <expr>]
>>  
>>    A config option can have any number of default values. If multiple
>>    default values are visible, only the first defined one is active.
>>    Default values are not limited to the menu entry where they are
>>    defined. This means the default can be defined somewhere else or be
>>    overridden by an earlier definition.
>>    The default value is only assigned to the config symbol if no other
>>    value was set by the user (via the input prompt above). If an input
>>    prompt is visible the default value is presented to the user and can
>>    be overridden by him.
>>    Optionally, dependencies only for this default value can be added with
>>    "if".
>>  
>>   The default value deliberately defaults to 'n' in order to avoid bloating the
>>   build. With few exceptions, new config options should not change this. The
>>   intent is for "make oldconfig" to add as little as possible to the config from
>>   release to release.
>>  
>> -- 
>> 2.43.5
>>