netdev - Re: [PATCH net-next] docs: ctucanfd: Use 'kernel-figure' directive instead of 'figure'

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] [thread-next>] [day] [month] [year] [list]

Date:   Wed, 11 May 2022 19:52:35 +0900
From:   Akira Yokosawa <akiyks@...il.com>
To:     Bagas Sanjaya <bagasdotme@...il.com>
Cc:     Marc Kleine-Budde <mkl@...gutronix.de>,
        Pavel Pisa <pisa@....felk.cvut.cz>,
        Martin Jerabek <martin.jerabek01@...il.com>,
        Ondrej Ille <ondrej.ille@...il.com>,
        "David S. Miller" <davem@...emloft.net>,
        Jakub Kicinski <kuba@...nel.org>, netdev@...r.kernel.org,
        linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org
Subject: Re: [PATCH net-next] docs: ctucanfd: Use 'kernel-figure' directive
 instead of 'figure'

On Wed, 11 May 2022 13:37:31 +0700,
Bagas Sanjaya wrote:
> On Tue, May 10, 2022 at 06:34:37PM +0900, Akira Yokosawa wrote:
>> Two issues were observed in the ReST doc added by commit c3a0addefbde
>> ("docs: ctucanfd: CTU CAN FD open-source IP core documentation.").
>>
>> The plain "figure" directive broke "make pdfdocs" due to a missing
>> PDF figure.  For conversion of SVG -> PDF to work, the "kernel-figure"
>> directive, which is an extension for kernel documentations, should
>> be used instead.
>>
>
> Does plain "figure" directive not currently support SVG file argument?
> Because when I see reST documentation ([1]), it doesn't explicitly
> mentioned supported image formats.
>
> [1]: https://docutils.sourceforge.io/docs/ref/rst/directives.html#figure
>

Close!

See:
    https://docutils.sourceforge.io/docs/ref/rst/directives.html#images

There you see the compatibility table of image format vs
output format/user agent.  The argument (URI) can be in any
format a consumer of generated document can render.
It's user's (read: kernel-documentation tool's) responsibility
to prepare images in suitable formats.

For kernel documentation, the "kernel-figure" directive triggers
the conversion of images depending on the output format, so that
compatible images can be used in the generated documents.

Those conversions are independent of what you write in .rst files.
If there emerges another output target which prefers a different
image format, you can always modify the extension code in
kfigure.py.

        Thanks, Akira