Re: [RFC PATCH 3/4] doc: nics guide

[Thomas Monjalon <thomas.monjalon-pdR9zngts4EAvxtiuMwx3w@public.gmane.org>]

2015-02-02 17:33, Iremonger, Bernard:
> From: Thomas Monjalon [mailto:thomas.monjalon-pdR9zngts4EAvxtiuMwx3w@public.gmane.org]
> > 2015-02-02 14:59, Iremonger, Bernard:
> > > > 2015-02-02 14:11, Iremonger, Bernard:
> > > > > > --- a/doc/guides/prog_guide/index.rst
> > > > > > +++ b/doc/guides/prog_guide/index.rst
> > > > > > @@ -101,18 +96,6 @@ Programmer's Guide
> > > > > >
> > > > > >  :ref:`Figure 9. An mbuf with Three Segments <pg_figure_9>`
> > > > > >
> > > > > > -:ref:`Figure 10. Virtualization for a Single Port NIC in SR-IOV
> > > > > > Mode <pg_figure_10>`
> > > > > > -
> > > > > > -:ref:`Figure 11. Performance Benchmark Setup <pg_figure_11>`
> > > > > > -
> > > > > > -:ref:`Figure 12. Fast Host-based Packet Processing
> > > > > > <pg_figure_12>`
> > > > > > -
> > > > > > -:ref:`Figure 13. Inter-VM Communication <pg_figure_13>`
> > > > > > -
> > > > > > -:ref:`Figure 14. Host2VM Communication Example Using kni vhost
> > > > > > Back End <pg_figure_14>`
> > > > > > -
> > > > > > -:ref:`Figure 15. Host2VM Communication Example Using qemu vhost
> > > > > > Back End <pg_figure_15>`
> > > > > > -
> > > > > >  :ref:`Figure 16. Memory Sharing inthe Intel(r) DPDK
> > > > > > Multi-process Sample Application <pg_figure_16>`
> > > > > >
> > > > > >  :ref:`Figure 17. Components of an Intel(r) DPDK KNI Application
> > > > > > <pg_figure_17>` diff --git
> > > > >
> > > > > References to Figures 9 to 17 have been removed have they been reinstated somewhere else ?
> > > >
> > > > Figures 10 to 15 moved in doc/guides/nics/img.
> > > >
> > > > I didn't re-create the references in doc/guides/nics/index.rst nor
> > > > renumbered the ones in doc/guides/prog_guide/index.rst.
> > >
> > > It would be better to recreate the references  in  doc/guides/nics/index.rst rather than just delete them.
> > > I don't think there is any need to renumber them.
> > > The references are global across documents and must be unique.
> > 
> > No the references are not really uniques:
> > 	- Figures in doc/guides/sample_app_ug/index.rst start from 1 to 17.
> > 	- Figures in doc/guides/prog_guide/index.rst start from 1 to 39.
> > When adding a new new figure in a document, we must renumber them.
> 
> I had this problem before with duplicate numbers, so in the prog_guide I prefixed the links with "pg_" so the links are unique.
> For example:
>  :ref:`Figure 16. Memory Sharing inthe Intel(r) DPDK Multi-process Sample Application <pg_figure_16>` 

OK I understand what is unique.
But I still think that the number in "Figure 16." should be automatically generated.
Or we can remove this Figure/Table list at the bottom of the index.

> > > > I think these manual numberings should be removed as it is a pain to update.
> > > > Actually I don't really understand what is the usage of such references.
> > > > So I suggest to completely remove them or generate them with a script.
> > >
> > > These references were in the original 1.7 MSWord docs.
> > > When reading a document it enabled the reader to jump to another
> > > section and jump back, they worked in the HTML docs too.
> > > I think they should be retained.
> > 
> > Are you speaking about the figure references at the bottom of this page?
> > 	http://dpdk.org/doc/guides/prog_guide
> > It doesn't really help for browsing.
> 
> No, what I mean is that within a document you can jump to another section and back for example:
> 
> file:///home/bairemon/git_home/dpdk_master/build/doc/html/guides/prog_guide/mbuf_lib.html  
> There is link on this page that allows the reader to jump to Mempool Library
> file:///home/bairemon/git_home/dpdk_master/build/doc/html/guides/prog_guide/mempool_lib.html#mempool-library
> The reader can use the back arrow in the browser to return to the original page.
> All of the links are used for this purpose.

OK, it was a misunderstanding. I agree the cross references are useful.
I'm speaking only about the Figure/Table list at the bottom of the index.

-- 
Thomas