V4L2 spec

V4L2 spec

[Hans Verkuil]

Hi Mauro,

I noticed that there is an ancient V4L2 spec in our tree in the v4l/API 
directory. Is that spec used in any way? I don't think so, so I suggest 
that it is removed.

The V4L1 spec that is there should probably be moved to the v4l2-spec 
directory as that is where people would look for it. We can just keep it 
there for reference.

The documentation on www.linuxtv.org is also out of date. How are we going 
to update that?

I think that a good schedule would be right after a kernel merge window 
closes. The spec at that moment is the spec for that new kernel and that's 
a good moment to update the website.

The current spec is really old, though, and should be updated asap.

Note that the specs from the daily build are always available from 
www.xs4all.nl/~hverkuil/spec. I've modified the build to upload the 
dvbapi.pdf as well.

Regards,

	Hans

-- 
Hans Verkuil - video4linux developer - sponsored by TANDBERG

Re: V4L2 spec

[wk]

Hans Verkuil wrote:
> Hi Mauro,
>
> I noticed that there is an ancient V4L2 spec in our tree in the v4l/API 
> directory. Is that spec used in any way? I don't think so, so I suggest 
> that it is removed.
>
> The V4L1 spec that is there should probably be moved to the v4l2-spec 
> directory as that is where people would look for it. We can just keep it 
> there for reference.
>
> The documentation on www.linuxtv.org is also out of date. How are we going 
> to update that?
>
> I think that a good schedule would be right after a kernel merge window 
> closes. The spec at that moment is the spec for that new kernel and that's 
> a good moment to update the website.
>
> The current spec is really old, though, and should be updated asap.
>
> Note that the specs from the daily build are always available from 
> www.xs4all.nl/~hverkuil/spec. I've modified the build to upload the 
> dvbapi.pdf as well.
>
> Regards,
>
> 	Hans
>
>   

Wouldn't it make sense to merge both apis, v4l2 and dvb together?

- dvb api is completely outdated, would be good to be rewritten anyway.
- v4l2 and dvb share the same hg
- v4l2 and dvb share the same wiki
- a lot of developers are active in both topics
- any person interested in video and tv could be directed to the same file

Just some thoughts to the topic..

--Winfried

Re: V4L2 spec

[Mauro Carvalho Chehab]

On Fri, 6 Mar 2009, wk wrote:

> Hans Verkuil wrote:
>>  Hi Mauro,
>>
>>  I noticed that there is an ancient V4L2 spec in our tree in the v4l/API
>>  directory. Is that spec used in any way? I don't think so, so I suggest
>>  that it is removed.

OK.

>>  The V4L1 spec that is there should probably be moved to the v4l2-spec
>>  directory as that is where people would look for it. We can just keep it
>>  there for reference.

Nah. Let's just strip and point to some place where V4L1 doc is 
available, adding some warning that the API is outdated and will be 
removed from kernel soon.

>>  The documentation on www.linuxtv.org is also out of date. How are we going
>>  to update that?

Make a proposal. I'll then updade it acordingly.

>>  I think that a good schedule would be right after a kernel merge window
>>  closes. The spec at that moment is the spec for that new kernel and that's
>>  a good moment to update the website.
>>
>>  The current spec is really old, though, and should be updated asap.
>>
>>  Note that the specs from the daily build are always available from
>>  www.xs4all.nl/~hverkuil/spec. I've modified the build to upload the
>>  dvbapi.pdf as well.

Maybe we can add a script to daily update at linuxtv.org for the specs as
well.

> Wouldn't it make sense to merge both apis, v4l2 and dvb together?
>
> - dvb api is completely outdated, would be good to be rewritten anyway.
> - v4l2 and dvb share the same hg
> - v4l2 and dvb share the same wiki
> - a lot of developers are active in both topics
> - any person interested in video and tv could be directed to the same file
>
> Just some thoughts to the topic..

I think so. The better would be to convert DVB api to docbook (as used by 
all other kernel documents), and add a developers document for the kernel 
API for both at the kernel documentation structure).

However, this is a huge task that someone should volunteer for doing, 
otherwise, it won't happen.

Cheers,
Mauro

