Re: Script to build the media documentation as if it were a single book

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

Em Thu, 16 Apr 2020 10:06:28 +0200
Hans Verkuil <hverkuil@xs4all.nl> escreveu:

> On 16/04/2020 09:55, Mauro Carvalho Chehab wrote:
> > Em Thu, 16 Apr 2020 09:29:45 +0200
> > Hans Verkuil <hverkuil@xs4all.nl> escreveu:
> >   
> >> On 16/04/2020 09:21, Mauro Carvalho Chehab wrote:  
> >>> Em Thu, 16 Apr 2020 09:01:55 +0200
> >>> Hans Verkuil <hverkuil@xs4all.nl> escreveu:
> >>>     
> >>>> On 14/04/2020 15:37, Mauro Carvalho Chehab wrote:    
> >>>     
> >>>>> ================================
> >>>>> Linux Kernel Media Documentation
> >>>>> ================================
> >>>>>
> >>>>> .. toctree::
> >>>>> 	:maxdepth: 4
> >>>>>
> >>>>>         admin-guide/index
> >>>>>         driver-api/index
> >>>>>         userspace-api/index      
> >>>>
> >>>> Wouldn't it make more sense to have the userspace-api before the admin-guide?    
> >>>
> >>> There, I just placed them on alphabetic order.
> >>>
> >>> But answering your question, that depends on the audience ;-)
> >>>
> >>> -
> >>>
> >>> Yet, assuming that we are doing a good job, I would expect a lot more
> >>> users than developers[1].    
> >>
> >> If you want to see what it looks like with userspace-api on top:
> >>
> >> https://hverkuil.home.xs4all.nl/spec/index.html
> >>
> >> I think it makes more sense that way.  
> > 
> > With the current content, I fully agree with you. However, take a look
> > at the RFC patch I just sent. It is just the start of something
> > (and it is not aligned yet with the latest Kconfig changes).
> > 
> > Anyway, my plan is to add something that a random media user could
> > find some useful information, and point to our Wiki pages where
> > it would make sense.  
> 
> But that's only useful for people who need to build their own kernel or do
> other admin tasks. That's a small group and it is usually a one-off thing.

Well, all Kernel developers need that. Also userspace developers that
may want to build test drivers. So, the ones potentially interested
on this chapter contains the group of people interested at the public
API.

Granted, once some Kernel developer gets familiar with the stuff 
contained there, the uAPI guide becomes a lot more interesting, but
this is true for any technical book:

at the beginning, the introductory chapters (with don't have much
details) are the more relevant ones, as they explain the basic concepts
that will be present at the rest of the book. Once you pass that, the
other chapters will be a lot more interesting, and those are the ones 
that people re-visit more often.

> 
> The vast majority is interested in the public APIs.
> 
> Regards,
> 
> 	Hans
> 
> >   
> >>
> >> Regards,
> >>
> >> 	Hans
> >>  
> >>>
> >>> [1] Granted, there are lots of gaps there for it to be a generic guide
> >>>     to media subsystem. I'm planning to improve the admin-guide in order
> >>>     to make it more consistent and useful for media users.
> >>>
> >>> The order there, IMHO, doesn't matter much, as someone accessing it from
> >>> LinuxTV.org would likely use this URL:
> >>>
> >>> 	https://linuxtv.org/docs.php
> >>>
> >>> Side note: I need to add a pointer to the admin guide there - and at the
> >>> wiki pages.
> >>>
> >>> Thanks,
> >>> Mauro
> >>>     
> >>  
> > 
> > 
> > 
> > Thanks,
> > Mauro
> >   
> 



Thanks,
Mauro