On Mon, 28 Nov 2016, Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx> wrote:
> Em Mon, 28 Nov 2016 09:22:31 +0100
> Markus Heiser <markus.heiser@xxxxxxxxxxx> escreveu:
>> Since this is for "figure" AND "image" (inline) I thought it is
>> better to replace. But I'am open to change this .. concrete ideas?
>
> I agree. IMHO, the best is to keep the existing tags, as it makes
> easy for people that read the ReST documentation. Of couse, in
> this case, it should keep supporting all options that exist
> for figure and image tags.
As I said in my other mail, I think shadowing the Sphinx directives can
be really confusing if we deviate at all. And by definition we do
deviate, because otherwise we'd just go with the original...
If we use "kernel-figure" or something like that, the users will look at
*our* documentation for it, and we can describe what it does under the
hood. If we shadow the original, how are users supposed to know to look
for documentation in the kernel tree for the extension?
Also, if we use our own directive, we don't have to go out of our way to
remain compatible with the original, and we can add our own options as
we see fit.
>> This patch applies to the reading-phase, where it is not clear if you
>> build HTML or LaTeX output. Think about the environment with the parsed
>> doctrees, which is build up in this phase and (re-)used for any output.
>
> Isn't there any variable visible by a reader extension or by conf.py
> telling the type of output or getting the command line used when
> sphinx-build is called?
Might be hard from caching POV if readers worked differently for
different builders. I don't know if there's a way for readers to note a
dependency on the builder changing.
>> >> +
>> >> +convert_exists = cmd_exists('convert')
>> >> +dot_exists = cmd_exists('dot')
>> >
>> >> +def setup(app): # pylint: disable=W0613
>> >> + directives.register_directive('figure', Figure)
>> >> + directives.register_directive('image', Image)
>> >> +
>> >> +def asterix_conversions(folder, node):
>> >
>> > "Asterix" is an indomitable Gaul; "asterisk" is "*" :) But again, I'm
>> > not convinced we need this step at all.
>> >
>>
>> OMG :-)
>
> If we remove support for *, then the patch would need to touch the
> files under media, as they currently relies on it.
>
> I would prefer if the extension keeps supporting it, even if we
> decide to use the file extension directly at the figure/image
> directives.
I don't understand. Please elaborate.
BR,
Jani.
--
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
