Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Message-ID: <6a5ce717-cc0a-9b7c-ba08-88e3b9f760bb@gmail.com>
Date:   Mon, 28 Mar 2022 16:46:16 +0900
MIME-Version: 1.0
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:91.0) Gecko/20100101
 Thunderbird/91.7.0
Subject: Re: [PATCH v3 1/2] Documentation: kernel-doc: Promote two chapter
 headings to page title
Content-Language: en-US
To:     Bagas Sanjaya <bagasdotme@gmail.com>
Cc:     Jonathan Corbet <corbet@lwn.net>,
        "David S. Miller" <davem@davemloft.net>,
        Greg Kroah-Hartman <gregkh@linuxfoundation.org>,
        Tony Nguyen <anthony.l.nguyen@intel.com>,
        Vinod Koul <vkoul@kernel.org>,
        Daniel Borkmann <daniel@iogearbox.net>,
        Mauro Carvalho Chehab <mchehab+huawei@kernel.org>,
        "Rafael J. Wysocki" <rafael.j.wysocki@intel.com>,
        Jens Axboe <axboe@kernel.dk>, linux-kernel@vger.kernel.org,
        linux-doc@vger.kernel.org, Akira Yokosawa <akiyks@gmail.com>
References: <20220328065030.24936-1-bagasdotme@gmail.com>
 <20220328065030.24936-2-bagasdotme@gmail.com>
From:   Akira Yokosawa <akiyks@gmail.com>
In-Reply-To: <20220328065030.24936-2-bagasdotme@gmail.com>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit
Precedence: bulk

On Mon, 28 Mar 2022 13:50:30 +0700,
Bagas Sanjaya wrote:
> Promote two chapter headings, named "Writing kernel-doc comments" and
> "Including kernel-doc comments" to page title. These titles deserve
> their own chapters in PDF output, although these will also appear as two
> separate titles in table of contents in HTML output.

As Mauro and I have pointed out, this change won't have any effect
in the resulting HTML and PDF docs.  No difference *at all*.

Why do you think this change is worthwhile.

Please convince us!

> 
> Cc: Jonathan Corbet <corbet@lwn.net>
> Cc: "David S. Miller" <davem@davemloft.net>
> Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
> Cc: Tony Nguyen <anthony.l.nguyen@intel.com>
> Cc: Vinod Koul <vkoul@kernel.org>
> Cc: Daniel Borkmann <daniel@iogearbox.net>
> Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> Cc: Akira Yokosawa <akiyks@gmail.com>
> Cc: "Rafael J. Wysocki" <rafael.j.wysocki@intel.com>
> Cc: Jens Axboe <axboe@kernel.dk>
> Cc: linux-kernel@vger.kernel.org
> Suggested-by: Akira Yokosawa <akiyks@gmail.com>

Please don't put this Suggested-by: at the moment.

        Thanks, Akira

> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
> ---
>  Documentation/doc-guide/kernel-doc.rst | 2 ++
>  1 file changed, 2 insertions(+)
> 
> diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst
> index 79aaa55d6bcf2b..a7cb2afd799007 100644
> --- a/Documentation/doc-guide/kernel-doc.rst
> +++ b/Documentation/doc-guide/kernel-doc.rst
> @@ -1,3 +1,4 @@
> +===========================
>  Writing kernel-doc comments
>  ===========================
>  
> @@ -436,6 +437,7 @@ The title following ``DOC:`` acts as a heading within the source file, but also
>  as an identifier for extracting the documentation comment. Thus, the title must
>  be unique within the file.
>  
> +=============================
>  Including kernel-doc comments
>  =============================
>