On Mon, 18 Jan 2021 12:08:13 +0100
Michal Wajdeczko <michal.wajdeczko@xxxxxxxxx> wrote:
> While DOC: section titles are not converted into RST headings
> sections and are only decorated with strong emphasis markup,
> nothing stops us from generating internal hyperlinks for them,
> to mimic implicit hyperlinks to RST headings.
>
> Signed-off-by: Michal Wajdeczko <michal.wajdeczko@xxxxxxxxx>
> Cc: Jonathan Corbet <corbet@xxxxxxx>
> Cc: Jani Nikula <jani.nikula@xxxxxxxxx>
> Cc: Chris Wilson <chris@xxxxxxxxxxxxxxxxxx>
So I've applied this, but ...
> scripts/kernel-doc | 1 +
> 1 file changed, 1 insertion(+)
>
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index 6325bec3f66f..272f70c9fb13 100755
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -833,6 +833,7 @@ sub output_blockhead_rst(%) {
> next if (defined($nosymbol_table{$section}));
>
> if ($output_selection != OUTPUT_INCLUDE) {
> + print ".. _$section:\n\n";
> print "**$section**\n\n";
> }
...the placement within this if means that the section marker doesn't
appear whenever a doc block is explicitly included with the :doc: modifier
- which I think is much of the time. I *think* the marker should be
output unconditionally.
Jani, you appear to be the culprit behind that particular "if", which
seems a little questionable to me in general at the moment, but you must
have had a good reason. Do you see any reason why a section marker should
be suppressed in the same way?
Thanks,
jon
