lkml.org 
[lkml]   [2022]   [Mar]   [27]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
Date
SubjectRe: [PATCH v2 1/2] Documentation: kernel-doc: Promote "Writing kernel-doc comments" to page title
From
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?
>

\
 
 \ /
  Last update: 2022-03-27 10:51    [W:0.062 / U:0.752 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site