Em Mon, 28 Nov 2016 12:02:43 +0200
Jani Nikula <jani.nikula@xxxxxxxxx> escreveu:
> 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...
Well, we're deviating just because we're fixing SVG support and adding
DOT format. So, IMHO, it would be ok to shadow them.
However, if we also deviate in syntax, then it is better to use
a different name for the tags, and override the existing ones
to produce a warning if used.
> 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.
Good point.
> >> 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.
Yeah, caching could be an issue, depending on how sphinx implements it.
If the script is allowed to do something with regards to cache, this could
be addressed inside the script, although would make it more complex.
>
> >> >> +
> >> >> +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.
I'm meant to say that, if we override image/figure, we can't remove
support for .*, as it would break midia figures, that relies on
that, as they all use:
.. figure:: dvbstb.*
If we use a different tag, it is OK to not support .*
Thanks,
Mauro
--
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