Re: V4L2 spec

[Hans Verkuil]

On Monday 09 March 2009 12:08:39 Mauro Carvalho Chehab wrote:
> On Fri, 6 Mar 2009, wk wrote:
> > Hans Verkuil wrote:
> >>  Hi Mauro,
> >>
> >>  I noticed that there is an ancient V4L2 spec in our tree in the
> >> v4l/API directory. Is that spec used in any way? I don't think so, so
> >> I suggest that it is removed.
>
> OK.
>
> >>  The V4L1 spec that is there should probably be moved to the v4l2-spec
> >>  directory as that is where people would look for it. We can just keep
> >> it there for reference.
>
> Nah. Let's just strip and point to some place where V4L1 doc is
> available, adding some warning that the API is outdated and will be
> removed from kernel soon.

I don't think we should remove the doc from the repo until all drivers are 
converted to v4l2.

> >>  The documentation on www.linuxtv.org is also out of date. How are we
> >> going to update that?
>
> Make a proposal. I'll then updade it acordingly.

Can you just update it with the latest version compiled from v4l-dvb?

> >>  I think that a good schedule would be right after a kernel merge
> >> window closes. The spec at that moment is the spec for that new kernel
> >> and that's a good moment to update the website.

Updating it whenever a merge window closes seems to make sense to me, so I 
propose that we do that.

> >>  The current spec is really old, though, and should be updated asap.
> >>
> >>  Note that the specs from the daily build are always available from
> >>  www.xs4all.nl/~hverkuil/spec. I've modified the build to upload the
> >>  dvbapi.pdf as well.
>
> Maybe we can add a script to daily update at linuxtv.org for the specs as
> well.

That would be a good plan.

Regards,

	Hans


> > Wouldn't it make sense to merge both apis, v4l2 and dvb together?
> >
> > - dvb api is completely outdated, would be good to be rewritten anyway.
> > - v4l2 and dvb share the same hg
> > - v4l2 and dvb share the same wiki
> > - a lot of developers are active in both topics
> > - any person interested in video and tv could be directed to the same
> > file
> >
> > Just some thoughts to the topic..
>
> I think so. The better would be to convert DVB api to docbook (as used by
> all other kernel documents), and add a developers document for the kernel
> API for both at the kernel documentation structure).
>
> However, this is a huge task that someone should volunteer for doing,
> otherwise, it won't happen.
>
> Cheers,
> Mauro



-- 
Hans Verkuil - video4linux developer - sponsored by TANDBERG

Re: V4L2 spec

[wk]

>
> I think so. The better would be to convert DVB api to docbook (as used 
> by all other kernel documents), and add a developers document for the 
> kernel API for both at the kernel documentation structure).
>
> However, this is a huge task that someone should volunteer for doing, 
> otherwise, it won't happen.
>
> Cheers,
> Mauro
>
Sorry Mauro,

but i disagree with you.

Its a bad idea to expect someone else, the magic volunteer, doing work 
with *deep impact* on the dvb driver API structure or documentation.
Working on this topic determines complete usability of the driver, so 
MAIN DEVELOPERS have to REVIEW and CONTRIBUTE.
If they think, that they cannot do such work in parallel, they should to 
stop work on drivers for some time.

Status from application side of view at the moment: *not usable* without 
re-inventing the wheel.

The very same with the structures in frontend.h, a lot of things are not 
understandable. I give you some examples (i could give more...):

-  TRANSMISSION_MODE_4K is missing, but still mentioned in 300468 
v.1.9.1  "6.2.13.4 Terrestrial delivery system descriptor"
-  the same for BANDWIDTH_5_MHZ, also 300468 v.1.9.1  "6.2.13.4 
Terrestrial delivery system descriptor"
-  POLARIZATION for QPSK frontends  is nowhere defined in frontend.h at 
all, forcing applications to do its own definitions,
     "6.2.13.2 Satellite delivery system descriptor" gives clear 
definitions - so why are they not defined in frontend.h?
-  ATSC frontends are mixed cable and terrestrian, whereas older DVB-C 
and DVB-T are *strictly* separated
-  struct dvb_qpsk_parameters is missing (at least!) to be usable again
    * fe_modulation_t
    * fe_pilot_t
    * fe_rolloff_t
    * fe_delivery_system_t
    * west_east_flag
    * scrambling_sequence_selector
    * multiple_input_stream_flag

