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?
>
