[dpdk-dev] [PATCH v2 0/3] split programmers guide a bit
> -Original Message- > From: Thomas Monjalon [mailto:thomas.monjalon at 6wind.com] > Sent: Tuesday, March 31, 2015 1:23 PM > To: Mcnamara, John > Cc: Butler, Siobhan A; Iremonger, Bernard; dev at 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). Regards, Bernard
[dpdk-dev] [PATCH v2 0/3] split programmers guide a bit
> -Original Message- > From: Iremonger, Bernard > Sent: Wednesday, April 1, 2015 10:19 AM > To: Thomas Monjalon; Mcnamara, John > Cc: Butler, Siobhan A; dev at 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
[dpdk-dev] [PATCH v2 0/3] split programmers guide a bit
> -Original Message- > From: Mcnamara, John > Sent: Wednesday, April 1, 2015 5:37 PM > To: Iremonger, Bernard; Thomas Monjalon > Cc: Butler, Siobhan A; dev at dpdk.org > Subject: RE: [dpdk-dev] [PATCH v2 0/3] split programmers guide a bit > > > -Original Message- > > From: Iremonger, Bernard > > Sent: Wednesday, April 1, 2015 10:19 AM > > To: Thomas Monjalon; Mcnamara, John > > Cc: Butler, Siobhan A; dev at 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 > Hi John, I am not sure why the captions have to be under the images. At present the captions are just a bold line of text before the image in the rst files for example, **Figure 17. Components of a DPDK KNI Application** This will probably affect the cross reference links as well or does the automatic numbering work with the links as well. Regards, Bernard
[dpdk-dev] [PATCH v2 0/3] split programmers guide a bit
> -Original Message- > From: Iremonger, Bernard > Sent: Wednesday, April 1, 2015 6:20 PM > To: Mcnamara, John; Thomas Monjalon > Cc: Butler, Siobhan A; dev at dpdk.org > Subject: RE: [dpdk-dev] [PATCH v2 0/3] split programmers guide a bit > > 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 > > > Hi John, > > I am not sure why the captions have to be under the images. > At present the captions are just a bold line of text before the image in > the rst files for example, **Figure 17. Components of a DPDK KNI > Application** Hi Bernard, The issue with the current solution is that the caption isn't tied to the image in any way and the pdf formatter frequently puts it on a separate page. Unfortunately, the solution to that issue, to use figure:: instead of image::, doesn't support captions above the image. If it did I would be happy to leave the placement as it is. > This will probably affect the cross reference links as well or does the > automatic numbering work with the links as well. The automatic numbering can be added to the cross references as well. I'll submit an RFC patch and you can try it out and see if it is worth changing. John
[dpdk-dev] [PATCH v2 0/3] split programmers guide a bit
Too many things are included in the programmers guide.
I think it should cover only API and knowledge needed to make an application.
That's why I suggest to move Xen and NICs doc outside.
Then it will be easier to add doc for a new environment or a new NIC.
Note that drivers or device-related libs like KNI, vhost or bonding stay
in the programmer's guide because they are more high-level than NICs drivers.
Changes in v2:
- create index for Xen guide
- rename figure links
- rebase with mlx4
- HTML copyright removal has been sent separately
Thomas Monjalon (3):
doc: fix file attributes
doc: move Xen guide out of programmers guide
doc: nics guide
MAINTAINERS| 17 +-
doc/guides/index.rst | 2 +
.../driver_vm_emul_dev.rst => nics/e1000em.rst}| 0
doc/guides/{prog_guide => nics}/img/console.png| Bin
.../{prog_guide => nics}/img/fast_pkt_proc.png | Bin
.../{prog_guide => nics}/img/forward_stats.png | Bin
.../{prog_guide => nics}/img/host_vm_comms.png | Bin
.../img/host_vm_comms_qemu.png | Bin
.../{prog_guide => nics}/img/inter_vm_comms.png| Bin
.../{prog_guide => nics}/img/perf_benchmark.png| Bin
.../{prog_guide => nics}/img/single_port_nic.png | Bin
.../{prog_guide => nics}/img/vm_vm_comms.png | Bin
.../{prog_guide => nics}/img/vmxnet3_int.png | Bin
doc/guides/{prog_guide => nics}/img/vswitch_vm.png | Bin
doc/guides/{ => nics}/index.rst| 28 ++--
.../intel_vf.rst} | 8 +-
doc/guides/nics/ixgbe.rst | 184 +
.../mlx4_poll_mode_drv.rst => nics/mlx4.rst} | 0
.../pcap_ring.rst} | 0
.../virtio.rst}| 4 +-
.../vmxnet3.rst} | 0
doc/guides/prog_guide/index.rst| 18 --
doc/guides/prog_guide/poll_mode_drv.rst| 152 -
.../img/dpdk_xen_pkt_switch.png| Bin
doc/guides/{prog_guide => xen}/img/grant_refs.png | Bin
doc/guides/{prog_guide => xen}/img/grant_table.png | Bin
doc/guides/{ => xen}/index.rst | 21 +--
.../pkt_switch.rst}| 0
28 files changed, 228 insertions(+), 206 deletions(-)
rename doc/guides/{prog_guide/driver_vm_emul_dev.rst => nics/e1000em.rst}
(100%)
rename doc/guides/{prog_guide => nics}/img/console.png (100%)
rename doc/guides/{prog_guide => nics}/img/fast_pkt_proc.png (100%)
rename doc/guides/{prog_guide => nics}/img/forward_stats.png (100%)
rename doc/guides/{prog_guide => nics}/img/host_vm_comms.png (100%)
rename doc/guides/{prog_guide => nics}/img/host_vm_comms_qemu.png (100%)
rename doc/guides/{prog_guide => nics}/img/inter_vm_comms.png (100%)
rename doc/guides/{prog_guide => nics}/img/perf_benchmark.png (100%)
rename doc/guides/{prog_guide => nics}/img/single_port_nic.png (100%)
rename doc/guides/{prog_guide => nics}/img/vm_vm_comms.png (100%)
rename doc/guides/{prog_guide => nics}/img/vmxnet3_int.png (100%)
rename doc/guides/{prog_guide => nics}/img/vswitch_vm.png (100%)
copy doc/guides/{ => nics}/index.rst (88%)
rename doc/guides/{prog_guide/i40e_ixgbe_igb_virt_func_drv.rst =>
nics/intel_vf.rst} (99%)
mode change 100755 => 100644
create mode 100644 doc/guides/nics/ixgbe.rst
rename doc/guides/{prog_guide/mlx4_poll_mode_drv.rst => nics/mlx4.rst} (100%)
rename doc/guides/{prog_guide/libpcap_ring_based_poll_mode_drv.rst =>
nics/pcap_ring.rst} (100%)
rename doc/guides/{prog_guide/poll_mode_drv_emulated_virtio_nic.rst =>
nics/virtio.rst} (99%)
rename doc/guides/{prog_guide/poll_mode_drv_paravirtual_vmxnets_nic.rst =>
nics/vmxnet3.rst} (100%)
mode change 100755 => 100644 doc/guides/prog_guide/poll_mode_drv.rst
rename doc/guides/{prog_guide => xen}/img/dpdk_xen_pkt_switch.png (100%)
rename doc/guides/{prog_guide => xen}/img/grant_refs.png (100%)
rename doc/guides/{prog_guide => xen}/img/grant_table.png (100%)
copy doc/guides/{ => xen}/index.rst (88%)
rename doc/guides/{prog_guide/intel_dpdk_xen_based_packet_switch_sol.rst =>
xen/pkt_switch.rst} (100%)
--
2.2.2
[dpdk-dev] [PATCH v2 0/3] split programmers guide a bit
2015-03-19 17:48, Thomas Monjalon: > Too many things are included in the programmers guide. > I think it should cover only API and knowledge needed to make an application. > That's why I suggest to move Xen and NICs doc outside. > Then it will be easier to add doc for a new environment or a new NIC. > Note that drivers or device-related libs like KNI, vhost or bonding stay > in the programmer's guide because they are more high-level than NICs drivers. > > Changes in v2: > - create index for Xen guide > - rename figure links > - rebase with mlx4 > - HTML copyright removal has been sent separately > > Thomas Monjalon (3): > doc: fix file attributes > doc: move Xen guide out of programmers guide > doc: nics guide Applied with figures list restored on Bernard's request.
[dpdk-dev] [PATCH v2 0/3] split programmers guide a bit
> -Original Message- > From: dev [mailto:dev-bounces at dpdk.org] On Behalf Of Thomas Monjalon > Sent: Tuesday, March 31, 2015 12:38 AM > To: Butler, Siobhan A > Cc: dev at dpdk.org > Subject: Re: [dpdk-dev] [PATCH v2 0/3] split programmers guide a bit > > 2015-03-19 17:48, Thomas Monjalon: > > Too many things are included in the programmers guide. > > I think it should cover only API and knowledge needed to make an > application. > > That's why I suggest to move Xen and NICs doc outside. > > Then it will be easier to add doc for a new environment or a new NIC. > > Note that drivers or device-related libs like KNI, vhost or bonding > > stay in the programmer's guide because they are more high-level than > NICs drivers. > > > > Changes in v2: > > - create index for Xen guide > > - rename figure links > > - rebase with mlx4 > > - HTML copyright removal has been sent separately > > > > Thomas Monjalon (3): > > doc: fix file attributes > > doc: move Xen guide out of programmers guide > > doc: nics guide > > Applied with figures list restored on Bernard's request. Hi, Any objection to an additional patch to move the figure captions below the figures in the docs? 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. John
[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.
