Re: [dpdk-dev] [PATCH v2 0/3] split programmers guide a bit

["Mcnamara, John" <john.mcnamara@intel.com>]

> -----Original Message-----
> From: Iremonger, Bernard
> Sent: Wednesday, April 1, 2015 10:19 AM
> To: Thomas Monjalon; Mcnamara, John
> Cc: Butler, Siobhan A; dev@dpdk.org
> Subject: RE: [dpdk-dev] [PATCH v2 0/3] split programmers guide a bit
> >
> > 2015-03-31 11:34, Mcnamara, John:
> > > Any objection to an additional patch to move the figure captions
> > > below the figures in the docs?
> >
> > No objection.
> > We should use figure:: keyword instead of image:: to add a caption.
> >
> > > The caption above the figure was the format used in the initial
> > > docs, and it looks okay in the HTML output, but in the PDF output it
> > > tends to get merged into the preceding paragraph and isn't always on
> > > the same page as the figure.
> >
> > Yes, it's a bit strange.
> > Why moving it below will ensure to keep it in the same page?
> > I think figure:: keyword may solve it.
> 
> Hi John,
> 
> My preference would be to keep the caption above the figure.
> This was the way it was done in the original 1.7 MSword documents (the
> starting point for the conversion to rst files).

Hi Bernard,

I don't mind the caption above. I'm mainly concerned with it staying with the image.

To do this we need to use the figure:: keyword as Thomas suggested. However, there are some knock on effects from this.

* As far as I can see, we can't just replace with image:: with figure:: in the |image-name| substitution definitions since Sphinx or RST doesn't support it.
* This means that the |image-name| substitutions will have to change back to explicit .. figure:: declarations. Not a big deal.
* The captions have to be under the image. I don't see a way to configure it to be on top. It may be possible in LaTex but not in Html.
* We should also modify the table captions in the same way.

So at this point I'm sorry I brought it up. I can post a programmatically generated patch as an RFC if there is interest in seeing what the updated output would look like.

The main positive is that it would give us automatic* figure/table numbering in Html and PDF and the captioning looks quite good. (*This requires Sphinx 1.3).

John