Hi Randy, Em Thu, 29 Oct 2020 20:17:34 -0700 Randy Dunlap <rdunlap@xxxxxxxxxxxxx> escreveu: > Hi, > > I have noticed a few cases of excess bolding in generated html (seen in both > Firefox and Opera web browsers). > > (1) https://www.kernel.org/doc/html/latest/kernel-hacking/locking.html#futex-api-reference > > In the description of struct hrtimer_sleeper * futex_setup_timer: > > Both the Return line and the next following line are all bold, while the third (final) > line is not bold (as expected): > > Return > > Initialized hrtimer_sleeper structure or NULL if no timeout > value given The problem is related to the indentation of "value given". With ReST, this causes the first line to be print in bold. The reason for that is that a common practice to describe arguments on texts is to use this: foo Does foo things bar Does bar things Without this feature at ReST, the above would need to be: **foo** Does foo things **bar** Does bar things Which is more polluted with symbols, on text mode. - Just changing the kernel-doc markup at kernel/futex.c: /** * futex_setup_timer - set up the sleeping hrtimer. * @time: ptr to the given timeout value * @timeout: the hrtimer_sleeper structure to be set up * @flags: futex flags * @range_ns: optional range in ns * * Return: Initialized hrtimer_sleeper structure or NULL if no timeout * value given */ To: ... * Return: * * Initialized hrtimer_sleeper structure or NULL if no timeout * value given */ Should fix it. > > (2) https://www.kernel.org/doc/html/latest/filesystems/api-summary.html > > In the description of int seq_open(): > > Both the Note line and the following line are all bold, while the final line > is not bold (as expected): > > Note > > seq_open() will allocate a struct seq_file and store its > pointer in file->private_data. This pointer should not be modified. > > > > I looked at scripts/kernel-doc briefly but did not see where this is > happening, so if anyone out there wants a small project to fix, > please go for it. We can't make kernel-doc ignore alignments, as otherwise other things will break, as several kernel-doc markups use indents for some things (like supporting literal-blocks). So, such kind of fixes need to be done at the kernel-doc markups. In this very specific case, though, I guess, some regex could be used to convert things like: * Foo: some multiline * description into something like: * Foo: * * some multiline * description or: * Foo: * * some multiline * description kernel-doc uses this regex to match "Return": my $doc_sect = $doc_com . '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:(.*)'; I guess something could be added after this: if (/$doc_sect/i) { # case insensitive for supported section names $newsection = $1; $newcontents = $2; in order do to the replacement. Maybe something like this (untested): if (/$doc_sect/i) { # case insensitive for supported section names $newsection = $1; $newcontents = $2; my $spaces = $newsection; $spaces =~ s/\S/ /; $newcontents = $spaces . $newcontents; Would do the trick. Thanks, Mauro
