Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Message-ID: <ec431b19-520f-b202-33f6-4ba336743ee3@gmail.com>
Date:   Wed, 11 May 2022 19:52:35 +0900
MIME-Version: 1.0
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:91.0) Gecko/20100101
 Thunderbird/91.8.1
From:   Akira Yokosawa <akiyks@gmail.com>
Subject: Re: [PATCH net-next] docs: ctucanfd: Use 'kernel-figure' directive
 instead of 'figure'
To:     Bagas Sanjaya <bagasdotme@gmail.com>
Cc:     Marc Kleine-Budde <mkl@pengutronix.de>,
        Pavel Pisa <pisa@cmp.felk.cvut.cz>,
        Martin Jerabek <martin.jerabek01@gmail.com>,
        Ondrej Ille <ondrej.ille@gmail.com>,
        "David S. Miller" <davem@davemloft.net>,
        Jakub Kicinski <kuba@kernel.org>, netdev@vger.kernel.org,
        linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org
References: <05d491d4-c498-9bab-7085-9c892b636d68@gmail.com>
 <YntZqxuLSci6f8Z+@debian.me>
Content-Language: en-US
In-Reply-To: <YntZqxuLSci6f8Z+@debian.me>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit
Precedence: bulk

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