Re: [dpdk-dev] [PATCH] doc: document all EAL parameters in one place

[Burakov, Anatoly]

On 16-Nov-18 4:52 PM, Anatoly Burakov wrote:
Currently, the most complete (but still incomplete) user guide for
EAL command-line parameters resides in user guide for testpmd.
This is wrong on multiple levels, and should not be the case.
To fix it, we have to create a document that lists all supported
EAL command-line arguments. However, because different platforms
support different subsets of available EAL parameters, instead of
creating a single file, we will create a common file in
doc/guides/common containing documentation for EAL parameters
that are supported on all of our supported platforms (Linux and
FreeBSD at the time of this writing).

We will then include this document in the Getting Started guides
for all supported platforms, so that any changes made to
documentation for commonly supported EAL parameters will be
reflected in Getting Started guides for all platforms.

This patch also removes EAL parameters documentation from the
testpmd user guide, and instead adds references to the newly
created documents in both testpmd user guides and in sample
applications guide.

Signed-off-by: Anatoly Burakov <anatoly.bura...@intel.com>
---

Notes:
     Here, "supported" is defined not as "doesn't produce error
     on a particular platform, but rather is defined as "actually
     works according to current codebase". All command-line
     options have been traced through code to determine whether
     they actually do anything.
     
     As a result, even though some command-line options (such as
     "--vmware-tsc-map") are handled in eal_common_options (and
     thus are supposed to be supported on all platforms), they
     are nevertheless marked as Linux-specific. I believe this
     is a good standard to follow.
     
     It would also be good to include links to relevant PG
     sections for each parameters, but that can be done in
     the future. This is a good enough start, i think.
     
     Also, currently, this breaks our pdf doc build because
     i've added a "common" directory, and our PDF generator
     expects an index.rst to be in there, even though this
     directory is not supposed to be an actual document. I
     would kindly request community's advice on how to best
     resolve this situation.
     
     Things that i can think of myself:
     - Put the common EAL flags somewhere in the existing
       directories (we don't have anything appropriate for
       that, but the last resolt would be something like
       Linux GSG directory)
     - Hack our build system to not create a "common" PDF
       file and skip this directory altogether
     - Put this file outside of doc/guides (doc/common?)


The above problem with pdf doc build still exists and needs to be solved 
before this patch is integrated. Unfortunately, my LaTeX-fu is lacking, 
so i'd really like some help here :)

--
Thanks,
Anatoly