linux-kernel - Re: [PATCH v2 1/2] Documentation: kernel-doc: Promote "Writing kernel-doc comments" to page title

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: <63efab39-68aa-f4c5-1d5d-d708188eb7b0@gmail.com>
Date:   Sun, 27 Mar 2022 17:50:18 +0900
From:   Akira Yokosawa <akiyks@...il.com>
To:     Bagas Sanjaya <bagasdotme@...il.com>,
        Mauro Carvalho Chehab <mchehab@...nel.org>
Cc:     linux-doc@...r.kernel.org, Jonathan Corbet <corbet@....net>,
        "David S. Miller" <davem@...emloft.net>,
        Greg Kroah-Hartman <gregkh@...uxfoundation.org>,
        "Rafael J. Wysocki" <rafael.j.wysocki@...el.com>,
        Jens Axboe <axboe@...nel.dk>,
        Mauro Carvalho Chehab <mchehab+huawei@...nel.org>,
        linux-kernel@...r.kernel.org, Akira Yokosawa <akiyks@...il.com>
Subject: Re: [PATCH v2 1/2] Documentation: kernel-doc: Promote "Writing
 kernel-doc comments" to page title

Hello Bagas,

On Sun, 27 Mar 2022 12:27:20 +0700,
Bagas Sanjaya wrote:
> On 26/03/22 20.56, Mauro Carvalho Chehab wrote:
>> Hmm... I can't really see any differences... What this patch seems to be
>> doing is to just change the markups for each level.
>>
>> See, on Sphinx, the first markup (whatever it is) is level 1, level 2
>> the second different markup and so on.
>>
>> So, before this patch, kernel-doc.rst had:
>>
>>     level 1: Writing kernel-doc comments
>>     =====================================
>>
>>     level 2: How to format kernel-doc comments
>>     ------------------------------------------
>>
>>     level 3: Function parameters
>>     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>>
>> And after it, it will have:
>>
>>     ====================================
>>     level 1: Writing kernel-doc comments
>>     ====================================
>>
>>     level 2: How to format kernel-doc comments
>>     ==========================================
>>
>>     level 3: Function parameters
>>     ----------------------------
>>
>> No semantic changes at all.
>>
>> The only (eventual) value of a change like that would be to make the
>> levels more uniform, but IMO, it is not worth to apply a change like
>> that, as:
>>
>>     1. There are a lot other documents that don't use the more commonly
>>        used level standard;
>>
>>     2. Making all .rst files to use the same definitions is hard;
>>
>>     3. Even if we place everything using identical markups for every
>>        level, as new stuff gets added, different (still valid)
>>        markups could be used on newer documents.
>>
>> Regards,
>> Mauro
>>
> 
> Indeed, fixing heading levels when adding title heading is required because
> without it, Sphinx will complain "indentation inconsistency" error.

I think all you'd need to do would be to promote both of two headings
of

    Title A
    =======

to

    =======
    Title A
    =======

, namely "Writing kernel-doc comments" and "Including kernel-doc
comments".  They deserve their own chapters in PDF.

As Mauro says, such changes won't have any effect on the resulting
pretty-printed docs.  So I'm afraid I don't see any point in 1/2.

        Thanks, Akira

> 
> Maybe better splitting indentation level changes into its own patch, right?
>