Re: [for-next][PATCH 12/26] Documentation: bootconfig: Add a doc for extended boot config

Re: [for-next][PATCH 12/26] Documentation: bootconfig: Add a doc for extended boot config

[Markus Elfring]

I wonder about a few details in the added text.


…
> +++ b/Documentation/admin-guide/bootconfig.rst
…
> +C onfig File Limitation

How do you think about to omit a space character at the beginning
of this line?


> +Currently the maximum config size size is 32KB …

Would you like to avoid a word duplication here?


> +Note: this is not the number of entries but nodes, an entry must consume
> +more than 2 nodes (a key-word and a value). …

I find the relevance of the term “nodes” unclear at the moment.


Could an other wording be nicer than the abbreviation “a doc for … config”
in the commit subject?

Regards,
Markus

Re: [for-next][PATCH 12/26] Documentation: bootconfig: Add a doc for extended boot config

[Masami Hiramatsu]

Hi,

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

> I wonder about a few details in the added text.
> 
> 
> …
> > +++ b/Documentation/admin-guide/bootconfig.rst
> …
> > +C onfig File Limitation
> 
> How do you think about to omit a space character at the beginning
> of this line?

That was my mistake. I used restructured text extension for vim
which collapsed all sections and use "space" key to expand.
Accidentally, I run into edit mode and hit "space" to expand it.
(it actually expanded but also put a space there and I missed it...)

Anyway, it has been fixed (pointed by Rundy)

> > +Currently the maximum config size size is 32KB …
> 
> Would you like to avoid a word duplication here?

Oops, still exist. Thanks!


> > +Note: this is not the number of entries but nodes, an entry must consume
> > +more than 2 nodes (a key-word and a value). …
> 
> I find the relevance of the term “nodes” unclear at the moment.

Indeed, "node" is not well defined. What about this?
---
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".
---

> 
> Could an other wording be nicer than the abbreviation “a doc for … config”
> in the commit subject?

OK, I'll try next time. 

Thank you,

-- 
Masami Hiramatsu <mhiramat@kernel.org>

Re: [for-next][PATCH 12/26] Documentation: bootconfig: Add a doc for extended boot config

[Markus Elfring]

>>> +Currently the maximum config size size is 32KB …
>>
>> Would you like to avoid a word duplication here?
>
> Oops, still exist.

Is there a need to separate the number from the following unit?


> Indeed, "node" is not well defined. What about this?
> ---
> 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 have got still understanding difficulties with such an interpretation.

* Do other contributors find an other word also more appropriate for this use case?

* How will the influence evolve for naming these items?

* Is each element just a string (according to specific rules)?


>> Could an other wording be nicer than the abbreviation “a doc for … config”
>> in the commit subject?
>
> OK, I'll try next time.

Will words like “descriptions”and “configuration”be helpful?

Regards,
Markus

Re: [for-next][PATCH 12/26] Documentation: bootconfig: Add a doc for extended boot config

[Masami Hiramatsu]

On Thu, 20 Feb 2020 16:00:23 +0100
Markus Elfring <Markus.Elfring@web.de> wrote:

> >>> +Currently the maximum config size size is 32KB …
> >>
> >> Would you like to avoid a word duplication here?
> >
> > Oops, still exist.
> 
> Is there a need to separate the number from the following unit?

Sorry, I couldn't understand what you pointed here. Would you mean the
number of file size and nodes?

> > Indeed, "node" is not well defined. What about this?
> > ---
> > 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 have got still understanding difficulties with such an interpretation.
> 
> * Do other contributors find an other word also more appropriate for this use case?

No.

> * How will the influence evolve for naming these items?

Node is used in its API, but from the user's point of view, I think it
is OK to use "key-word" and "value".
Also, since it is hard to count those numbers by manual, I think user
can depend on tools/bootconfig which shows the number of node in the
configuration file now.

> * Is each element just a string (according to specific rules)?

Yes.

> >> Could an other wording be nicer than the abbreviation “a doc for … config”
> >> in the commit subject?
> >
> > OK, I'll try next time.
> 
> Will words like “descriptions”and “configuration”be helpful?

Like "descriptions of ..." ?

Thank you,

> 
> Regards,
> Markus


