[dpdk-dev] [PATCH 09/11] doc: refresh headers list

[Mcnamara, John]

> -----Original Message-----
> From: David Marchand [mailto:david.marchand at 6wind.com]
> Sent: Saturday, January 16, 2016 3:11 PM
> To: Mcnamara, John
> Cc: dev at dpdk.org; Thomas Monjalon
> Subject: Re: [dpdk-dev] [PATCH 09/11] doc: refresh headers list
> 
> Hello John,
> 
> On Tue, Jan 12, 2016 at 3:06 PM, Mcnamara, John <john.mcnamara at intel.com>
> wrote:
> >> -----Original Message-----
> >> From: dev [mailto:dev-bounces at dpdk.org] On Behalf Of David Marchand
> >> Sent: Sunday, January 10, 2016 12:51 PM
> >> To: dev at dpdk.org
> >> Cc: thomas.monjalon at dpdk.org
> >> Subject: [dpdk-dev] [PATCH 09/11] doc: refresh headers list
> >>
> >> Since we are going to remove a header in next commit, let's first
> >> refresh documentation.
> >
> > I don't like these parts of the docs that list files since they go out
> > of date quite easily and, in general, the same information can be
> > conveyed by just listing the directories. (That isn't future-proof
> > either but it should be less subject to change.)
> 
> Well, we could imagine something automatic (in the build process), but I
> agree that the quickest solution is to get rid of it.
> 
> >
> > In this case you could just remove everything in the console section
> > after the output from "ls x86_64-native-linuxapp-gcc" like this:
> >
> >
> > Each build directory contains include files, libraries, and applications
> like the following::
> >
> >     $ ls
> >     app                       tools
> >     config                    MAINTAINERS
> >     Makefile                  GNUmakefile
> >     drivers                   mk
> >     examples                  pkg
> >     doc                       README
> >     lib                       scripts
> >     LICENSE.GPL               LICENSE.LGPL
> >     i686-native-linuxapp-gcc  x86_64-native-linuxapp-gcc
> >     i686-native-linuxapp-icc  x86_64-native-linuxapp-icc
> >
> >     $ ls x86_64-native-linuxapp-gcc
> >     app  build  include  kmod  lib  Makefile
> >
> 
> Well, from my pov, it is the same issue here.
> How about just removing all those files listings ?
> I am not sure they really help.

Hi,

I'm fine with that. I don't think the file listing adds much information to the previous paragraph. 

Or we could just add text that leaves out some of the information
so that the reader doesn’t expect an exact representation and isn't
confused when their file structure doesn't match. Something like:

    $ ls
    ...
    app
    config
    doc
    drivers
    examples
    lib
    ...
    i686-native-linuxapp-gcc  
    i686-native-linuxapp-icc  
    x86_64-native-linuxapp-gcc
    x86_64-native-linuxapp-icc
    ...

John.
--