Re: [PATCH 1/2] Documentation: bootconfig: Update boot configuration documentation

Re: [PATCH 1/2] Documentation: bootconfig: Update boot configuration documentation

[Markus Elfring]

> +This allows administrators to pass a structured-Key configuration file

Does capitalisation matter here for the word “Key”?


> +If you think that kernel/init options becomes too long to write in boot-loader
> +configuration file or want to comment on each options, you can use this

Can the following wording variant be a bit nicer?

+… or you want to comment on each option, …


> +Also, some subsystem may depend on the boot configuration, and it has own
> +root key.

Would you like to explain the influence of a key hierarchy any further?


> +The boot configuration syntax allows user to merge partially same word keys
>  by brace. For example::

“by braces.
For example::”?


> +The file /proc/bootconfig is a user-space interface to the configuration

“… is an user-…”?


> +Currently the maximum configuration size is 32 KiB and the total number
> +of key-words and values must be under 1024 nodes.

* How were these constraints chosen?

* Can such system limits become more configurable?


> +(Note: Each key consists of words separated by dot, and value also consists
> +of values separated by comma. Here, each word and each value is generally
> +called a "node".)

I would prefer the interpretation that nodes contain corresponding attributes.

How do you think about to add a link to a formal file format description?

Regards,
Markus

Re: [PATCH 2/2] Documentation: bootconfig: Add EBNF syntax file

[Markus Elfring]

Thanks for such a contribution.


> Add an extended Backus–Naur form (EBNF) syntax file for

Can it matter to mention the specific file format specification version
which should be applied finally?

Would you like to refer to any standard variant?


> bootconfig so that user can logically understand how they

Wording alternative “… that users can …”?


> can write correct boot configuration file.

Related development tools provide some benefits then, don't they?



…
> +++ b/Documentation/admin-guide/bootconfig.ebnf
…
> +digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ;

Can the specification of such alternatives (or value ranges) become
more compact (depending on a selected standard)?


…
> +++ b/Documentation/admin-guide/bootconfig.rst
…
> +Here is the boot configuration file syntax written in EBNF.

I suggest to replace the abbreviation “EBNF” by the term “extended Backus–Naur form”
in such a sentence.

Regards,
Markus

Re: [PATCH 2/2] Documentation: bootconfig: Add EBNF syntax file

[Masami Hiramatsu]

On Thu, 27 Feb 2020 20:53:03 +0100
Markus Elfring <Markus.Elfring@web.de> wrote:

> Thanks for such a contribution.
> 
> 
> > Add an extended Backus–Naur form (EBNF) syntax file for
> 
> Can it matter to mention the specific file format specification version
> which should be applied finally?
> 
> Would you like to refer to any standard variant?

I choose ISO/IEC 14977 : 1996(E), but it seems no good.

Don’t Use ISO/IEC 14977 Extended Backus-Naur Form (EBNF)
https://dwheeler.com/essays/dont-use-iso-14977-ebnf.html

I agree with this article. the ISO 14977 is halfway...
Not easy for human, but not good for machine too.
(at least it should support #xN as same as W3C BNF.

I'll drop it until rewriten by other standerd.

> > bootconfig so that user can logically understand how they
> 
> Wording alternative “… that users can …”?
> 
> 
> > can write correct boot configuration file.
> 
> Related development tools provide some benefits then, don't they?
> 
> 
> 
> …
> > +++ b/Documentation/admin-guide/bootconfig.ebnf
> …
> > +digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ;
> 
> Can the specification of such alternatives (or value ranges) become
> more compact (depending on a selected standard)?

W3C EBNF support it, ISO14977 doesn't.

> …
> > +++ b/Documentation/admin-guide/bootconfig.rst
> …
> > +Here is the boot configuration file syntax written in EBNF.
> 
> I suggest to replace the abbreviation “EBNF” by the term “extended Backus–Naur form”
> in such a sentence.

I think EBNF is enough.

Thank you,

-- 
Masami Hiramatsu <mhiramat@kernel.org>

Re: [PATCH 1/2] Documentation: bootconfig: Update boot configuration documentation

[Randy Dunlap]

On 2/27/20 11:12 AM, Markus Elfring wrote:
> 
>> +The boot configuration syntax allows user to merge partially same word keys
>>  by brace. For example::
> 
> “by braces.
> For example::”?

It is fine as Masami has it IMO.

> 
> 
>> +The file /proc/bootconfig is a user-space interface to the configuration
> 
> “… is an user-…”?

No, "is a user-space" or "is a userspace" is good.


-- 
~Randy

Re: [PATCH 1/2] Documentation: bootconfig: Update boot configuration documentation

[Masami Hiramatsu]

On Thu, 27 Feb 2020 20:12:17 +0100
Markus Elfring <Markus.Elfring@web.de> wrote:

> > +This allows administrators to pass a structured-Key configuration file
> 
> Does capitalisation matter here for the word “Key”?

Oops, thanks! that's a typo of key.

> > +If you think that kernel/init options becomes too long to write in boot-loader
> > +configuration file or want to comment on each options, you can use this
> 
> Can the following wording variant be a bit nicer?
> 
> +… or you want to comment on each option, …

OK, since the previous sentence is too long, it is more readable to put the
subject there.

> > +Also, some subsystem may depend on the boot configuration, and it has own
> > +root key.
> 
> Would you like to explain the influence of a key hierarchy any further?

Please read the example (boot time tracer) carefully :)

