Re: V4L2 spec

[wk <handygewinnspiel@gmx.de>]

Mauro Carvalho Chehab schrieb:
> On Mon, 09 Mar 2009 19:46:34 -0400
> Andy Walls <awalls@radix.net> wrote:
>
>   
>>> and integrating it into the existing v4l docbook,  
>>>       
>> I'm not sure of the value in that.
>>     
>
> The DVB conversion to docbook allows us to add it at the kernel docbook docs
> (probably, not the entire doc, but the parts that describe the internal kernel
> API).
>
>   
>> <opinion>
>> Implmenting something to multiple (or multi-volume) specifications is
>> indeed a pain, but it makes documentation maintenance easier as the task
>> is easily divided along areas of personnel expertise.  Assuming the rate
>> of documentation maintencance does not rapidly increase, keeping
>> documentation maintenace simple is paramount.
>>     
>
> If you take a look on V4L docbooks, it is divided into multiple volume files:
>
> biblio.sgml          pixfmt-nv16.sgml                 vidioc-enumstd.sgml
> common.sgml          pixfmt-packed-rgb.sgml           vidioc-g-audioout.sgml
> compat.sgml          pixfmt-packed-yuv.sgml           vidioc-g-audio.sgml
> controls.sgml        pixfmt-sbggr16.sgml              vidioc-g-crop.sgml
> dev-capture.sgml     pixfmt-sbggr8.sgml               vidioc-g-ctrl.sgml
> dev-codec.sgml       pixfmt-sgbrg8.sgml               vidioc-g-enc-index.sgml
> ...
>
> If we merge DVB there, for sure we should break it into some files, and maybe
> even having they on separate directories.
>
>   
>> Also multiple specifcations (or volumes) clearly group requirements into
>> large chunks of "I don't care about that volume" and "I do care about
>> this volume".  Combining the V4L2 and DVB spec into one volume would
>> probably be a strategic error for some tactical advantage in dealing
>> with hybrid devices.
>>     
>
> This is a good point. 
>
> On my opinion, it seems good to merge the docs. This is just my 2 cents.
>
> If we merge both, IMO, we should break the doc into two parts, being one for
> analog and another for digital, with an introductory text with the hybrid
> devices glue.
>
> If we decide not to merge, we can at least try to follow the same model on both
> documents, and link a common sgml introductory text for hybrid devices to be
> added on both documents.
>
>
>   
>> </opinion>
>>     
>
>
> Cheers,
> Mauro
>
>   
What about a two step aproach for each chapter?

- doing work on *contents* with developers inside linuxtv dvb wiki on 
standard wiki page
- convert wiki text to docbook (textformatting stuff) by someone else.

By doing so, the work load would be split into two independend topics, 
work on contents in wiki and afterwards textformatting of that agreed 
contents without help of developers afterwards and supplying to ML as patch.
If we would do so, one would prepare a wiki page with the actual 
contents of one chapter of the current api and set a deadline for 
editing that page.
Developers should edit contents (easy and fast on wiki) until deadline. 
It would improve greatly the speed of that work.

Keeping the logical structure of the document would also allow to have 
the "I don't care about that volume" feature as well to merge the 
decoder of the FF cards into V4l2 mpeg decoder section.

Introduction
        What you need to know (remove)
        History (as short as possible)
        Overview
        Linux DVB Devices
        API include files
DVB Frontend API (add a lot of missing stuff here.)
        Frontend Data Types
        Frontend Function Calls
DVB Demux Device
        Demux Data Types
        Demux Function Calls
DVB Video Device (merge with v4l2 mpeg decoders)
DVB Audio Device (merge with v4l2 mpeg decoders)
DVB CA Device
        CA Data Types
DVB Network API
        DVB Net Data Types
Kernel Demux API
       Kernel Demux Data Types
       Demux Directory API
        Demux API
        Demux Callback API
        TS Feed API
        Section Feed API
Examples

--Winfried