linux-kernel - Re: [PATCH 0/2] docs: Add automatic cross-reference for C types

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [day] [month] [year] [list]

Message-ID: <20200903153316.2f31f4d6@lwn.net>
Date:   Thu, 3 Sep 2020 15:33:16 -0600
From:   Jonathan Corbet <corbet@....net>
To:     "Nícolas F. R. A. Prado" <nfraprado@...tonmail.com>
Cc:     linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org,
        lkcamp@...ts.libreplanetbr.org, andrealmeid@...labora.com
Subject: Re: [PATCH 0/2] docs: Add automatic cross-reference for C types

On Thu, 03 Sep 2020 00:58:09 +0000
Nícolas F. R. A. Prado <nfraprado@...tonmail.com> wrote:

> In order to cross-reference C types in the documentation, Sphinx
> requires the syntax :c:type:`type_name`, or even :c:type:`struct
> type_name <type_name>` in order to have the link text different from the
> target text.
> This patch series removes the need for that markup.
> 
> The first commit extends the automarkup script to enable automatic
> cross-reference of C types by matching any "struct|union|enum|typedef type_name"
> expression.
> This makes the documentation's plain text cleaner and adds cross-reference to
> types without any additional effort by the author.
> 
> The second commit updates the "Cross-referencing from
> reStructuredText" section in Documentation/doc-guide/kernel-doc.rst
> to reflect that no additional syntax is needed when cross-referencing both types
> and functions anymore.

So I've looked this over, applied it, looked at how the output changes,
and generally put an untoward amount of effort into finding something to
grumble about.

I failed.

This is a great change - thanks for stepping up and doing it!

> When testing this, I did find an edge-case from the output of
> Documentation/output/scsi/scsi_mid_low_api.rst on the "typedef struct scsi_cmnd
> Scsi_Cmnd;", where 'typedef struct' is being identified as a reference, but
> there isn't any named 'struct', so it renders bold.
> I thought of adding an ignore_names list just like there is one for functions,
> with 'struct' in it, to workaround this edge case, but since it was the only
> one I found, and also because it was unclear what the desired output was
> (cross-reference 'struct scsi_cmnd' or leave the whole expression as plain text)
> I wanted to get some feedback beforehand.

As Randy pointed out, the documentation in question is obsolete and
incorrect anyway; there's really not much that can be done in the docs
build system to fix *that*.  I'm not going to worry about this particular
glitch.  If you felt so inspired, a patch to the SCSI maintainers just
removing that paragraph might be well received.

I'm going to go ahead and push this out to linux-next; we'll see if
anything explodes from there.

Thanks,

jon