- nearly the same for dvb_qam_parameters, dvb_ofdm_parameters, 
dvb_atsc_parameters..., at least delivery_system needs to be here

Working on documentation would fix *all* of this problems.

Regards,
Winfried

Re: V4L2 spec

[Devin Heitmueller]

On Mon, Mar 9, 2009 at 6:03 PM, wk <handygewinnspiel@gmx.de> wrote:
> Its a bad idea to expect someone else, the magic volunteer, doing work with
> *deep impact* on the dvb driver API structure or documentation.
> Working on this topic determines complete usability of the driver, so MAIN
> DEVELOPERS have to REVIEW and CONTRIBUTE.
> If they think, that they cannot do such work in parallel, they should to
> stop work on drivers for some time.

Cut me a $25,000 check and I'll happily do it.  Otherwise, don't tell
a bunch of volunteer developers how they should be spending their
time.  What you happen to think is the important is not necessarily
what developers feel is the most valuable use of their time.

The reality is that there is *some* value a developer can contribute
in reviewing the content and providing feedback and a *TON* of grunt
work involved that can be done by anybody who takes the time to learn
docbook.  If someone wants to volunteer to do the former, I'm sure
some developers would be willing to do the latter.

Devin

-- 
Devin J. Heitmueller
http://www.devinheitmueller.com
AIM: devinheitmueller

Re: V4L2 spec

[Hans Verkuil]

On Monday 09 March 2009 23:10:56 Devin Heitmueller wrote:
> On Mon, Mar 9, 2009 at 6:03 PM, wk <handygewinnspiel@gmx.de> wrote:
> > Its a bad idea to expect someone else, the magic volunteer, doing work
> > with *deep impact* on the dvb driver API structure or documentation.
> > Working on this topic determines complete usability of the driver, so
> > MAIN DEVELOPERS have to REVIEW and CONTRIBUTE.
> > If they think, that they cannot do such work in parallel, they should
> > to stop work on drivers for some time.
>
> Cut me a $25,000 check and I'll happily do it.  Otherwise, don't tell
> a bunch of volunteer developers how they should be spending their
> time.  What you happen to think is the important is not necessarily
> what developers feel is the most valuable use of their time.

Hear, hear.

> The reality is that there is *some* value a developer can contribute
> in reviewing the content and providing feedback and a *TON* of grunt
> work involved that can be done by anybody who takes the time to learn
> docbook.  If someone wants to volunteer to do the former, I'm sure
> some developers would be willing to do the latter.

Indeed. If someone could do the 'grunt' work of converting the dvb doc into 
DocBook and integrating it into the existing v4l docbook, then that will no 
doubt get a flow of patches and gradual improvements started from the main 
developers. In addition, simply asking them to clarify bits of the 
documentation will generally result in answers and you can then put that 
into the doc.

None of this requires in-depth knowledge, but only motivation and the time 
to do this work.

You can probably partially automate the conversion with some homebrewn 
one-off perl scripts (or whatever your favorite script language is). But 
it's still a lot of manual labor.

Regards,

	Hans

-- 
Hans Verkuil - video4linux developer - sponsored by TANDBERG

Re: V4L2 spec

[Mauro Carvalho Chehab]

Winfried,

On Mon, 9 Mar 2009 18:10:56 -0400
Devin Heitmueller <devin.heitmueller@gmail.com> wrote:

> On Mon, Mar 9, 2009 at 6:03 PM, wk <handygewinnspiel@gmx.de> wrote:
> > Its a bad idea to expect someone else, the magic volunteer, doing work with
> > *deep impact* on the dvb driver API structure or documentation.
> > Working on this topic determines complete usability of the driver, so MAIN
> > DEVELOPERS have to REVIEW and CONTRIBUTE.
> > If they think, that they cannot do such work in parallel, they should to
> > stop work on drivers for some time.
> 
> Cut me a $25,000 check and I'll happily do it.  Otherwise, don't tell
> a bunch of volunteer developers how they should be spending their
> time.  What you happen to think is the important is not necessarily
> what developers feel is the most valuable use of their time.
> 
> The reality is that there is *some* value a developer can contribute
> in reviewing the content and providing feedback and a *TON* of grunt
> work involved that can be done by anybody who takes the time to learn
> docbook.  If someone wants to volunteer to do the former, I'm sure
> some developers would be willing to do the latter.

