Re: [ANN] Media documentation converted to ReST markup language
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 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [ANN] Media documentation converted to ReST markup language
Em Sat, 09 Jul 2016 20:10:21 +0300 Laurent Pinchartescreveu: > 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 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [ANN] Media documentation converted to ReST markup language
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 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [ANN] Media documentation converted to ReST markup language
Em Fri, 8 Jul 2016 15:45:52 +0200 Hans Verkuilescreveu: > 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 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [ANN] Media documentation converted to ReST markup language
Em Fri, 8 Jul 2016 15:45:52 +0200 Hans Verkuilescreveu: > 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 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [ANN] Media documentation converted to ReST markup language
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 majord...@vger.kernel.org > More majordomo info at http://vger.kernel.org/majordomo-info.html > -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[ANN] Media documentation converted to ReST markup language
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 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html