[ANN] Media documentation converted to ReST markup language

[ANN] Media documentation converted to ReST markup language

[Mauro Carvalho Chehab]

As commented on the patch series I just submitted, we finished the conversion
of the Media uAPI book from DocBook to ReST.

For now, I'm placing the new documentation, after parsed by Sphinx, at this
place:
	https://mchehab.fedorapeople.org/media_API_book/

There are some instructions there about how to use Sphinx too, with can be
useful for the ones writing patches. Those are part of the docs-next that
will be sent to Kernel 4.8, thanks to Jani Nikula an Jonathan Corbet.

The media docbook itself is located at:
	https://mchehab.fedorapeople.org/media_API_book/linux_tv/index.html

And the patches are already at the media tree, under the "docs-next"
branch:
	https://git.linuxtv.org/media_tree.git/log/?h=docs-next

If you find anything inconsistent, wrong or incomplete, feel free to
submit patches to it. My plan is to merge this branch on Kernel 4.8-rc1
and then remove the Documentation/DocBook/media stuff from the Kernel.

PS.: I'll soon be adding one extra patch there renaming the media
directory. "linux_tv" is not the best name for the media contents,
but, on the other hand, having a "media/media" directory also doesn't
make sense. So, I need to think for a better name before doing the
change. Pehaps I'll go for:
	Documentation/media - for all media documentation, were we
		should also store things that are now under 
		/video4linux and under /dvb;

and:
	Documentation/media/uapi - for the above book that were just
		converted from DocBook.

Enjoy!

Thanks,
Mauro

Re: [ANN] Media documentation converted to ReST markup language

[Hans Verkuil]

On 07/08/2016 03:34 PM, Mauro Carvalho Chehab wrote:
> As commented on the patch series I just submitted, we finished the conversion
> of the Media uAPI book from DocBook to ReST.
> 
> For now, I'm placing the new documentation, after parsed by Sphinx, at this
> place:
> 	https://mchehab.fedorapeople.org/media_API_book/
> 
> There are some instructions there about how to use Sphinx too, with can be
> useful for the ones writing patches. Those are part of the docs-next that
> will be sent to Kernel 4.8, thanks to Jani Nikula an Jonathan Corbet.
> 
> The media docbook itself is located at:
> 	https://mchehab.fedorapeople.org/media_API_book/linux_tv/index.html
> 
> And the patches are already at the media tree, under the "docs-next"
> branch:
> 	https://git.linuxtv.org/media_tree.git/log/?h=docs-next
> 
> If you find anything inconsistent, wrong or incomplete, feel free to
> submit patches to it. My plan is to merge this branch on Kernel 4.8-rc1
> and then remove the Documentation/DocBook/media stuff from the Kernel.
> 
> PS.: I'll soon be adding one extra patch there renaming the media
> directory. "linux_tv" is not the best name for the media contents,
> but, on the other hand, having a "media/media" directory also doesn't
> make sense. So, I need to think for a better name before doing the
> change. Pehaps I'll go for:
> 	Documentation/media - for all media documentation, were we
> 		should also store things that are now under 
> 		/video4linux and under /dvb;
> 
> and:
> 	Documentation/media/uapi - for the above book that were just
> 		converted from DocBook.

Sounds good to me!

Regards,

	Hans

> 
> Enjoy!
> 
> Thanks,
> Mauro
> --
> To unsubscribe from this list: send the line "unsubscribe linux-media" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
> 

Re: [ANN] Media documentation converted to ReST markup language

[Mauro Carvalho Chehab]

Em Fri, 8 Jul 2016 15:45:52 +0200
Hans Verkuil <hverkuil@xs4all.nl> escreveu:

