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

["Burakov, Anatoly" <anatoly.burakov@intel.com>]

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.burakov@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