Re: [PATCH v1 1/1] x86/Documentation: Update algo in init_size description of boot protocol

["H. Peter Anvin" <hpa@zytor.com>]

On November 25, 2024 12:43:37 PM PST, Ingo Molnar <mingo@kernel.org> wrote:
>
>* Andy Shevchenko <andriy.shevchenko@linux.intel.com> wrote:
>
>> On Mon, Nov 25, 2024 at 09:45:36AM +0100, Ingo Molnar wrote:
>> > * Randy Dunlap <rdunlap@infradead.org> wrote:
>> > > On 11/25/24 12:31 AM, Andy Shevchenko wrote:
>> 
>> ...
>> 
>> > > > -	if (relocatable_kernel)
>> > > > -	runtime_start = align_up(load_address, kernel_alignment)
>> > > > -	else
>> > > > -	runtime_start = pref_address
>> > > > +    if ( relocatable_kernel ) {
>> > > > +      if ( load_address < pref_address )
>> > > 
>> > > What's up with the extra spaces around ( and ) ... and inconsistent with
>> > > the lines below?
>> 
>> I can remove them. This file has a lot of inconsistencies it seems...
>
>Feel free to send a followup patch that fixes up all of those other 
>details and harmonizes the style. Quality of the boot protocol 
>documentation demonstrably matters quite a bit in functional terms as 
>well ...
>
>> 
>> > Also, even pseudocode should follow the kernel's coding style and use 
>> > tabs in particular - which it already does in (some...) other places of 
>> > this document, such as the 'Sample Boot Configuration' chapter.
>> 
>> The problem is that reStructuredText syntax requires that indentation.
>> I may follow the rules after the rST requirements, though.
>
>That's a good solution - thank you!
>
>	Ingo

I, too, would really appreciate help in cleaning up the document and yes, the number of inconsistencies that have crept in over the years is quite frankly embarrassing. In a few places I will admit to thinking "did I actually write this?"

And as Ingo says, it matters, because experience shows that boot loader authors don't ask for clarification, they make their own interpretation and now we are stuck with a legacy. 

One part of the problem is that reviewing documentation changes in patch form hides inconsistencies because you only get a few lines of context.

On top of that, it would be great if the markup language could be used to insert rationale and commentary into the document. In some cases I think it would really help getting better compliance with the spec as intended, explain why we make certain recommendations as opposed to "well it seems to work", and help catch inconsistencies.