> On 07/08/2016 03:34 PM, Mauro Carvalho Chehab wrote:
> > As commented on the patch series I just submitted, we finished the conversion
> > of the Media uAPI book from DocBook to ReST.
> > 
> > For now, I'm placing the new documentation, after parsed by Sphinx, at this
> > place:
> > 	https://mchehab.fedorapeople.org/media_API_book/
> > 
> > There are some instructions there about how to use Sphinx too, with can be
> > useful for the ones writing patches. Those are part of the docs-next that
> > will be sent to Kernel 4.8, thanks to Jani Nikula an Jonathan Corbet.
> > 
> > The media docbook itself is located at:
> > 	https://mchehab.fedorapeople.org/media_API_book/linux_tv/index.html
> > 
> > And the patches are already at the media tree, under the "docs-next"
> > branch:
> > 	https://git.linuxtv.org/media_tree.git/log/?h=docs-next
> > 
> > If you find anything inconsistent, wrong or incomplete, feel free to
> > submit patches to it. My plan is to merge this branch on Kernel 4.8-rc1
> > and then remove the Documentation/DocBook/media stuff from the Kernel.
> > 
> > PS.: I'll soon be adding one extra patch there renaming the media
> > directory. "linux_tv" is not the best name for the media contents,
> > but, on the other hand, having a "media/media" directory also doesn't
> > make sense. So, I need to think for a better name before doing the
> > change. Pehaps I'll go for:
> > 	Documentation/media - for all media documentation, were we
> > 		should also store things that are now under 
> > 		/video4linux and under /dvb;
> > 
> > and:
> > 	Documentation/media/uapi - for the above book that were just
> > 		converted from DocBook.  
> 
> Sounds good to me!

Done. Patch applied.

Thanks,
Mauro

Re: [ANN] Media documentation converted to ReST markup language

[Mauro Carvalho Chehab]

Em Fri, 8 Jul 2016 15:45:52 +0200
Hans Verkuil <hverkuil@xs4all.nl> escreveu:

> On 07/08/2016 03:34 PM, Mauro Carvalho Chehab wrote:
> > As commented on the patch series I just submitted, we finished the conversion
> > of the Media uAPI book from DocBook to ReST.
> > 
> > For now, I'm placing the new documentation, after parsed by Sphinx, at this
> > place:
> > 	https://mchehab.fedorapeople.org/media_API_book/
> > 
> > There are some instructions there about how to use Sphinx too, with can be
> > useful for the ones writing patches. Those are part of the docs-next that
> > will be sent to Kernel 4.8, thanks to Jani Nikula an Jonathan Corbet.
> > 
> > The media docbook itself is located at:
> > 	https://mchehab.fedorapeople.org/media_API_book/linux_tv/index.html
> > 
> > And the patches are already at the media tree, under the "docs-next"
> > branch:
> > 	https://git.linuxtv.org/media_tree.git/log/?h=docs-next
> > 
> > If you find anything inconsistent, wrong or incomplete, feel free to
> > submit patches to it. My plan is to merge this branch on Kernel 4.8-rc1
> > and then remove the Documentation/DocBook/media stuff from the Kernel.
> > 
> > PS.: I'll soon be adding one extra patch there renaming the media
> > directory. "linux_tv" is not the best name for the media contents,
> > but, on the other hand, having a "media/media" directory also doesn't
> > make sense. So, I need to think for a better name before doing the
> > change. Pehaps I'll go for:
> > 	Documentation/media - for all media documentation, were we
> > 		should also store things that are now under 
> > 		/video4linux and under /dvb;
> > 
> > and:
> > 	Documentation/media/uapi - for the above book that were just
> > 		converted from DocBook.  
> 
> Sounds good to me!

I'm placing the ReST version of the document under:
	https://linuxtv.org/downloads/v4l-dvb-apis-new/media/media_uapi.html

For now, I'm updating it manually, as, currently, there's no way to
tell the Kernel build system to build just the media uAPI book.

Thanks,
Mauro

Re: [ANN] Media documentation converted to ReST markup language

[Laurent Pinchart]

Hi Mauro,