-- 
Masami Hiramatsu <mhiramat@kernel.org>

Re: [for-next][12/26] Documentation: bootconfig: Add a doc for extended boot config

[Markus Elfring]

>> Is there a need to separate the number from the following unit?
>
> Sorry, I couldn't understand what you pointed here.

Can the specification “… size is 32 KiB …”be more appropriate
(besides a small wording adjustment)?


> Like "descriptions of ..." ?

I got another idea also for the provided documentation format.
https://git.kernel.org/pub/scm/linux/kernel/git/next/linux-next.git/tree/Documentation/admin-guide/bootconfig.rst?id=bee46b309a13ca158c99c325d0408fb2f0db207f#n18

* Will a file format description become helpful in the way of
  an extended Backus–Naur form?

* How will data processing evolve around the added structures?

Regards,
Markus

Re: [for-next][12/26] Documentation: bootconfig: Add a doc for extended boot config

[Masami Hiramatsu]

On Fri, 21 Feb 2020 17:43:32 +0100
Markus Elfring <Markus.Elfring@web.de> wrote:

> >> Is there a need to separate the number from the following unit?
> >
> > Sorry, I couldn't understand what you pointed here.
> 
> Can the specification “… size is 32 KiB …”be more appropriate
> (besides a small wording adjustment)?

OK, I'll update as so :)

> > Like "descriptions of ..." ?
> 
> I got another idea also for the provided documentation format.
> https://git.kernel.org/pub/scm/linux/kernel/git/next/linux-next.git/tree/Documentation/admin-guide/bootconfig.rst?id=bee46b309a13ca158c99c325d0408fb2f0db207f#n18
> 
> * Will a file format description become helpful in the way of
>   an extended Backus–Naur form?

Good suggestion! Let me try to write an EBNF section.
I think EBNF can logically explain the format, but not intuitive
- we need some examples.

> * How will data processing evolve around the added structures?

OK, I'll add some more API (and usage) differences from the legacy
command line.

Thank you,

-- 
Masami Hiramatsu <mhiramat@kernel.org>

Re: [for-next][12/26] Documentation: bootconfig: Add a doc for extended boot config

[Markus Elfring]

>> * Will a file format description become helpful in the way of
>>   an extended Backus–Naur form?
>
> Good suggestion! Let me try to write an EBNF section.

Is there a need to provide two format descriptions as separate files
(so that they can help more for different software users)?

* RST
* EBNF


Will it matter to adjust another wording?

-/proc/bootconfig is a user-space interface of the boot config.
+The file “/proc/bootconfig” is an user-space interface to the configuration
+of system boot parameters.

Regards,
Markus

Re: [for-next][12/26] Documentation: bootconfig: Add a doc for extended boot config

[Masami Hiramatsu]

On Sat, 22 Feb 2020 10:48:28 +0100
Markus Elfring <Markus.Elfring@web.de> wrote:

> >> * Will a file format description become helpful in the way of
> >>   an extended Backus–Naur form?
> >
> > Good suggestion! Let me try to write an EBNF section.
> 
> Is there a need to provide two format descriptions as separate files
> (so that they can help more for different software users)?
> 
> * RST
> * EBNF

Hmm, since RST is enough flexible, we can write it as a section.
Then user can copy & paste if they need it.

> 
> 
> Will it matter to adjust another wording?
> 
> -/proc/bootconfig is a user-space interface of the boot config.
> +The file “/proc/bootconfig” is an user-space interface to the configuration
> +of system boot parameters.

OK.

Thank you,


-- 
Masami Hiramatsu <mhiramat@kernel.org>

Re: [for-next][12/26] Documentation: bootconfig: Add a doc for extended boot config

[Markus Elfring]

>> Is there a need to provide two format descriptions as separate files
>> (so that they can help more for different software users)?
>>
>> * RST
>> * EBNF
>
> Hmm, since RST is enough flexible, we can write it as a section.

I guess that there are further design options to consider.


> Then user can copy & paste if they need it.

I imagine that it can be more convenient to refer to an EBNF file directly
if an other software developer would like to generate customised parsers
based on available information.

Regards,
Markus

Re: [for-next][12/26] Documentation: bootconfig: Add a doc for extended boot config

