Re: excess bolding in html

[Mauro Carvalho Chehab <mchehab@kernel.org>]

Hi Randy,

Em Thu, 29 Oct 2020 20:17:34 -0700
Randy Dunlap <rdunlap@infradead.org> 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