On Friday 08 Jul 2016 10:34:20 Mauro Carvalho Chehab wrote:
> As commented on the patch series I just submitted, we finished the
> conversion of the Media uAPI book from DocBook to ReST.
> 
> For now, I'm placing the new documentation, after parsed by Sphinx, at this
> place:
> 	https://mchehab.fedorapeople.org/media_API_book/
> 
> There are some instructions there about how to use Sphinx too, with can be
> useful for the ones writing patches. Those are part of the docs-next that
> will be sent to Kernel 4.8, thanks to Jani Nikula an Jonathan Corbet.
> 
> The media docbook itself is located at:
> 	https://mchehab.fedorapeople.org/media_API_book/linux_tv/index.html
> 
> And the patches are already at the media tree, under the "docs-next"
> branch:
> 	https://git.linuxtv.org/media_tree.git/log/?h=docs-next
> 
> If you find anything inconsistent, wrong or incomplete, feel free to
> submit patches to it. My plan is to merge this branch on Kernel 4.8-rc1
> and then remove the Documentation/DocBook/media stuff from the Kernel.
> 
> PS.: I'll soon be adding one extra patch there renaming the media
> directory. "linux_tv" is not the best name for the media contents,
> but, on the other hand, having a "media/media" directory also doesn't
> make sense. So, I need to think for a better name before doing the
> change. Pehaps I'll go for:
> 	Documentation/media - for all media documentation, were we
> 		should also store things that are now under
> 		/video4linux and under /dvb;
> 
> and:
> 	Documentation/media/uapi - for the above book that were just
> 		converted from DocBook.

The layout looks fresh and new, that's nice. I've noticed two pain points 
though. One of them is that the left-hand side navigation table requires 
Javascript. I wonder if there would be away to expand it fully, or even remove 
it, when Javascript is disabled.

The other one is related, the table of contents in the main page of each 
section 
(https://mchehab.fedorapeople.org/media_API_book/linux_tv/media/v4l/v4l2.html 
for instance) only shows the first level entries. We have a full table of 
contents now, and that's very practical to quickly search for the information 
we need without requiring many clicks (or actually any click at all). How can 
we keep that feature ?

By the way, the "Video for Linux API" section (and the other sibling sections) 
are child nodes of the "Introduction" section. That feels quite odd.

-- 
Regards,

Laurent Pinchart

Re: [ANN] Media documentation converted to ReST markup language

[Mauro Carvalho Chehab]

Em Sat, 09 Jul 2016 20:10:21 +0300
Laurent Pinchart <laurent.pinchart@ideasonboard.com> escreveu:

> The other one is related, the table of contents in the main page of each 
> section 
> (https://mchehab.fedorapeople.org/media_API_book/linux_tv/media/v4l/v4l2.html 
> for instance) only shows the first level entries. We have a full table of 
> contents now, and that's very practical to quickly search for the information 
> we need without requiring many clicks (or actually any click at all). How can 
> we keep that feature ?

It is not hard to change the level of entries, although I really hated the
DocBook template that creates multi-depth TOCs everywhere, as it is very
messy to see those big indexes in the middle of the book.

What I did was to add *one* full contents index (actually, up to level 5)
at the first page of the book:
	https://linuxtv.org/downloads/v4l-dvb-apis-new/media/media_uapi.html

and kept the other ones with depth 1.

> 
> By the way, the "Video for Linux API" section (and the other sibling sections) 
> are child nodes of the "Introduction" section. That feels quite odd.


This was fixed already.

Thanks,
Mauro

Re: [ANN] Media documentation converted to ReST markup language

[Laurent Pinchart]

Hi Mauro,

On Wednesday 13 Jul 2016 11:11:43 Mauro Carvalho Chehab wrote:
> Em Sat, 09 Jul 2016 20:10:21 +0300 Laurent Pinchart escreveu:
> > The other one is related, the table of contents in the main page of each
> > section
> > (https://mchehab.fedorapeople.org/media_API_book/linux_tv/media/v4l/v4l2.h
> > tml for instance) only shows the first level entries. We have a full table
> > of contents now, and that's very practical to quickly search for the
> > information we need without requiring many clicks (or actually any click
> > at all). How can we keep that feature ?
> 
> It is not hard to change the level of entries, although I really hated the
> DocBook template that creates multi-depth TOCs everywhere, as it is very
> messy to see those big indexes in the middle of the book.
> 
> What I did was to add *one* full contents index (actually, up to level 5)
> at the first page of the book:
> 	https://linuxtv.org/downloads/v4l-dvb-apis-new/media/media_uapi.html
> 
> and kept the other ones with depth 1.

Thank you, that's exactly what I had in mind.

> > By the way, the "Video for Linux API" section (and the other sibling
> > sections) are child nodes of the "Introduction" section. That feels quite
> > odd.
>
> This was fixed already.

-- 
Regards,

Laurent Pinchart