[Masami Hiramatsu]

Hi Markus,

On Sat, 22 Feb 2020 17:15:57 +0100
Markus Elfring <Markus.Elfring@web.de> wrote:

> >> Is there a need to provide two format descriptions as separate files
> >> (so that they can help more for different software users)?
> >>
> >> * RST
> >> * EBNF
> >
> > Hmm, since RST is enough flexible, we can write it as a section.
> 
> I guess that there are further design options to consider.
> 
> 
> > Then user can copy & paste if they need it.
> 
> I imagine that it can be more convenient to refer to an EBNF file directly
> if an other software developer would like to generate customised parsers
> based on available information.

OK, I'll try to make a split EBNF file and include it.

Thank you,

-- 
Masami Hiramatsu <mhiramat@kernel.org>

Re: [for-next][12/26] Documentation: bootconfig: Add a doc for extended boot config

[Markus Elfring]

> OK, I'll try to make a split EBNF file and include it.

Thanks for your positive feedback.


How do you think about to clarify any additional software design options
around involved data structures?

Regards,
Markus

Re: [for-next][12/26] Documentation: bootconfig: Add a doc for extended boot config

[Masami Hiramatsu]

Hi,

On Mon, 24 Feb 2020 11:00:31 +0100
Markus Elfring <Markus.Elfring@web.de> wrote:

> > OK, I'll try to make a split EBNF file and include it.
> 
> Thanks for your positive feedback.
> 
> 
> How do you think about to clarify any additional software design options
> around involved data structures?

Sorry, what would you mean the "involved data structures" here?
Would you mean the usage of APIs or when to use bootconfig or command line?

Thank you,

> 
> Regards,
> Markus


-- 
Masami Hiramatsu <mhiramat@kernel.org>

Re: [for-next][12/26] Documentation: bootconfig: Add a doc for extended boot config

[Markus Elfring]

>> How do you think about to clarify any additional software design options
>> around involved data structures?
>
> Sorry, what would you mean the "involved data structures" here?
> Would you mean the usage of APIs or when to use bootconfig or command line?

Additional system boot parameters can be managed also by a single file.
The file format will trigger specific parsing efforts.

* Linux functions are provided for the handling of available information.

* I imagine that another software library will become helpful
  besides the file interface.
  Will further bindings evolve for various programming languages?

* How do you think about to work with a higher level file system?
  Would you like to increase the granularity for corresponding
  data accesses (by user-space processes)?

Regards,
Markus

Re: [for-next][12/26] Documentation: bootconfig: Add a doc for extended boot config

[Masami Hiramatsu]

On Tue, 25 Feb 2020 08:56:41 +0100
Markus Elfring <Markus.Elfring@web.de> wrote:

> >> How do you think about to clarify any additional software design options
> >> around involved data structures?
> >
> > Sorry, what would you mean the "involved data structures" here?
> > Would you mean the usage of APIs or when to use bootconfig or command line?
> 
> Additional system boot parameters can be managed also by a single file.
> The file format will trigger specific parsing efforts.

Maybe. If someone is interested in expanding their command, (e.g. vim)
they can use EBNF to understand syntax, or directly reuse lib/bootconfig.c
which provides a compact parser. :)

Thank you,

-- 
Masami Hiramatsu <mhiramat@kernel.org>

Re: [for-next][12/26] Documentation: bootconfig: Add a doc for extended boot config

[Markus Elfring]

>> The file format will trigger specific parsing efforts.
>
> Maybe. If someone is interested in expanding their command, (e.g. vim)
> they can use EBNF to understand syntax,

I hope so.


> or directly reuse lib/bootconfig.c which provides a compact parser. :)

I see some development challenges according to this design direction.
This software component is using programming interfaces from
the Linux kernel, isn't it?
https://git.kernel.org/pub/scm/linux/kernel/git/next/linux-next.git/tree/lib/bootconfig.c?id=c99b17ac03994525092fd66bed14b4a0c82f0b4d#n9

I guess that other approaches should be considered for the desired
software reuse in this system configuration area.

Is there a need to map key and value combinations directly to files
(and directories) for a more convenient data processing by user-space processes?

Regards,
Markus