Re: [PATCH v3 5/7] docs-rst: media: Sort topic list alphabetically

[Mauro Carvalho Chehab <mchehab@s-opensource.com>]

Em Mon, 10 Apr 2017 16:02:54 +0300
Sakari Ailus <sakari.ailus@linux.intel.com> escreveu:

> Bring some order by alphabetically ordering the list of topics.
> 
> Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>
> ---
>  Documentation/media/kapi/v4l2-core.rst | 18 +++++++++---------
>  1 file changed, 9 insertions(+), 9 deletions(-)
> 
> diff --git a/Documentation/media/kapi/v4l2-core.rst b/Documentation/media/kapi/v4l2-core.rst
> index d8f6c46..2fbf532 100644
> --- a/Documentation/media/kapi/v4l2-core.rst
> +++ b/Documentation/media/kapi/v4l2-core.rst
> @@ -4,23 +4,23 @@ Video4Linux devices
>  .. toctree::
>      :maxdepth: 1
>  
> -    v4l2-intro

NACK.

The order of the documentation should match what makes sense for the
user that will be reading the docs, and *not* an alphabetical order. 

I didn't check what order you did, but for sure the introduction should 
come first, and then the stuff that all drivers use, like
v4l2-dev, v4l2-device and v4l2-fh. Then, other stuff that it is part of
the framework but are used only by a subset of the drivers.

That's said, it probably makes sense to use multiple toctrees here, and
add some description before each of them, in order to better organize
its contents. Something similar to what it was done with
	Documentation/admin-guide/index.rst

I'll rebase patch 6/7 to not depend on this one.


Regards

Thanks,
Mauro