I agree with Devin. 

The format conversion itself doesn't aggregate value to the spec. It is just a
format conversion. Even the merge between V4L and DVB specs doesn't aggregate
much value, per se. The value of a merged docbook with V4L and DVB will appear
when some new chapters will be added, mentioning how a hybrid driver should
work to provide both APIs, and maybe creating some additional functions to
control the hybrid behaviour (if needed).

I doubt that you'll find a main developer to do the docbook conversion work,
instead of spending his time developing. There are a number of reasons for
that, including that developers are good with C language but are probably not
familiar with docbook/latex languages. Also, they are not as skilled on writing
a book in English than on writing a C file. A proof of this is that most of the
work on both V4L and DVB APIs were done by a very small subset of people.

So, the better is to have someone more focused with documentation that will do
the hard work, with the support of the developers that will review and help
with the contents of the document, fixing the non-compliances (at the code, or
by proposing a patch to the docs).

Cheers,
Mauro

Re: V4L2 spec

[Andy Walls]

On Mon, 2009-03-09 at 23:44 +0100, Hans Verkuil wrote:
> On Monday 09 March 2009 23:10:56 Devin Heitmueller wrote:
> > On Mon, Mar 9, 2009 at 6:03 PM, wk <handygewinnspiel@gmx.de> wrote:

> > The reality is that there is *some* value a developer can contribute
> > in reviewing the content and providing feedback and a *TON* of grunt
> > work involved that can be done by anybody who takes the time to learn
> > docbook.  If someone wants to volunteer to do the former, I'm sure
> > some developers would be willing to do the latter.
> 
> Indeed. If someone could do the 'grunt' work of converting the dvb doc into 
> DocBook 

The Google leads me to ask:

What about a LaTeX to HTML or OOo Writer convertor:

http://www.tug.org/utilities/texconv/textopc.html#TeX4ht

(maybe oolatex?)

Then OOo Writer saving to DocBook?

I suspect it won't be perfect, but since existing software does the
heavy lifting, it beats manual conversion.


I didn't quite understand why a conversion is necessary, but I do see a
lot of hard-coded structures in the LaTeX documents, which I suspect is
a pain to keep up to date.



> and integrating it into the existing v4l docbook,

I'm not sure of the value in that.

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

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.
</opinion>

Regards,
Andy

Re: V4L2 spec

[Andy Walls]

On Mon, 2009-03-09 at 19:46 -0400, Andy Walls wrote:
> On Mon, 2009-03-09 at 23:44 +0100, Hans Verkuil wrote:
> > On Monday 09 March 2009 23:10:56 Devin Heitmueller wrote:
> > > On Mon, Mar 9, 2009 at 6:03 PM, wk <handygewinnspiel@gmx.de> wrote:

> > Indeed. If someone could do the 'grunt' work of converting the dvb doc into 
> > DocBook 
> 
> The Google leads me to ask:
> 
> What about a LaTeX to HTML or OOo Writer convertor:
> 
> http://www.tug.org/utilities/texconv/textopc.html#TeX4ht
> 
> (maybe oolatex?)
> 
> Then OOo Writer saving to DocBook?

Following up: apparently TeX4ht's dmlatex or dblatex command can go
straight from LaTex to DocBook:

http://www.cse.ohio-state.edu/~gurari/TeX4ht/mn-commands.html

> I suspect it won't be perfect, but since existing software does the
> heavy lifting, it beats manual conversion.

Regards,
Andy

Re: V4L2 spec

[Mauro Carvalho Chehab]

On Mon, 09 Mar 2009 19:56:56 -0400
Andy Walls <awalls@radix.net> wrote:

