[Dropped irrelevant CCs] Hi Bagas, First of all, can I ask you to refrain from submitting new versions everyday? It is one of the most frowned-upon behavior in the kernel community. See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#don-t-get-discouraged-or-impatient I'm intentionally ignoring v4. On Mon, 28 Mar 2022 19:28:51 +0700, Bagas Sanjaya wrote: > On 28/03/22 14.46, Akira Yokosawa wrote: >> 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! >> > > My intention is to give page title for kernel-doc.rst, according to > documentation guideline at [1]. I'm afraid I'm not convinced. Let's see the history of this document. It first appeared in commit 17defc282fe6 ("Documentation: add meta-documentation for Sphinx and kernel-doc") as a chapter among other topics which evolved into current Documentation/doc-guide/. Back then there was a proper document title of "Linux Kernel Documentation". It was renamed "How to write kernel documentation" in commit 555af62431e6 ("docs: retitle the kernel-documentation.rst"), which you still find in Documentation/doc-guide/index.rst. It got split by commit 1dc4bbf0b268 ("docs-rst: doc-guide: split the kernel-documentation.rst contents") in 2016. The title markers have not been touched ever since. This is why you find those markers one level below the ones suggested in the guideline. I think the guideline predates the reorganization of Documentations/ into document-wise subdirectories. It needs some expansion regarding .rst docs included from index.rst files under subdirectories. What does "document title" mean? The one in index.rst? What happens when a .rst file has a "document title"-level title at the beginning? Would it be treated as a "chapter" level title? What happens when an index.rst file is included from another index.rst file? Which title is used as a "page title" in the HTML docs? ... and so on. I'd like to suggest you do the expansion of the guideline itself, which will be much appreciated. Thanks, Akira > [...]