> > +The boot configuration syntax allows user to merge partially same word keys
> >  by brace. For example::
> 
> “by braces.
> For example::”?

I think current one is shorter and compact.

> > +The file /proc/bootconfig is a user-space interface to the configuration
> 
> “… is an user-…”?

Hm, it seems "a user" is correct wording.
https://www.quora.com/Which-is-the-correct-usage-a-user-or-an-user

> > +Currently the maximum configuration size is 32 KiB and the total number
> > +of key-words and values must be under 1024 nodes.
> 
> * How were these constraints chosen?
> 
> * Can such system limits become more configurable?

No.

> > +(Note: Each key consists of words separated by dot, and value also consists
> > +of values separated by comma. Here, each word and each value is generally
> > +called a "node".)
> 
> I would prefer the interpretation that nodes contain corresponding attributes.

No. Node is a node. It is merely generic.

> 
> How do you think about to add a link to a formal file format description?

Oh, nice idea. Please contribute it :)

Thank you,

-- 
Masami Hiramatsu <mhiramat@kernel.org>

Re: [1/2] Documentation: bootconfig: Update boot configuration documentation

[Markus Elfring]

>>> +Also, some subsystem may depend on the boot configuration, and it has own
>>> +root key.
>>
>> Would you like to explain the influence of a key hierarchy any further?
>
> Please read the example (boot time tracer) carefully :)

I find the descriptions still too terse for corresponding relationships.


>> * Can such system limits become more configurable?
>
> No.

The possibility remains to adjust the source code also for special needs.


>>> +(Note: Each key consists of words separated by dot, and value also consists
>>> +of values separated by comma. Here, each word and each value is generally
>>> +called a "node".)
>>
>> I would prefer the interpretation that nodes contain corresponding attributes.
>
> No. Node is a node. It is merely generic.

I hope that the applied ontology will be clarified a bit more.


>> How do you think about to add a link to a formal file format description?
>
> Oh, nice idea. Please contribute it :)

Did you provide it (according to a RST include directive in the subsequent
update step)?

Can it be helpful to reorder any changes for the discussed patch series?

Regards,
Markus

Re: [1/2] Documentation: bootconfig: Update boot configuration documentation

[Masami Hiramatsu]

On Fri, 28 Feb 2020 09:30:27 +0100
Markus Elfring <Markus.Elfring@web.de> wrote:

> >> How do you think about to add a link to a formal file format description?
> >
> > Oh, nice idea. Please contribute it :)
> 
> Did you provide it (according to a RST include directive in the subsequent
> update step)?

No I didn't. I you think that is important, feel free to write up. You have
a parser code in the kernel already. It might be not hard for you. :)

Thank you,

-- 
Masami Hiramatsu <mhiramat@kernel.org>

Re: [1/2] Documentation: bootconfig: Update boot configuration documentation

[Markus Elfring]

>>>> How do you think about to add a link to a formal file format description?
>>>
>>> Oh, nice idea. Please contribute it :)
>>
>> Did you provide it (according to a RST include directive in the subsequent
>> update step)?
>
> No I didn't.

I hope that more progress can be achieved around the published suggestion
“bootconfig: Add EBNF syntax file”.
https://lore.kernel.org/linux-doc/158278836196.14966.3881489301852781521.stgit@devnote2/
https://lore.kernel.org/patchwork/patch/1200987/
https://lkml.org/lkml/2020/2/27/72


> I you think that is important, feel free to write up.

I am curious how the software development attention will evolve further.


> You have a parser code in the kernel already.

This software component is useful there.


> It might be not hard for you. :)

Some challenges are waiting on corresponding solutions.

Regards,
Markus

Re: [PATCH 2/2] Documentation: bootconfig: Add EBNF syntax file

[Markus Elfring]

…
> +++ b/Documentation/admin-guide/bootconfig.rst
…
> +Syntax in EBNF
> +--------------
> +
> +Here is the boot configuration file syntax written in EBNF.
> +
> +.. include:: bootconfig.ebnf
> +   :literal:

How do you think about to move the content for this section into another RST file
so that it can be used as a text module?

Would you like to improve the outline and corresponding reuse
for such information any further?

Regards,
Markus