> On Mon, 2009-03-09 at 19:46 -0400, Andy Walls wrote:
> > On Mon, 2009-03-09 at 23:44 +0100, Hans Verkuil wrote:
> > > On Monday 09 March 2009 23:10:56 Devin Heitmueller wrote:
> > > > On Mon, Mar 9, 2009 at 6:03 PM, wk <handygewinnspiel@gmx.de> wrote:
> 
> > > Indeed. If someone could do the 'grunt' work of converting the dvb doc into 
> > > DocBook 
> > 
> > The Google leads me to ask:
> > 
> > What about a LaTeX to HTML or OOo Writer convertor:
> > 
> > http://www.tug.org/utilities/texconv/textopc.html#TeX4ht
> > 
> > (maybe oolatex?)
> > 
> > Then OOo Writer saving to DocBook?
> 
> Following up: apparently TeX4ht's dmlatex or dblatex command can go
> straight from LaTex to DocBook:
> 
> http://www.cse.ohio-state.edu/~gurari/TeX4ht/mn-commands.html
> 
> > I suspect it won't be perfect, but since existing software does the
> > heavy lifting, it beats manual conversion.

It would be a worth trial to use such tools to convert the doc.

Cheers,
Mauro

Re: V4L2 spec

[Mauro Carvalho Chehab]

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

Re: V4L2 spec

[Hans Verkuil]

On Tuesday 10 March 2009 01:54:15 Mauro Carvalho Chehab wrote:
> 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.

Part of the DVB API relating to audio/video decoding is actually shared 
between DVB and V4L (ivtv uses it for decoding). So that alone is a good 
argument IMHO to merge the two.

Regards,

	Hans

-- 
Hans Verkuil - video4linux developer - sponsored by TANDBERG

Re: V4L2 spec

[wk]

Devin Heitmueller schrieb:
> On Mon, Mar 9, 2009 at 6:03 PM, wk <handygewinnspiel@gmx.de> wrote:
>   
>> Its a bad idea to expect someone else, the magic volunteer, doing work with
>> *deep impact* on the dvb driver API structure or documentation.
>> Working on this topic determines complete usability of the driver, so MAIN
>> DEVELOPERS have to REVIEW and CONTRIBUTE.
>> If they think, that they cannot do such work in parallel, they should to
>> stop work on drivers for some time.
>>     
>
> Cut me a $25,000 check and I'll happily do it.  Otherwise, don't tell
> a bunch of volunteer developers how they should be spending their
> time.  What you happen to think is the important is not necessarily
> what developers feel is the most valuable use of their time.
>   
Devin,

during your work on drivers you use a lot of tools and applications, 
most probably a lot of them beeing open-source.
Did YOU spend 25000usd for each of the developers of that tools which 
documentation you was using? Hopefully - after such a comment.

Documentation is part of development.

-Winfried

Re: V4L2 spec

[wk]

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

Re: V4L2 spec

[Trent Piepho]

On Mon, 9 Mar 2009, Hans Verkuil wrote:
> On Monday 09 March 2009 12:08:39 Mauro Carvalho Chehab wrote:
> > On Fri, 6 Mar 2009, wk wrote:
> > > Hans Verkuil wrote:
> > >>  Hi Mauro,
> > >>
> > >>  I noticed that there is an ancient V4L2 spec in our tree in the
> > >> v4l/API directory. Is that spec used in any way? I don't think so, so
> > >> I suggest that it is removed.
> >
> > OK.
> >
> > >>  The V4L1 spec that is there should probably be moved to the v4l2-spec
> > >>  directory as that is where people would look for it. We can just keep
> > >> it there for reference.
> >
> > Nah. Let's just strip and point to some place where V4L1 doc is
> > available, adding some warning that the API is outdated and will be
> > removed from kernel soon.
>
> I don't think we should remove the doc from the repo until all drivers are
> converted to v4l2.

I think it would be useful to keep around.  Consider someone trying to
convert some old app or driver from v4l1 to v4l2.  It would be useful for
them to have the spec for v4l1 to know what the software was trying to do.

You could just point somewhere else, but things move, and that's another
link that will need to be kept up to date.  And there could be updates to
it, like common ways that v4l1 apps violate the spec that you need to deal
with when converting to v4l2.