linux-kernel - Re: [PATCH RESEND] Documentation: add missing page title for kernel-doc.rst and sphinx.rst

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [day] [month] [year] [list]

Message-ID: <136a0e9e-98ff-68d2-b2a3-147f3910e0a0@gmail.com>
Date:   Sat, 26 Mar 2022 11:22:44 +0700
From:   Bagas Sanjaya <bagasdotme@...il.com>
To:     Jonathan Corbet <corbet@....net>, linux-doc@...r.kernel.org
Cc:     "David S. Miller" <davem@...emloft.net>,
        Greg Kroah-Hartman <gregkh@...uxfoundation.org>,
        Mauro Carvalho Chehab <mchehab+huawei@...nel.org>,
        linux-kernel@...r.kernel.org
Subject: Re: [PATCH RESEND] Documentation: add missing page title for
 kernel-doc.rst and sphinx.rst

On 26/03/22 02.29, Jonathan Corbet wrote:
>> diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst
>> index 79aaa55d6bcf2b..de47b20c806acf 100644
>> --- a/Documentation/doc-guide/kernel-doc.rst
>> +++ b/Documentation/doc-guide/kernel-doc.rst
>> @@ -1,3 +1,7 @@
>> +==========================
>> +kernel-doc Comments Format
>> +==========================
>> +
>>   Writing kernel-doc comments
>>   ===========================
> 
> Honestly, I think this is better fixed just by promoting the existing
> heading up a level.  It describes the file nicely, and we don't need two
> headers there.
> 

OK.

>> diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst
>> index bb36f18ae9ac3e..140507de5a85e0 100644
>> --- a/Documentation/doc-guide/sphinx.rst
>> +++ b/Documentation/doc-guide/sphinx.rst
>> @@ -1,5 +1,9 @@
>>   .. _sphinxdoc:
>>   
>> +=============
>> +Sphinx Primer
>> +=============
>> +
>>   Introduction
>>   ============
> 
> Here, perhaps, replace "Introduction" with "Using Sphinx for kernel
> documentation" or some such and make that the document title?
> 

I agree with your document title suggestion.

-- 
An old man doll... just what I always wanted! - Clara