[PATCH] Documentation: x86: fix boot.rst warning and format

[PATCH] Documentation: x86: fix boot.rst warning and format

[Randy Dunlap]

From: Randy Dunlap <rdunlap@infradead.org>

Fix a Sphinx documentation format warning by breaking a long line
into 2 lines.

Also drop the ':' usage after the Protocol version numbers since
other Protocol versions don't use colons.

Documentation/x86/boot.rst:72: WARNING: Malformed table.
Text in column margin in table line 57.

Fixes: 2c33c27fd603 ("x86/boot: Introduce kernel_info")
Fixes: 00cd1c154d56 ("x86/boot: Introduce kernel_info.setup_type_max")
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Cc: Thomas Gleixner <tglx@linutronix.de>
Cc: Ingo Molnar <mingo@redhat.com>
Cc: Borislav Petkov <bp@alien8.de>
Cc: "H. Peter Anvin" <hpa@zytor.com>
Cc: x86@kernel.org
Cc: Daniel Kiper <daniel.kiper@oracle.com>
---
 Documentation/x86/boot.rst |    5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

--- linux-next-20191209.orig/Documentation/x86/boot.rst
+++ linux-next-20191209/Documentation/x86/boot.rst
@@ -69,11 +69,12 @@ Protocol 2.13	(Kernel 3.14) Support 32-
 		xloadflags to support booting a 64-bit kernel from 32-bit
 		EFI
 
-Protocol 2.14:	BURNT BY INCORRECT COMMIT ae7e1238e68f2a472a125673ab506d49158c1889
+Protocol 2.14	BURNT BY INCORRECT COMMIT
+                ae7e1238e68f2a472a125673ab506d49158c1889
 		(x86/boot: Add ACPI RSDP address to setup_header)
 		DO NOT USE!!! ASSUME SAME AS 2.13.
 
-Protocol 2.15:	(Kernel 5.5) Added the kernel_info and kernel_info.setup_type_max.
+Protocol 2.15	(Kernel 5.5) Added the kernel_info and kernel_info.setup_type_max.
 =============	============================================================
 
 .. note::

Re: [PATCH] Documentation: x86: fix boot.rst warning and format

[Daniel Kiper]

On Sun, Dec 08, 2019 at 08:25:10PM -0800, Randy Dunlap wrote:
> From: Randy Dunlap <rdunlap@infradead.org>
>
> Fix a Sphinx documentation format warning by breaking a long line
> into 2 lines.
>
> Also drop the ':' usage after the Protocol version numbers since
> other Protocol versions don't use colons.
>
> Documentation/x86/boot.rst:72: WARNING: Malformed table.
> Text in column margin in table line 57.
>
> Fixes: 2c33c27fd603 ("x86/boot: Introduce kernel_info")
> Fixes: 00cd1c154d56 ("x86/boot: Introduce kernel_info.setup_type_max")
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> Cc: Jonathan Corbet <corbet@lwn.net>
> Cc: linux-doc@vger.kernel.org
> Cc: Thomas Gleixner <tglx@linutronix.de>
> Cc: Ingo Molnar <mingo@redhat.com>
> Cc: Borislav Petkov <bp@alien8.de>
> Cc: "H. Peter Anvin" <hpa@zytor.com>
> Cc: x86@kernel.org
> Cc: Daniel Kiper <daniel.kiper@oracle.com>

Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>

What can I do next time to avoid mistakes like that? I suppose that
I can run something to get this warning but I do not know what exactly
it should be.

Daniel

Re: [PATCH] Documentation: x86: fix boot.rst warning and format

[Randy Dunlap]

On 12/9/19 8:13 AM, Daniel Kiper wrote:
> On Sun, Dec 08, 2019 at 08:25:10PM -0800, Randy Dunlap wrote:
>> From: Randy Dunlap <rdunlap@infradead.org>
>>
>> Fix a Sphinx documentation format warning by breaking a long line
>> into 2 lines.
>>
>> Also drop the ':' usage after the Protocol version numbers since
>> other Protocol versions don't use colons.
>>
>> Documentation/x86/boot.rst:72: WARNING: Malformed table.
>> Text in column margin in table line 57.
>>
>> Fixes: 2c33c27fd603 ("x86/boot: Introduce kernel_info")
>> Fixes: 00cd1c154d56 ("x86/boot: Introduce kernel_info.setup_type_max")
>> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
>> Cc: Jonathan Corbet <corbet@lwn.net>
>> Cc: linux-doc@vger.kernel.org
>> Cc: Thomas Gleixner <tglx@linutronix.de>
>> Cc: Ingo Molnar <mingo@redhat.com>
>> Cc: Borislav Petkov <bp@alien8.de>
>> Cc: "H. Peter Anvin" <hpa@zytor.com>
>> Cc: x86@kernel.org
>> Cc: Daniel Kiper <daniel.kiper@oracle.com>
> 
> Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
> 
> What can I do next time to avoid mistakes like that? I suppose that
> I can run something to get this warning but I do not know what exactly
> it should be.

I just do:
$ mkdir DOC1
$ make O=DOC1 htmldocs &>doc1.out

doc1.out will contain the build log for the documentation.
It will be large.  :(
Just grep (or use editor search) for the file(s) that you are
interested in.


thanks.
-- 
~Randy

Re: [PATCH] Documentation: x86: fix boot.rst warning and format

[Matthew Wilcox]

On Mon, Dec 09, 2019 at 08:26:17AM -0800, Randy Dunlap wrote:
> On 12/9/19 8:13 AM, Daniel Kiper wrote:
> > What can I do next time to avoid mistakes like that? I suppose that
> > I can run something to get this warning but I do not know what exactly
> > it should be.
> 
> I just do:
> $ mkdir DOC1
> $ make O=DOC1 htmldocs &>doc1.out
> 
> doc1.out will contain the build log for the documentation.
> It will be large.  :(
> Just grep (or use editor search) for the file(s) that you are
> interested in.

"make W=1" will show warnings from the kernel-doc program without going to
the trouble of building the documentation.  We can enable it by default
once the number of extra warnings it produces is reduced significantly
(in November 2017 it was 1300).

Re: [PATCH] Documentation: x86: fix boot.rst warning and format

[Jonathan Corbet]

On Sun, 8 Dec 2019 20:25:10 -0800
Randy Dunlap <rdunlap@infradead.org> wrote:

> Fix a Sphinx documentation format warning by breaking a long line
> into 2 lines.
> 
> Also drop the ':' usage after the Protocol version numbers since
> other Protocol versions don't use colons.
> 
> Documentation/x86/boot.rst:72: WARNING: Malformed table.
> Text in column margin in table line 57.
> 
> Fixes: 2c33c27fd603 ("x86/boot: Introduce kernel_info")
> Fixes: 00cd1c154d56 ("x86/boot: Introduce kernel_info.setup_type_max")
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> Cc: Jonathan Corbet <corbet@lwn.net>
> Cc: linux-doc@vger.kernel.org
> Cc: Thomas Gleixner <tglx@linutronix.de>
> Cc: Ingo Molnar <mingo@redhat.com>
> Cc: Borislav Petkov <bp@alien8.de>
> Cc: "H. Peter Anvin" <hpa@zytor.com>
> Cc: x86@kernel.org
> Cc: Daniel Kiper <daniel.kiper@oracle.com>
> ---
>  Documentation/x86/boot.rst |    5 +++--
>  1 file changed, 3 insertions(+), 2 deletions(-)

Applied, thanks.

jon