From mboxrd@z Thu Jan 1 00:00:00 1970 From: Thomas Monjalon Subject: Re: [RFC PATCH 3/4] doc: nics guide Date: Mon, 02 Feb 2015 18:38:16 +0100 Message-ID: <1500004.RM7mZx5SlJ@xps13> References: <1422747307-13792-1-git-send-email-thomas.monjalon@6wind.com> <1678582.gq5SofjDC3@xps13> <8CEF83825BEC744B83065625E567D7C2049DCD83@IRSMSX108.ger.corp.intel.com> Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7Bit Cc: dev-VfR2kkLFssw@public.gmane.org To: "Iremonger, Bernard" Return-path: In-Reply-To: <8CEF83825BEC744B83065625E567D7C2049DCD83-kPTMFJFq+rEMvF1YICWikbfspsVTdybXVpNB7YpNyf8@public.gmane.org> List-Id: patches and discussions about DPDK List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces-VfR2kkLFssw@public.gmane.org Sender: "dev" 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 ` > > > > > > > > > > > > -:ref:`Figure 10. Virtualization for a Single Port NIC in SR-IOV > > > > > > Mode ` > > > > > > - > > > > > > -:ref:`Figure 11. Performance Benchmark Setup ` > > > > > > - > > > > > > -:ref:`Figure 12. Fast Host-based Packet Processing > > > > > > ` > > > > > > - > > > > > > -:ref:`Figure 13. Inter-VM Communication ` > > > > > > - > > > > > > -:ref:`Figure 14. Host2VM Communication Example Using kni vhost > > > > > > Back End ` > > > > > > - > > > > > > -:ref:`Figure 15. Host2VM Communication Example Using qemu vhost > > > > > > Back End ` > > > > > > - > > > > > > :ref:`Figure 16. Memory Sharing inthe Intel(r) DPDK > > > > > > Multi-process Sample Application ` > > > > > > > > > > > > :ref:`Figure 17. Components of an Intel(r) DPDK KNI Application > > > > > > ` 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 ` 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