Make PDF output for media book to work
Subsystems (3)
v2 cover Make PDF output for media book to work
This patch series fix the severe issues related to LaTeX output with media. After applying it, "make pdfdocs" generates the Kernel documentation with all books upstream, including the media books.
There are still some caveats, but the end result can be seen at:
https://mchehab.fedorapeople.org/TheLinuxKernel.pdf
To help people testing it, I pushed the patches on this series, plus two patches from Jani at:
https://git.linuxtv.org/mchehab/experimental.git/log/?h=docs-next
This series contain:
1) 3 patches fixing LaTeX handling at Documentation/conf.py
Those patches use "xelatex" instead of "pdflatex", with fix support for UTF-8 characters, needed by the media books. It also fixes the breakages on LaTeX Sphinx output for notes inside tables. Finally, it allows rotating some pages at the PDF output. This is needed in order to output very big tables. Patches to rotate such tables are not in this series.
2) a patch that makes usage of Sphinx math extension;
3) One patch converting some GIF files to PNG (needed by pdflatex). Didn't check if xelatex needs it, but it is still a good idea to use PNG.
4) 3 fixup patches (that are actually independent of this series
5) A hack that does two things:
- comment out C blocks inside tables, as Sphinx 1.4.5 produces a broken LaTeX file if it sees such blocks;
- Cleans the auto-generated rst files, as the escape codes there are meant to work with HTML, and not LaTeX. It is likely easy to fix the perl script to do the right thing here, but, as Markus is writing a Sphinx extension for it, let's discuss it uptream before doing rework.
PS.: The last patch are not meant to be merged. Merging the other ones should be OK.
Mauro Carvalho Chehab (9):
docs-rst: allow generating some LaTeX pages in landscape
docs-rst: improve output for .. notes:: on LaTeX
docs-rst: Don't mangle with UTF-8 chars on LaTeX/PDF output [media] pixfmt-007.rst: use Sphinx math:: expressions [media] pixfmt-nv12mt.rst: use PNG instead of GIF [media] vidioc-enumstd.rst: fix a broken reference [media] vidioc-enumstd.rst: remove bullets from sound carrier [media] docs-rst: better use the .. note:: tag
HACK: make pdfdocs build with media books
Documentation/Makefile.sphinx | 7 +- Documentation/conf.py | 56 ++++-- Documentation/media/uapi/cec/cec-func-close.rst | 4 +- Documentation/media/uapi/cec/cec-func-ioctl.rst | 4 +- Documentation/media/uapi/cec/cec-func-open.rst | 4 +- Documentation/media/uapi/cec/cec-func-poll.rst | 4 +- Documentation/media/uapi/cec/cec-intro.rst | 4 +- .../media/uapi/cec/cec-ioc-adap-g-caps.rst | 4 +- .../media/uapi/cec/cec-ioc-adap-g-log-addrs.rst | 4 +- .../media/uapi/cec/cec-ioc-adap-g-phys-addr.rst | 4 +- Documentation/media/uapi/cec/cec-ioc-dqevent.rst | 4 +- Documentation/media/uapi/cec/cec-ioc-g-mode.rst | 4 +- Documentation/media/uapi/cec/cec-ioc-receive.rst | 4 +- .../media/uapi/dvb/dvb-fe-read-status.rst | 4 +- Documentation/media/uapi/dvb/dvbapi.rst | 4 +- Documentation/media/uapi/dvb/dvbproperty.rst | 4 +- Documentation/media/uapi/dvb/examples.rst | 4 +- Documentation/media/uapi/dvb/fe-get-info.rst | 4 +- Documentation/media/uapi/dvb/fe-read-status.rst | 4 +- Documentation/media/uapi/dvb/frontend.rst | 4 +- .../media/uapi/rc/lirc-set-wideband-receiver.rst | 4 +- Documentation/media/uapi/v4l/audio.rst | 4 +- Documentation/media/uapi/v4l/buffer.rst | 13 +- Documentation/media/uapi/v4l/crop.rst | 12 +- Documentation/media/uapi/v4l/dev-codec.rst | 4 +- Documentation/media/uapi/v4l/dev-osd.rst | 4 +- Documentation/media/uapi/v4l/dev-overlay.rst | 8 +- Documentation/media/uapi/v4l/dev-rds.rst | 4 +- Documentation/media/uapi/v4l/extended-controls.rst | 4 +- Documentation/media/uapi/v4l/func-mmap.rst | 4 +- Documentation/media/uapi/v4l/pixfmt-006.rst | 4 +- Documentation/media/uapi/v4l/pixfmt-007.rst | 187 ++++++++++++++------- Documentation/media/uapi/v4l/pixfmt-nv12mt.rst | 4 +- .../media/uapi/v4l/pixfmt-nv12mt_files/nv12mt.gif | Bin 2108 -> 0 bytes .../media/uapi/v4l/pixfmt-nv12mt_files/nv12mt.png | Bin 0 -> 1920 bytes .../v4l/pixfmt-nv12mt_files/nv12mt_example.gif | Bin 6858 -> 0 bytes .../v4l/pixfmt-nv12mt_files/nv12mt_example.png | Bin 0 -> 5261 bytes Documentation/media/uapi/v4l/pixfmt-sbggr16.rst | 4 +- Documentation/media/uapi/v4l/pixfmt-y16-be.rst | 4 +- Documentation/media/uapi/v4l/pixfmt-y16.rst | 4 +- Documentation/media/uapi/v4l/standard.rst | 4 +- Documentation/media/uapi/v4l/tuner.rst | 4 +- Documentation/media/uapi/v4l/userp.rst | 4 +- .../media/uapi/v4l/vidioc-dv-timings-cap.rst | 4 +- .../media/uapi/v4l/vidioc-enum-dv-timings.rst | 4 +- Documentation/media/uapi/v4l/vidioc-enum-fmt.rst | 17 +- .../media/uapi/v4l/vidioc-enum-frameintervals.rst | 4 +- .../media/uapi/v4l/vidioc-enum-framesizes.rst | 4 +- .../media/uapi/v4l/vidioc-enum-freq-bands.rst | 4 +- .../media/uapi/v4l/vidioc-enumaudioout.rst | 4 +- Documentation/media/uapi/v4l/vidioc-enumstd.rst | 27 ++- Documentation/media/uapi/v4l/vidioc-g-audioout.rst | 4 +- Documentation/media/uapi/v4l/vidioc-g-edid.rst | 4 +- .../media/uapi/v4l/vidioc-g-ext-ctrls.rst | 8 +- .../media/uapi/v4l/vidioc-g-modulator.rst | 4 +- .../media/uapi/v4l/vidioc-g-sliced-vbi-cap.rst | 4 +- Documentation/media/uapi/v4l/vidioc-g-tuner.rst | 8 +- Documentation/media/uapi/v4l/vidioc-qbuf.rst | 4 +- .../media/uapi/v4l/vidioc-query-dv-timings.rst | 4 +- Documentation/media/uapi/v4l/vidioc-querycap.rst | 20 +-- Documentation/media/uapi/v4l/vidioc-queryctrl.rst | 16 +- Documentation/media/uapi/v4l/vidioc-querystd.rst | 4 +- Documentation/media/uapi/v4l/vidioc-streamon.rst | 4 +- .../media/uapi/v4l/vidioc-subscribe-event.rst | 4 +- Documentation/media/v4l-drivers/bttv.rst | 1 + 65 files changed, 396 insertions(+), 176 deletions(-) delete mode 100644 Documentation/media/uapi/v4l/pixfmt-nv12mt_files/nv12mt.gif create mode 100644 Documentation/media/uapi/v4l/pixfmt-nv12mt_files/nv12mt.png delete mode 100644 Documentation/media/uapi/v4l/pixfmt-nv12mt_files/nv12mt_example.gif create mode 100644 Documentation/media/uapi/v4l/pixfmt-nv12mt_files/nv12mt_example.png
Signature · 1 line
2.7.4
PATCH v2 1/9 docs-rst: allow generating some LaTeX pages in landscape
Portrait is too small for some tables used at the media docs. So, allow documents to tell Sphinx to generate some pages in landscape by using:
.. raw:: latex
\begin{landscape}<some stuff>
.. raw:: latex
\end{landscape}--- Documentation/conf.py | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-)
Documentation/conf.py +8 -5
@@ -252,16 +252,19 @@ htmlhelp_basename = 'TheLinuxKerneldoc' latex_elements = { # The paper size ('letterpaper' or 'a4paper'). -#'papersize': 'letterpaper', +'papersize': 'a4paper', # The font size ('10pt', '11pt' or '12pt'). -#'pointsize': '10pt', - -# Additional stuff for the LaTeX preamble. -#'preamble': '', +'pointsize': '10pt', # Latex figure (float) alignment #'figure_align': 'htbp', + +# Additional stuff for the LaTeX preamble. + 'preamble': ''' + % Allow generate some pages in landscape + \\usepackage{lscape} + ''' } # Grouping the document tree into LaTeX files. List of tuples
Signature · 1 line
2.7.4
RFC PATCH v2 2/9 docs-rst: improve output for .. notes:: on LaTeX
In reply to Mauro Carvalho ChehabThe output for those notes are bad in pdf, as they're not in a box with a different color. Also, it causes the output to not build if the note is inside a table.
Change its implementation to avoid the above troubles.
The logic there came from:
https://stackoverflow.com/questions/606746/how-to-customize-an-existing-latex-environment-without-interfering-with-other-en
--- Documentation/conf.py | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+)
Documentation/conf.py +23 -0
@@ -264,6 +264,29 @@ latex_elements = { 'preamble': ''' % Allow generate some pages in landscape \\usepackage{lscape} + + % Put notes in gray color and let them be inside a table + + \\definecolor{MyGray}{rgb}{0.80,0.80,0.80} + + \\makeatletter\\newenvironment{graybox}{% + \\begin{lrbox}{\\@tempboxa}\\begin{minipage}{\\columnwidth}}{\\end{minipage}\\end{lrbox}% + \\colorbox{MyGray}{\\usebox{\\@tempboxa}} + }\\makeatother + + \\makeatletter + \\renewenvironment{notice}[2]{ + \\begin{graybox} + \\bf\\it + \\def\\py@noticetype{#1} + \\par\\strong{#2} + \\csname py@noticestart@#1\\endcsname + } + { + \\csname py@noticeend@\\py@noticetype\\endcsname + \\end{graybox} + } + \\makeatother ''' }
Signature · 1 line
2.7.4
RFC PATCH v2 3/9 docs-rst: Don't mangle with UTF-8 chars on LaTeX/PDF output
In reply to Mauro Carvalho Chehabpdflatex doesn't accept using some UTF-8 chars, like "equal or less than" or "equal or greater than" chars. However, the media documents use them. So, we need to use XeLaTeX for conversion, and a font that accepts such characters.
--- Documentation/Makefile.sphinx | 6 +++--- Documentation/conf.py | 11 +++++++++++ 2 files changed, 14 insertions(+), 3 deletions(-)
Documentation/Makefile.sphinx +3 -3
@@ -26,7 +26,7 @@ else ifneq ($(DOCBOOKS),) else # HAVE_SPHINX # User-friendly check for pdflatex -HAVE_PDFLATEX := $(shell if which pdflatex >/dev/null 2>&1; then echo 1; else echo 0; fi) +HAVE_PDFLATEX := $(shell if which xelatex >/dev/null 2>&1; then echo 1; else echo 0; fi) # Internal variables. PAPEROPT_a4 = -D latex_paper_size=a4
@@ -45,11 +45,11 @@ htmldocs: pdfdocs: ifeq ($(HAVE_PDFLATEX),0) - $(warning The 'pdflatex' command was not found. Make sure you have it installed and in PATH to produce PDF output.) + $(warning The 'xelatex' command was not found. Make sure you have it installed and in PATH to produce PDF output.) @echo " SKIP Sphinx $@ target." else # HAVE_PDFLATEX $(call cmd,sphinx,latex) - $(Q)$(MAKE) -C $(BUILDDIR)/latex + $(Q)$(MAKE) PDFLATEX=xelatex -C $(BUILDDIR)/latex endif # HAVE_PDFLATEX epubdocs:
Documentation/conf.py +11 -0
@@ -260,6 +260,10 @@ latex_elements = { # Latex figure (float) alignment #'figure_align': 'htbp', +# Don't mangle with UTF-8 chars +'inputenc': '', +'utf8extra': '', + # Additional stuff for the LaTeX preamble. 'preamble': ''' % Allow generate some pages in landscape
@@ -287,6 +291,13 @@ latex_elements = { \\end{graybox} } \\makeatother + + % Use some font with UTF-8 support with XeLaTeX + \\usepackage{fontspec} + \\setsansfont{DejaVu Serif} + \\setromanfont{DejaVu Sans} + \\setmonofont{DejaVu Sans Mono} + ''' }
Signature · 1 line
2.7.4
Re: [PATCH RFC v2 3/9] docs-rst: Don't mangle with UTF-8 chars on LaTeX/PDF output
Am 15.08.2016 um 23:21 schrieb Mauro Carvalho Chehab <[email protected]>:
Quoted 4 lines
pdflatex doesn't accept using some UTF-8 chars, like "equal or less than" or "equal or greater than" chars. However, the media documents use them. So, we need to use XeLaTeX for conversion, and a font that accepts such characters.
Right, we should use the XeLaTeX engine. But ...
Sphinx LaTeX output was/is developed for LaTeX, not for XeLaTeX. E.g. in its defaults it uses "inputenc" and other stuff which is not a part of XeLaTeX.
* https://github.com/sphinx-doc/sphinx/issues/894#issuecomment-220786426
This patch removes the "inputenc", thats right, but I think over short/long term we will see more errors related to LaTeX/XeLaTeX distinction. And we will see that some conversion will break, depending on the sphinx version we use (There might be some non XeLateX friendly changes in the sphinx-versions, since it is not tested with XeLaTeX).
Nevertheless, XeLaTeX is the right choice!
My Suggestion is, that you merge this patch on top of Jon's doc-next. There, we have the sub-folders feature, with we can test book by book and improve our toolchain.
-- Markus --
Quoted 71 lines
Signed-off-by Mauro Carvalho Chehab <[email protected]>---
Documentation/Makefile.sphinx| 6 +++---Documentation/conf.py| 11 +++++++++++2 files changed, 14 insertions(+), 3 deletions(-)Documentation/Makefile.sphinx +0
-0@@ -26,7 +26,7 @@ else ifneq ($(DOCBOOKS),)else #
HAVE_SPHINX# User-friendly check for pdflatex
Documentation/Makefile.sphinx +1
-1-HAVE_PDFLATEX := $(shell if which pdflatex >/dev/null 2>&1; then echo 1; else echo 0; fi) +HAVE_PDFLATEX := $(shell if which xelatex >/dev/null 2>&1; then echo 1; else echo 0; fi)# Internal variables.
PAPEROPT_a4= -D latex_paper_size=a4Documentation/Makefile.sphinx +0
-0@@ -45,11 +45,11 @@ htmldocs:pdfdocs:
ifeq ($(HAVE_PDFLATEX),0)Documentation/Makefile.sphinx +1
-1- $(warning The 'pdflatex' command was not found. Make sure you have it installed and in PATH to produce PDF output.) + $(warning The 'xelatex' command was not found. Make sure you have it installed and in PATH to produce PDF output.)@echo " SKIP Sphinx $@ target."
else #HAVE_PDFLATEX$(call cmd,sphinx,latex)Documentation/Makefile.sphinx +1
-1- $(Q)$(MAKE) -C $(BUILDDIR)/latex + $(Q)$(MAKE) PDFLATEX=xelatex -C $(BUILDDIR)/latexendif #
HAVE_PDFLATEXepubdocs:
Documentation/conf.py +11
-0@@ -260,6 +260,10 @@ latex_elements = { # Latex figure (float) alignment #'figure_align': 'htbp', +# Don't mangle with UTF-8 chars +'inputenc': '', +'utf8extra': '', + # Additional stuff for the LaTeX preamble. 'preamble': ''' % Allow generate some pages in landscape@@ -287,6 +291,13 @@ latex_elements = { \\end{graybox} } \\makeatother + + % Use some font with UTF-8 support with XeLaTeX + \\usepackage{fontspec} + \\setsansfont{DejaVu Serif} + \\setromanfont{DejaVu Sans} + \\setmonofont{DejaVu Sans Mono} + ''' }Signature · 7 lines
2.7.4 -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH RFC v2 3/9] docs-rst: Don't mangle with UTF-8 chars on LaTeX/PDF output
Em Tue, 16 Aug 2016 10:27:34 +0200
Markus Heiser <[email protected]> escreveu:
Quoted 10 lines
Am 15.08.2016 um 23:21 schrieb Mauro Carvalho Chehab <[email protected]>:
Quoted 4 lines
pdflatex doesn't accept using some UTF-8 chars, like "equal or less than" or "equal or greater than" chars. However, the media documents use them. So, we need to use XeLaTeX for conversion, and a font that accepts such characters.
Right, we should use the XeLaTeX engine. But ...
Sphinx LaTeX output was/is developed for LaTeX, not for XeLaTeX.
Yes, but official support for XeLaTeX was added for 1.5:
https://github.com/agda/agda/commit/a6a437316c9b9d998e6d6d0a6a654a63422a4212
And the change there was really simple: it just adds it to the generated Makefile.
Quoted 8 lines
E.g. in its defaults it uses "inputenc" and other stuff which is not a part of XeLaTeX.
* https://github.com/sphinx-doc/sphinx/issues/894#issuecomment-220786426
This patch removes the "inputenc", thats right, but I think over short/long term we will see more errors related to LaTeX/XeLaTeX distinction.
Actually, I don't expect troubles at long term, as it is now officially supported.
Quoted 3 lines
And we will see that some conversion will break, depending on the sphinx version we use (There might be some non XeLateX friendly changes in the sphinx-versions, since it is not tested with XeLaTeX).
Yeah, we need to double-check backward compatibility, and eventually disable it on older versions.
I can't easily test version 1.3.x anymore, as Fedora 24 upgraded to Sphinx 1.4.4. The book builds fine on both 1.4.4 and 1.4.5.
I'll install a Debian Jessie LXC container and double-check if the build is fine with Sphinx version 1.2.x and check the package requirements.
Quoted 72 lines
Nevertheless, XeLaTeX is the right choice!
My Suggestion is, that you merge this patch on top of Jon's doc-next. There, we have the sub-folders feature, with we can test book by book and improve our toolchain.
-- Markus --
Quoted 63 lines
Signed-off-by Mauro Carvalho Chehab <[email protected]>---
Documentation/Makefile.sphinx| 6 +++---Documentation/conf.py| 11 +++++++++++2 files changed, 14 insertions(+), 3 deletions(-)Documentation/Makefile.sphinx +0
-0@@ -26,7 +26,7 @@ else ifneq ($(DOCBOOKS),)else #
HAVE_SPHINX# User-friendly check for pdflatex
Documentation/Makefile.sphinx +1
-1-HAVE_PDFLATEX := $(shell if which pdflatex >/dev/null 2>&1; then echo 1; else echo 0; fi) +HAVE_PDFLATEX := $(shell if which xelatex >/dev/null 2>&1; then echo 1; else echo 0; fi)# Internal variables.
PAPEROPT_a4= -D latex_paper_size=a4Documentation/Makefile.sphinx +0
-0@@ -45,11 +45,11 @@ htmldocs:pdfdocs:
ifeq ($(HAVE_PDFLATEX),0)Documentation/Makefile.sphinx +1
-1- $(warning The 'pdflatex' command was not found. Make sure you have it installed and in PATH to produce PDF output.) + $(warning The 'xelatex' command was not found. Make sure you have it installed and in PATH to produce PDF output.)@echo " SKIP Sphinx $@ target."
else #HAVE_PDFLATEX$(call cmd,sphinx,latex)Documentation/Makefile.sphinx +1
-1- $(Q)$(MAKE) -C $(BUILDDIR)/latex + $(Q)$(MAKE) PDFLATEX=xelatex -C $(BUILDDIR)/latexendif #
HAVE_PDFLATEXepubdocs:
Documentation/conf.py +11
-0@@ -260,6 +260,10 @@ latex_elements = { # Latex figure (float) alignment #'figure_align': 'htbp', +# Don't mangle with UTF-8 chars +'inputenc': '', +'utf8extra': '', + # Additional stuff for the LaTeX preamble. 'preamble': ''' % Allow generate some pages in landscape@@ -287,6 +291,13 @@ latex_elements = { \\end{graybox} } \\makeatother + + % Use some font with UTF-8 support with XeLaTeX + \\usepackage{fontspec} + \\setsansfont{DejaVu Serif} + \\setromanfont{DejaVu Sans} + \\setmonofont{DejaVu Sans Mono} + ''' }
Quoted 9 lines
Quoted 8 lines
Signature · 7 lines
2.7.4 -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
Thanks,
Mauro
Re: [PATCH RFC v2 3/9] docs-rst: Don't mangle with UTF-8 chars on LaTeX/PDF output
Em Tue, 16 Aug 2016 06:36:05 -0300
Mauro Carvalho Chehab <[email protected]> escreveu:
Quoted 36 lines
Em Tue, 16 Aug 2016 10:27:34 +0200
Markus Heiser <[email protected]> escreveu:Quoted 10 lines
Am 15.08.2016 um 23:21 schrieb Mauro Carvalho Chehab <[email protected]>:
Quoted 4 lines
pdflatex doesn't accept using some UTF-8 chars, like "equal or less than" or "equal or greater than" chars. However, the media documents use them. So, we need to use XeLaTeX for conversion, and a font that accepts such characters.
Right, we should use the XeLaTeX engine. But ...
Sphinx LaTeX output was/is developed for LaTeX, not for XeLaTeX.
Yes, but official support for XeLaTeX was added for 1.5:
https://github.com/agda/agda/commit/a6a437316c9b9d998e6d6d0a6a654a63422a4212And the change there was really simple: it just adds it to the generated
Makefile.Quoted 8 lines
E.g. in its defaults it uses "inputenc" and other stuff which is not a part of XeLaTeX.
* https://github.com/sphinx-doc/sphinx/issues/894#issuecomment-220786426
This patch removes the "inputenc", thats right, but I think over short/long term we will see more errors related to LaTeX/XeLaTeX distinction.
Actually, I don't expect troubles at long term, as it is now officially supported.
Quoted 3 lines
And we will see that some conversion will break, depending on the sphinx version we use (There might be some non XeLateX friendly changes in the sphinx-versions, since it is not tested with XeLaTeX).
Quoted 8 lines
Yeah, we need to double-check backward compatibility, and eventually disable it on older versions.
I can't easily test version 1.3.x anymore, as Fedora 24 upgraded to Sphinx 1.4.4. The book builds fine on both 1.4.4 and 1.4.5.
I'll install a Debian Jessie LXC container and double-check if the build is fine with Sphinx version 1.2.x and check the package requirements.
Did some tests on Jessie. texlive required 219 packages there, 771MB. The packages I installed there are:
# 219 packages, 771MB - and includes some non-tex packages, that # are not present on the minimal LXC container install texlive-xetex
# 24 packages, 7289kB
python3-sphinx
# 2 packages, 373kB
python3-sphinx-rtd-theme
# Build environment: 19 packages
make gcc
# Fonts
ttf-dejavu
There are 2 issues there that are easy to solve, but would require some extra logic. I added a quick hack to make them build with xelatex. See enclosed. The issues are:
1) the name of the math extension changed from sphinx.ext.pngmath to sphinx.ext.imgmath on Sphinx 1.4. I guess it should be possible to add some logic at conf.py to change the include depending on the Sphinx version;
2) the Latex auto-generated Makefile is hardcoded to use pdflatex. So, I had to manually replace it to xelatex. One easy solution would be to not use Make -C $BUILDDIR/latex, but to just call xelatex $BUILDDIR/$tex_name.
Also, documentation hits an error. using <q> or <r> makes it build, but not sure what got missed there, as it has 1205 pages. I suspect that only the index was broken.
The error happens during document output phase:
[1] [2] (./TheLinuxKernel.toc)
Adding blank page after the table of contents.
[1] [2] [1] [2]
Chapter 1.
[3] [4]
! Misplaced \omit.
\multispan ->\omit
\@multispan
l.407 \hline\end{tabulary}
It resembles this error:
https://www.mail-archive.com/[email protected]/msg06083.html
So, I suspect it has nothing to do with xelatex, but it is, instead some Spinx 1.2.x bug when generating cell span output in Latex.
It happened on this part of the LaTeX source code:
\begin{threeparttable}
\capstart\caption{table title}
\begin{tabulary}{\linewidth}{|L|L|L|L|}
\hline
head col 1
&
head col 2
&
head col 3
&
head col 4
\\
\hline
column 1
&
field 1.1
& \multicolumn{2}{l|}{
field 1.2 with autospan
}\\
\hline
column 2
&
field 2.1
& \multirow{2}{*}{ \multicolumn{2}{l|}{
field 2.2 - 3.3
}}\\
\hline\phantomsection\label{kernel-documentation:last-row} column 3
& & \\
\hline\end{tabulary}
\end{threeparttable}
\end{quote}
Btw, removing the media books and all latex options, using pdflatex still doesn't build cleanly on 1.2.x:
Package inputenc Warning: inputenc package ignored with utf8 based engines.
)
! Undefined control sequence.
<recently read> \DeclareUnicodeCharacter
l.5 \DeclareUnicodeCharacter
{00A0}{\nobreakspace}Again, user has to use <q> or <r> to continue the build.
I'll try to install Ubuntu Xenial on a LXC container and repeat the test there. Xenial seems to use Sphinx 1.3.6, according with:
http://packages.ubuntu.com/search?keywords=python-sphinx
Btw, as now both latest version of Ubuntu and Fedora uses Sphinx 1.4.x, perhaps we could raise the bar and just require Sphinx > 1.4.
Thanks,
Mauro
Quick hack to make it build on Sphinx 1.2.3
Documentation/Makefile.sphinx +1 -1
@@ -50,7 +50,7 @@ ifeq ($(HAVE_PDFLATEX),0) else # HAVE_PDFLATEX $(call cmd,sphinx,latex) (cd $(BUILDDIR); for i in *.rst; do echo >$$i; done) - $(Q)$(MAKE) PDFLATEX=xelatex -C $(BUILDDIR)/latex + (cd $(BUILDDIR)/latex; xelatex TheLinuxKernel.tex) endif # HAVE_PDFLATEX epubdocs:
Documentation/conf.py +1 -1
@@ -28,7 +28,7 @@ sys.path.insert(0, os.path.abspath('sphinx')) # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = ['sphinx.ext.imgmath', 'kernel-doc', 'rstFlatTable', 'kernel_include'] +extensions = ['sphinx.ext.pngmath', 'kernel-doc', 'rstFlatTable', 'kernel_include'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates']
Re: [PATCH RFC v2 3/9] docs-rst: Don't mangle with UTF-8 chars on LaTeX/PDF output
Am 16.08.2016 um 13:03 schrieb Mauro Carvalho Chehab <[email protected]>:
Quoted 6 lines
Em Tue, 16 Aug 2016 06:36:05 -0300
Mauro Carvalho Chehab <[email protected]> escreveu:2) the Latex auto-generated
Makefileis hardcoded to use pdflatex. So, I had to manually replace it to xelatex. One easy solution would be to not use Make -C $BUILDDIR/latex, but to just call xelatex $BUILDDIR/$tex_name.
I recommend to ship your own tex-Makefile, see:
https://lkml.org/lkml/2016/8/10/114
-- Markus
Re: [PATCH RFC v2 3/9] docs-rst: Don't mangle with UTF-8 chars on LaTeX/PDF output
Em Tue, 16 Aug 2016 13:48:13 +0200
Markus Heiser <[email protected]> escreveu:
Quoted 5 lines
Am 16.08.2016 um 13:03 schrieb Mauro Carvalho Chehab <[email protected]>:
Quoted 3 lines
Em Tue, 16 Aug 2016 06:36:05 -0300
Mauro Carvalho Chehab <[email protected]> escreveu:
Quoted 7 lines
Quoted 3 lines
2) the Latex auto-generated
Makefileis hardcoded to use pdflatex. So, I had to manually replace it to xelatex. One easy solution would be to not use Make -C $BUILDDIR/latex, but to just call xelatex $BUILDDIR/$tex_name.I recommend to ship your own tex-Makefile, see:
That makes sense for me, but let the others review what we have so far. We can later improve and use a makefile for tex. I would prefer to call the version that will be copied to the output dir with a different name (like Makefile.tex or Makefile.in), as I found really weird to have a file called Makefile inside the Kernel tree that contains just a makefile prototype.
Regards,
Mauro
Re: [PATCH RFC v2 3/9] docs-rst: Don't mangle with UTF-8 chars on LaTeX/PDF output
In reply to Mauro Carvalho ChehabEm Tue, 16 Aug 2016 08:03:38 -0300
Mauro Carvalho Chehab <[email protected]> escreveu:
Quoted 4 lines
Em Tue, 16 Aug 2016 06:36:05 -0300
Mauro Carvalho Chehab <[email protected]> escreveu:Did some tests on Jessie. texlive required 219 packages there, 771MB.
...
Quoted 12 lines
There are 2 issues there that are easy to solve, but would require some extra logic. I added a quick hack to make them build with xelatex. See enclosed. The issues are:
1) the name of the math extension changed from sphinx.ext.pngmath to sphinx.ext.imgmath on Sphinx 1.4. I guess it should be possible to add some logic at
conf.pyto change the include depending on the Sphinx version;2) the Latex auto-generated
Makefileis hardcoded to use pdflatex. So, I had to manually replace it to xelatex. One easy solution would be to not use Make -C $BUILDDIR/latex, but to just call xelatex $BUILDDIR/$tex_name.
...
Quoted 3 lines
I'll try to install Ubuntu Xenial on a LXC container and repeat the test there. Xenial seems to use Sphinx 1.3.6, according with:
http://packages.ubuntu.com/search?keywords=python-sphinx
On Ubuntu Xenial LXC container, I had to install:
texlive-xetex python3-sphinx python3-sphinx-rtd-theme ttf-dejavu make gcc python3-sphinx-rtd-theme
With actually installed 259 packages, 1,6 GB after install (about 800MB of download).
The only issue there was the name of the math extension, with is also sphinx.ext.pngmath. On a plus side, I was also able to remove one of the hacks, by applying the enclosed patch (this doesn't work on 1.4 yet - I suspect it requires some extra stuff to escape).
So, for me, we're pretty much safe using xelatex, as it works fine for Sphinx 1.3 and 1.4 (and, with Sphinx 1.2, provided that the user asks to continue the build, just like what's needed with pdflatex on such version).
To make it generic, we'll need to patch conf.py to detect the Sphinx version, and use the right math extension, depending on the version. Also, as you proposed, Due to Sphinx version is 1.2, we'll need to use a custom-made Makefile for tex.
As xelatex support was added for version 1.5, we don't need to care about it.
Jon,
What do you think? Let's move to xelatex?
Thanks,
Mauro
Documentation/Makefile.sphinx +0 -1
@@ -49,7 +49,6 @@ ifeq ($(HAVE_PDFLATEX),0) @echo " SKIP Sphinx $@ target." else # HAVE_PDFLATEX $(call cmd,sphinx,latex) - (cd $(BUILDDIR); for i in *.rst; do echo >$$i; done) $(Q)$(MAKE) PDFLATEX=xelatex -C $(BUILDDIR)/latex endif # HAVE_PDFLATEX
Documentation/conf.py +1 -1
@@ -28,7 +28,7 @@ sys.path.insert(0, os.path.abspath('sphinx')) # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = ['sphinx.ext.imgmath', 'kernel-doc', 'rstFlatTable', 'kernel_include'] +extensions = ['sphinx.ext.pngmath', 'kernel-doc', 'rstFlatTable', 'kernel_include'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates']
Documentation/sphinx/parse-headers.pl +1 -1
@@ -220,7 +220,7 @@ $data =~ s/\n\s+\n/\n\n/g; # # Add escape codes for special characters # -$data =~ s,([\_\`\*\<\>\&\\\\:\/\|]),\\$1,g; +$data =~ s,([\_\`\*\<\>\&\\\\:\/\|\%\$\#\{\}\~\^]),\\$1,g; $data =~ s,DEPRECATED,**DEPRECATED**,g;
Re: [PATCH RFC v2 3/9] docs-rst: Don't mangle with UTF-8 chars on LaTeX/PDF output
Am 16.08.2016 um 14:16 schrieb Mauro Carvalho Chehab <[email protected]>:
...
Quoted 10 lines
The only issue there was the name of the math extension, with is also sphinx.ext.pngmath. On a plus side, I was also able to remove one of the hacks, by applying the enclosed patch (this doesn't work on 1.4 yet - I suspect it requires some extra stuff to escape).
So, for me, we're pretty much safe using xelatex, as it works fine for Sphinx 1.3 and 1.4 (and, with Sphinx 1.2, provided that the user asks to continue the build, just like what's needed with pdflatex on such version).
Quoted 7 lines
To make it generic, we'll need to patch
conf.pyto detect the Sphinx version, and use the right math extension, depending on the version. Also, as you proposed, Due to Sphinx version is 1.2, we'll need to use a custom-madeMakefilefor tex.As xelatex support was added for version 1.5, we don't need to care about it.
I haven't checked on which version which math-extension was replaced. But it is easy to detect the sphinx version in conf.py. Add these lines to conf.py::
import sphinx
major, minor, patch = map(int, sphinx.__version__.split("."))
The "minor" is what you are looking for.
if minor > 3:
extensions.append("sphinx.ext.imgmath")
else:
extensions.append("sphinx.ext.pngmath")
-- Markus --
Re: [PATCH RFC v2 3/9] docs-rst: Don't mangle with UTF-8 chars on LaTeX/PDF output
Em Tue, 16 Aug 2016 14:35:16 +0200
Markus Heiser <[email protected]> escreveu:
Quoted 28 lines
Am 16.08.2016 um 14:16 schrieb Mauro Carvalho Chehab <[email protected]>:
...
Quoted 10 lines
The only issue there was the name of the math extension, with is also sphinx.ext.pngmath. On a plus side, I was also able to remove one of the hacks, by applying the enclosed patch (this doesn't work on 1.4 yet - I suspect it requires some extra stuff to escape).
So, for me, we're pretty much safe using xelatex, as it works fine for Sphinx 1.3 and 1.4 (and, with Sphinx 1.2, provided that the user asks to continue the build, just like what's needed with pdflatex on such version).
Quoted 7 lines
To make it generic, we'll need to patch
conf.pyto detect the Sphinx version, and use the right math extension, depending on the version. Also, as you proposed, Due to Sphinx version is 1.2, we'll need to use a custom-madeMakefilefor tex.As xelatex support was added for version 1.5, we don't need to care about it.
I haven't checked on which version which math-extension was replaced. But it is easy to detect the sphinx version in
conf.py. Add these lines toconf.py::import sphinx
major, minor, patch =map(int, sphinx.__version__.split("."))
Quoted 6 lines
The "minor" is what you are looking for.
if minor > 3:
extensions.append("sphinx.ext.imgmath")
else:
extensions.append("sphinx.ext.pngmath")
Worked, thanks!
Added on the patch series I submitted.
Regards,
Mauro
RFC PATCH v2 4/9 pixfmt-007.rst: use Sphinx math:: expressions
In reply to Mauro Carvalho ChehabEnrich math formulas by using the Sphinx math. That will allow using those formulas on pdf documents as well.
--- Documentation/conf.py | 9 +- Documentation/media/uapi/v4l/pixfmt-007.rst | 175 ++++++++++++++++++---------- 2 files changed, 115 insertions(+), 69 deletions(-)
Documentation/conf.py +1 -8
@@ -28,14 +28,7 @@ sys.path.insert(0, os.path.abspath('sphinx')) # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = ['kernel-doc', 'rstFlatTable', 'kernel_include'] - -# Gracefully handle missing rst2pdf. -try: - import rst2pdf - extensions += ['rst2pdf.pdfbuilder'] -except ImportError: - pass +extensions = ['sphinx.ext.imgmath', 'kernel-doc', 'rstFlatTable', 'kernel_include'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates']
Documentation/media/uapi/v4l/pixfmt-007.rst +114 -61
331 lines not on this page · raw message
Signature · 1 line
2.7.4
RFC PATCH v2 5/9 pixfmt-nv12mt.rst: use PNG instead of GIF
In reply to Mauro Carvalho Chehabpdflatex doesn't like gif images:
None:None: WARNING: no matching candidate for image URI u'media/uapi/v4l/pixfmt-nv12mt_files/nv12mt.*' None:None: WARNING: no matching candidate for image URI u'media/uapi/v4l/pixfmt-nv12mt_files/nv12mt_example.*'
But it works fine with png. So, convert them. As a plus, PNG images are smaller.
--- Documentation/media/uapi/v4l/pixfmt-nv12mt.rst | 4 ++-- .../media/uapi/v4l/pixfmt-nv12mt_files/nv12mt.gif | Bin 2108 -> 0 bytes .../media/uapi/v4l/pixfmt-nv12mt_files/nv12mt.png | Bin 0 -> 1920 bytes .../uapi/v4l/pixfmt-nv12mt_files/nv12mt_example.gif | Bin 6858 -> 0 bytes .../uapi/v4l/pixfmt-nv12mt_files/nv12mt_example.png | Bin 0 -> 5261 bytes 5 files changed, 2 insertions(+), 2 deletions(-) delete mode 100644 Documentation/media/uapi/v4l/pixfmt-nv12mt_files/nv12mt.gif create mode 100644 Documentation/media/uapi/v4l/pixfmt-nv12mt_files/nv12mt.png delete mode 100644 Documentation/media/uapi/v4l/pixfmt-nv12mt_files/nv12mt_example.gif create mode 100644 Documentation/media/uapi/v4l/pixfmt-nv12mt_files/nv12mt_example.png
Documentation/media/uapi/v4l/pixfmt-nv12mt.rst +2 -2
@@ -36,7 +36,7 @@ Layout of macroblocks in memory is presented in the following figure. .. _nv12mt: .. figure:: pixfmt-nv12mt_files/nv12mt.* - :alt: nv12mt.gif + :alt: nv12mt.png :align: center V4L2_PIX_FMT_NV12MT macroblock Z shape memory layout
@@ -53,7 +53,7 @@ interleaved. Height of the buffer is aligned to 32. .. _nv12mt_ex: .. figure:: pixfmt-nv12mt_files/nv12mt_example.* - :alt: nv12mt_example.gif + :alt: nv12mt_example.png :align: center Example V4L2_PIX_FMT_NV12MT memory layout of macroblocks
Documentation/media/uapi/v4l/pixfmt-nv12mt_files/nv12mt.gif deleted binary +0 -0
Documentation/media/uapi/v4l/pixfmt-nv12mt_files/nv12mt.png new file binary +0 -0
Documentation/media/uapi/v4l/pixfmt-nv12mt_files/nv12mt_example.gif deleted binary +0 -0
Documentation/media/uapi/v4l/pixfmt-nv12mt_files/nv12mt_example.png new file binary +0 -0
Signature · 1 line
2.7.4
RFC PATCH v2 6/9 vidioc-enumstd.rst: fix a broken reference
In reply to Mauro Carvalho ChehabSomehow, the conversion broke a reference here. Re-add it.
--- Documentation/media/uapi/v4l/vidioc-enumstd.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/media/uapi/v4l/vidioc-enumstd.rst +1 -1
@@ -269,7 +269,7 @@ support digital TV. See also the Linux DVB API at .. _video-standards: -.. flat-table:: Video Standards (based on []) +.. flat-table:: Video Standards (based on :ref:`itu470`) :header-rows: 1 :stub-columns: 0
Signature · 1 line
2.7.4
RFC PATCH v2 7/9 vidioc-enumstd.rst: remove bullets from sound carrier
In reply to Mauro Carvalho ChehabThe items at the sound carrier had a bullet. Those are not needed.
So, get rid of them.
--- Documentation/media/uapi/v4l/vidioc-enumstd.rst | 25 ++++++++++++------------- 1 file changed, 12 insertions(+), 13 deletions(-)
Documentation/media/uapi/v4l/vidioc-enumstd.rst +12 -13
@@ -330,8 +330,7 @@ support digital TV. See also the Linux DVB API at - 4433618.75 ± 1 - - :cspan:`3` f\ :sub:`OR` = 4406250 ± 2000, f\ :sub:`OB` = 4250000 - ± 2000 + - :cspan:`3` f\ :sub:`OR` = 4406250 ± 2000, f\ :sub:`OB` = 4250000 ± 2000 - .. row 5
@@ -363,27 +362,27 @@ support digital TV. See also the Linux DVB API at - Sound carrier relative to vision carrier (MHz) - - + 4.5 + - 4.5 - - + 4.5 + - 4.5 - - + 4.5 + - 4.5 - - + 5.5 ± 0.001 [#f4]_ [#f5]_ [#f6]_ [#f7]_ + - 5.5 ± 0.001 [#f4]_ [#f5]_ [#f6]_ [#f7]_ - - + 6.5 ± 0.001 + - 6.5 ± 0.001 - - + 5.5 + - 5.5 - - + 5.9996 ± 0.0005 + - 5.9996 ± 0.0005 - - + 5.5 ± 0.001 + - 5.5 ± 0.001 - - + 6.5 ± 0.001 + - 6.5 ± 0.001 - - + 6.5 + - 6.5 - - + 6.5 [#f8]_ + - 6.5 [#f8]_ Return Value
Signature · 1 line
2.7.4
RFC PATCH v2 8/9 docs-rst: better use the .. note:: tag
In reply to Mauro Carvalho ChehabChange multi-line note tags to be more symetric, e. g. not starting the text together witht the tag.
--- Documentation/media/uapi/cec/cec-func-close.rst | 4 +++- Documentation/media/uapi/cec/cec-func-ioctl.rst | 4 +++- Documentation/media/uapi/cec/cec-func-open.rst | 4 +++- Documentation/media/uapi/cec/cec-func-poll.rst | 4 +++- Documentation/media/uapi/cec/cec-intro.rst | 4 +++- Documentation/media/uapi/cec/cec-ioc-adap-g-caps.rst | 4 +++- .../media/uapi/cec/cec-ioc-adap-g-log-addrs.rst | 4 +++- .../media/uapi/cec/cec-ioc-adap-g-phys-addr.rst | 4 +++- Documentation/media/uapi/cec/cec-ioc-dqevent.rst | 4 +++- Documentation/media/uapi/cec/cec-ioc-g-mode.rst | 4 +++- Documentation/media/uapi/cec/cec-ioc-receive.rst | 4 +++- Documentation/media/uapi/dvb/dvb-fe-read-status.rst | 4 +++- Documentation/media/uapi/dvb/dvbapi.rst | 4 +++- Documentation/media/uapi/dvb/dvbproperty.rst | 4 +++- Documentation/media/uapi/dvb/examples.rst | 4 +++- Documentation/media/uapi/dvb/fe-get-info.rst | 4 +++- Documentation/media/uapi/dvb/fe-read-status.rst | 4 +++- Documentation/media/uapi/dvb/frontend.rst | 4 +++- .../media/uapi/rc/lirc-set-wideband-receiver.rst | 4 +++- Documentation/media/uapi/v4l/audio.rst | 4 +++- Documentation/media/uapi/v4l/buffer.rst | 13 ++++++++++--- Documentation/media/uapi/v4l/crop.rst | 12 +++++++++--- Documentation/media/uapi/v4l/dev-codec.rst | 4 +++- Documentation/media/uapi/v4l/dev-osd.rst | 4 +++- Documentation/media/uapi/v4l/dev-overlay.rst | 8 ++++++-- Documentation/media/uapi/v4l/dev-rds.rst | 4 +++- Documentation/media/uapi/v4l/extended-controls.rst | 4 +++- Documentation/media/uapi/v4l/func-mmap.rst | 4 +++- Documentation/media/uapi/v4l/pixfmt-006.rst | 4 +++- Documentation/media/uapi/v4l/pixfmt-007.rst | 12 +++++++++--- Documentation/media/uapi/v4l/pixfmt-sbggr16.rst | 4 +++- Documentation/media/uapi/v4l/pixfmt-y16-be.rst | 4 +++- Documentation/media/uapi/v4l/pixfmt-y16.rst | 4 +++- Documentation/media/uapi/v4l/standard.rst | 4 +++- Documentation/media/uapi/v4l/tuner.rst | 4 +++- Documentation/media/uapi/v4l/userp.rst | 4 +++- Documentation/media/uapi/v4l/vidioc-dv-timings-cap.rst | 4 +++- Documentation/media/uapi/v4l/vidioc-enum-dv-timings.rst | 4 +++- Documentation/media/uapi/v4l/vidioc-enum-fmt.rst | 9 ++++++--- .../media/uapi/v4l/vidioc-enum-frameintervals.rst | 4 +++- Documentation/media/uapi/v4l/vidioc-enum-framesizes.rst | 4 +++- Documentation/media/uapi/v4l/vidioc-enum-freq-bands.rst | 4 +++- Documentation/media/uapi/v4l/vidioc-enumaudioout.rst | 4 +++- Documentation/media/uapi/v4l/vidioc-g-audioout.rst | 4 +++- Documentation/media/uapi/v4l/vidioc-g-edid.rst | 4 +++- Documentation/media/uapi/v4l/vidioc-g-ext-ctrls.rst | 8 ++++++-- Documentation/media/uapi/v4l/vidioc-g-modulator.rst | 4 +++- Documentation/media/uapi/v4l/vidioc-g-sliced-vbi-cap.rst | 4 +++- Documentation/media/uapi/v4l/vidioc-g-tuner.rst | 8 ++++++-- Documentation/media/uapi/v4l/vidioc-qbuf.rst | 4 +++- Documentation/media/uapi/v4l/vidioc-query-dv-timings.rst | 4 +++- Documentation/media/uapi/v4l/vidioc-queryctrl.rst | 16 ++++++++++++---- Documentation/media/uapi/v4l/vidioc-querystd.rst | 4 +++- Documentation/media/uapi/v4l/vidioc-streamon.rst | 4 +++- Documentation/media/uapi/v4l/vidioc-subscribe-event.rst | 4 +++- Documentation/media/v4l-drivers/bttv.rst | 1 + 56 files changed, 206 insertions(+), 69 deletions(-)
Documentation/media/uapi/cec/cec-func-close.rst +3 -1
@@ -32,7 +32,9 @@ Arguments Description =========== -.. note:: This documents the proposed CEC API. This API is not yet finalized +.. note:: + + This documents the proposed CEC API. This API is not yet finalized and is currently only available as a staging kernel module. Closes the cec device. Resources associated with the file descriptor are
Documentation/media/uapi/cec/cec-func-ioctl.rst +3 -1
@@ -38,7 +38,9 @@ Arguments Description =========== -.. note:: This documents the proposed CEC API. This API is not yet finalized +.. note:: + + This documents the proposed CEC API. This API is not yet finalized and is currently only available as a staging kernel module. The :c:func:`ioctl()` function manipulates cec device parameters. The
Documentation/media/uapi/cec/cec-func-open.rst +3 -1
@@ -45,7 +45,9 @@ Arguments Description =========== -.. note:: This documents the proposed CEC API. This API is not yet finalized +.. note:: + + This documents the proposed CEC API. This API is not yet finalized and is currently only available as a staging kernel module. To open a cec device applications call :c:func:`open()` with the
Documentation/media/uapi/cec/cec-func-poll.rst +3 -1
@@ -29,7 +29,9 @@ Arguments Description =========== -.. note:: This documents the proposed CEC API. This API is not yet finalized +.. note:: + + This documents the proposed CEC API. This API is not yet finalized and is currently only available as a staging kernel module. With the :c:func:`poll()` function applications can wait for CEC
Documentation/media/uapi/cec/cec-intro.rst +3 -1
@@ -3,7 +3,9 @@ Introduction ============ -.. note:: This documents the proposed CEC API. This API is not yet finalized +.. note:: + + This documents the proposed CEC API. This API is not yet finalized and is currently only available as a staging kernel module. HDMI connectors provide a single pin for use by the Consumer Electronics
Documentation/media/uapi/cec/cec-ioc-adap-g-caps.rst +3 -1
@@ -31,7 +31,9 @@ Arguments Description =========== -.. note:: This documents the proposed CEC API. This API is not yet finalized +.. note:: + + This documents the proposed CEC API. This API is not yet finalized and is currently only available as a staging kernel module. All cec devices must support :ref:`ioctl CEC_ADAP_G_CAPS <CEC_ADAP_G_CAPS>`. To query
Documentation/media/uapi/cec/cec-ioc-adap-g-log-addrs.rst +3 -1
@@ -35,7 +35,9 @@ Arguments Description =========== -.. note:: This documents the proposed CEC API. This API is not yet finalized +.. note:: + + This documents the proposed CEC API. This API is not yet finalized and is currently only available as a staging kernel module. To query the current CEC logical addresses, applications call
Documentation/media/uapi/cec/cec-ioc-adap-g-phys-addr.rst +3 -1
@@ -34,7 +34,9 @@ Arguments Description =========== -.. note:: This documents the proposed CEC API. This API is not yet finalized +.. note:: + + This documents the proposed CEC API. This API is not yet finalized and is currently only available as a staging kernel module. To query the current physical address applications call
Documentation/media/uapi/cec/cec-ioc-dqevent.rst +3 -1
@@ -32,7 +32,9 @@ Arguments Description =========== -.. note:: This documents the proposed CEC API. This API is not yet finalized +.. note:: + + This documents the proposed CEC API. This API is not yet finalized and is currently only available as a staging kernel module. CEC devices can send asynchronous events. These can be retrieved by
Documentation/media/uapi/cec/cec-ioc-g-mode.rst +3 -1
@@ -30,7 +30,9 @@ Arguments Description =========== -.. note:: This documents the proposed CEC API. This API is not yet finalized +.. note:: + + This documents the proposed CEC API. This API is not yet finalized and is currently only available as a staging kernel module. By default any filehandle can use :ref:`CEC_TRANSMIT`, but in order to prevent
Documentation/media/uapi/cec/cec-ioc-receive.rst +3 -1
@@ -33,7 +33,9 @@ Arguments Description =========== -.. note:: This documents the proposed CEC API. This API is not yet finalized +.. note:: + + This documents the proposed CEC API. This API is not yet finalized and is currently only available as a staging kernel module. To receive a CEC message the application has to fill in the
Documentation/media/uapi/dvb/dvb-fe-read-status.rst +3 -1
@@ -17,7 +17,9 @@ using :ref:`FE_READ_STATUS`. Signal statistics are provided via :ref:`FE_GET_PROPERTY`. -.. note:: Most statistics require the demodulator to be fully locked +.. note:: + + Most statistics require the demodulator to be fully locked (e. g. with FE_HAS_LOCK bit set). See :ref:`Frontend statistics indicators <frontend-stat-properties>` for more details.
Documentation/media/uapi/dvb/dvbapi.rst +3 -1
@@ -8,7 +8,9 @@ Part II - Digital TV API ######################## -.. note:: This API is also known as **DVB API**, although it is generic +.. note:: + + This API is also known as **DVB API**, although it is generic enough to support all digital TV standards. **Version 5.10**
Documentation/media/uapi/dvb/dvbproperty.rst +3 -1
@@ -20,7 +20,9 @@ Also, the union didn't have any space left to be expanded without breaking userspace. So, the decision was to deprecate the legacy union/struct based approach, in favor of a properties set approach. -.. note:: On Linux DVB API version 3, setting a frontend were done via +.. note:: + + On Linux DVB API version 3, setting a frontend were done via :ref:`struct dvb_frontend_parameters <dvb-frontend-parameters>`. This got replaced on version 5 (also called "S2API", as this API were added originally_enabled to provide support for DVB-S2), because the
Documentation/media/uapi/dvb/examples.rst +3 -1
@@ -9,7 +9,9 @@ Examples In this section we would like to present some examples for using the DVB API. -..note:: This section is out of date, and the code below won't even +..note:: + + This section is out of date, and the code below won't even compile. Please refer to the `libdvbv5 <https://linuxtv.org/docs/libdvbv5/index.html>`__ for updated/recommended examples.
Documentation/media/uapi/dvb/fe-get-info.rst +3 -1
@@ -144,7 +144,9 @@ struct dvb_frontend_info - Capabilities supported by the frontend -.. note:: The frequencies are specified in Hz for Terrestrial and Cable +.. note:: + + The frequencies are specified in Hz for Terrestrial and Cable systems. They're specified in kHz for Satellite systems
Documentation/media/uapi/dvb/fe-read-status.rst +3 -1
@@ -40,7 +40,9 @@ used to check about the locking status of the frontend after being tuned. The ioctl takes a pointer to an integer where the status will be written. -.. note:: The size of status is actually sizeof(enum fe_status), with +.. note:: + + The size of status is actually sizeof(enum fe_status), with varies according with the architecture. This needs to be fixed in the future.
Documentation/media/uapi/dvb/frontend.rst +3 -1
@@ -29,7 +29,9 @@ The frontend can be accessed through ``/dev/dvb/adapter?/frontend?``. Data types and ioctl definitions can be accessed by including ``linux/dvb/frontend.h`` in your application. -.. note:: Transmission via the internet (DVB-IP) is not yet handled by this +.. note:: + + Transmission via the internet (DVB-IP) is not yet handled by this API but a future extension is possible. On Satellite systems, the API support for the Satellite Equipment
Documentation/media/uapi/rc/lirc-set-wideband-receiver.rst +3 -1
@@ -42,7 +42,9 @@ that prevents them to be used with some remotes. Wide band receiver might also be more precise. On the other hand its disadvantage it usually reduced range of reception. -.. note:: Wide band receiver might be implictly enabled if you enable +.. note:: + + Wide band receiver might be implictly enabled if you enable carrier reports. In that case it will be disabled as soon as you disable carrier reports. Trying to disable wide band receiver while carrier reports are active will do nothing.
Documentation/media/uapi/v4l/audio.rst +3 -1
@@ -37,7 +37,9 @@ The :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` and :ref:`VIDIOC_G_AUDOUT <VIDIOC_G_AUDOUT>` ioctls report the current audio input and output, respectively. -.. note:: Note that, unlike :ref:`VIDIOC_G_INPUT <VIDIOC_G_INPUT>` and +.. note:: + + Note that, unlike :ref:`VIDIOC_G_INPUT <VIDIOC_G_INPUT>` and :ref:`VIDIOC_G_OUTPUT <VIDIOC_G_OUTPUT>` these ioctls return a structure as :ref:`VIDIOC_ENUMAUDIO` and :ref:`VIDIOC_ENUMAUDOUT <VIDIOC_ENUMAUDOUT>` do, not just an index.
Documentation/media/uapi/v4l/buffer.rst +10 -3
@@ -166,12 +166,15 @@ struct v4l2_buffer output device because the application did not pass new data in time. - .. note:: This may count the frames received e.g. over USB, without + .. note:: + + This may count the frames received e.g. over USB, without taking into account the frames dropped by the remote hardware due to limited compression throughput or bus bandwidth. These devices identify by not enumerating any video standards, see :ref:`standard`. + - .. row 10 - __u32
@@ -299,7 +302,9 @@ struct v4l2_plane ``bytesused`` will be set to the size of the plane (see the ``length`` field of this struct) by the driver. - .. note:: Note that the actual image data starts at ``data_offset`` + .. note:: + + Note that the actual image data starts at ``data_offset`` which may not be 0. - .. row 2
@@ -371,7 +376,9 @@ struct v4l2_plane field when ``type`` refers to a capture stream, applications when it refers to an output stream. - .. note:: That data_offset is included in ``bytesused``. So the + .. note:: + + That data_offset is included in ``bytesused``. So the size of the image in the plane is ``bytesused``-``data_offset`` at offset ``data_offset`` from the start of the plane.
Documentation/media/uapi/v4l/crop.rst +9 -3
@@ -15,7 +15,9 @@ offset into a video signal. Applications can use the following API to select an area in the video signal, query the default area and the hardware limits. -.. note:: Despite their name, the :ref:`VIDIOC_CROPCAP <VIDIOC_CROPCAP>`, +.. note:: + + Despite their name, the :ref:`VIDIOC_CROPCAP <VIDIOC_CROPCAP>`, :ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` and :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` ioctls apply to input as well as output devices.
@@ -38,7 +40,9 @@ support scaling or the :ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` and :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` ioctls. Their size (and position where applicable) will be fixed in this case. -.. note:: All capture and output devices must support the +.. note:: + + All capture and output devices must support the :ref:`VIDIOC_CROPCAP <VIDIOC_CROPCAP>` ioctl such that applications can determine if scaling takes place.
@@ -144,7 +148,9 @@ reopening a device, such that piping data into or out of a device will work without special preparations. More advanced applications should ensure the parameters are suitable before starting I/O. -.. note:: On the next two examples, a video capture device is assumed; +.. note:: + + On the next two examples, a video capture device is assumed; change ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` for other types of device. Example: Resetting the cropping parameters
Documentation/media/uapi/v4l/dev-codec.rst +3 -1
@@ -21,7 +21,9 @@ for both capture and output to start the codec. Video compression codecs use the MPEG controls to setup their codec parameters -.. note:: The MPEG controls actually support many more codecs than +.. note:: + + The MPEG controls actually support many more codecs than just MPEG. See :ref:`mpeg-controls`. Memory-to-memory devices can often be used as a shared resource: you can
Documentation/media/uapi/v4l/dev-osd.rst +3 -1
@@ -16,7 +16,9 @@ this interface, which borrows structures and ioctls of the The OSD function is accessible through the same character special file as the :ref:`Video Output <capture>` function. -.. note:: The default function of such a ``/dev/video`` device is video +.. note:: + + The default function of such a ``/dev/video`` device is video capturing or output. The OSD function is only available after calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.
Documentation/media/uapi/v4l/dev-overlay.rst +6 -2
@@ -19,7 +19,9 @@ video into a window. Video overlay devices are accessed through the same character special files as :ref:`video capture <capture>` devices. -.. note:: The default function of a ``/dev/video`` device is video +.. note:: + + The default function of a ``/dev/video`` device is video capturing. The overlay function is only available after calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.
@@ -236,7 +238,9 @@ exceeded are undefined. [#f3]_ :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`, :ref:`framebuffer-flags`). - .. note:: This field was added in Linux 2.6.23, extending the + .. note:: + + This field was added in Linux 2.6.23, extending the structure. However the :ref:`VIDIOC_[G|S|TRY]_FMT <VIDIOC_G_FMT>` ioctls, which take a pointer to a :ref:`v4l2_format <v4l2-format>` parent structure with padding bytes at the end, are not affected.
Documentation/media/uapi/v4l/dev-rds.rst +3 -1
@@ -14,7 +14,9 @@ at devices capable of receiving and/or transmitting RDS information. For more information see the core RDS standard :ref:`iec62106` and the RBDS standard :ref:`nrsc4`. -.. note:: Note that the RBDS standard as is used in the USA is almost +.. note:: + + Note that the RBDS standard as is used in the USA is almost identical to the RDS standard. Any RDS decoder/encoder can also handle RBDS. Only some of the fields have slightly different meanings. See the RBDS standard for more information.
Documentation/media/uapi/v4l/extended-controls.rst +3 -1
@@ -184,7 +184,9 @@ Codec Control Reference Below all controls within the Codec control class are described. First the generic controls, then controls specific for certain hardware. -.. note:: These controls are applicable to all codecs and not just MPEG. The +.. note:: + + These controls are applicable to all codecs and not just MPEG. The defines are prefixed with V4L2_CID_MPEG/V4L2_MPEG as the controls were originally made for MPEG codecs and later extended to cover all encoding formats.
Documentation/media/uapi/v4l/func-mmap.rst +3 -1
@@ -78,7 +78,9 @@ Arguments ``MAP_SHARED`` allows applications to share the mapped memory with other (e. g. child-) processes. - .. note:: The Linux ``videobuf`` module which is used by some + .. note:: + + The Linux ``videobuf`` module which is used by some drivers supports only ``MAP_SHARED``. ``MAP_PRIVATE`` requests copy-on-write semantics. V4L2 applications should not set the ``MAP_PRIVATE``, ``MAP_DENYWRITE``, ``MAP_EXECUTABLE`` or ``MAP_ANON``
Documentation/media/uapi/v4l/pixfmt-006.rst +3 -1
@@ -19,7 +19,9 @@ colorspace field of struct :ref:`v4l2_pix_format <v4l2-pix-format>` or struct :ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>` needs to be filled in. -.. note:: The default R'G'B' quantization is full range for all +.. note:: + + The default R'G'B' quantization is full range for all colorspaces except for BT.2020 which uses limited range R'G'B' quantization.
Documentation/media/uapi/v4l/pixfmt-007.rst +9 -3
@@ -569,7 +569,9 @@ projectors that use the DCI-P3 colorspace. The default transfer function is ``V4L2_XFER_FUNC_DCI_P3``. The default Y'CbCr encoding is ``V4L2_YCBCR_ENC_709``. -.. note:: Note that this colorspace does not specify a +.. note:: + + Note that this colorspace does not specify a Y'CbCr encoding since it is not meant to be encoded to Y'CbCr. So this default Y'CbCr encoding was picked because it is the HDTV encoding. The default Y'CbCr quantization is limited range. The chromaticities of the
@@ -795,7 +797,9 @@ reference are: - 0.316 -.. note:: This colorspace uses Illuminant C instead of D65 as the white +.. note:: + + This colorspace uses Illuminant C instead of D65 as the white reference. To correctly convert an image in this colorspace to another that uses D65 you need to apply a chromatic adaptation algorithm such as the Bradford method.
@@ -941,7 +945,9 @@ reference are identical to sRGB. The transfer function use is with full range quantization where Y' is scaled to [0…255] and Cb/Cr are scaled to [-128…128] and then clipped to [-128…127]. -.. note:: The JPEG standard does not actually store colorspace +.. note:: + + The JPEG standard does not actually store colorspace information. So if something other than sRGB is used, then the driver will have to set that information explicitly. Effectively ``V4L2_COLORSPACE_JPEG`` can be considered to be an abbreviation for
Documentation/media/uapi/v4l/pixfmt-sbggr16.rst +3 -1
@@ -19,7 +19,9 @@ This format is similar to has a depth of 16 bits. The least significant byte is stored at lower memory addresses (little-endian). -..note:: The actual sampling precision may be lower than 16 bits, +..note:: + + The actual sampling precision may be lower than 16 bits, for example 10 bits per pixel with values in tange 0 to 1023. **Byte Order.**
Documentation/media/uapi/v4l/pixfmt-y16-be.rst +3 -1
@@ -17,7 +17,9 @@ Description This is a grey-scale image with a depth of 16 bits per pixel. The most significant byte is stored at lower memory addresses (big-endian). -.. note:: Tthe actual sampling precision may be lower than 16 bits, for +.. note:: + + The actual sampling precision may be lower than 16 bits, for example 10 bits per pixel with values in range 0 to 1023. **Byte Order.**
Documentation/media/uapi/v4l/pixfmt-y16.rst +3 -1
@@ -17,7 +17,9 @@ Description This is a grey-scale image with a depth of 16 bits per pixel. The least significant byte is stored at lower memory addresses (little-endian). -.. note:: The actual sampling precision may be lower than 16 bits, for +.. note:: + + The actual sampling precision may be lower than 16 bits, for example 10 bits per pixel with values in range 0 to 1023. **Byte Order.**
Documentation/media/uapi/v4l/standard.rst +3 -1
@@ -41,7 +41,9 @@ output applications call the :ref:`VIDIOC_G_STD <VIDIOC_G_STD>` and *received* standard can be sensed with the :ref:`VIDIOC_QUERYSTD` ioctl. -..note:: The parameter of all these ioctls is a pointer to a +..note:: + + The parameter of all these ioctls is a pointer to a :ref:`v4l2_std_id <v4l2-std-id>` type (a standard set), *not* an index into the standard enumeration. Drivers must implement all video standard ioctls when the device has one or more video inputs or outputs.
Documentation/media/uapi/v4l/tuner.rst +3 -1
@@ -28,7 +28,9 @@ struct :ref:`v4l2_tuner <v4l2-tuner>` returned by :ref:`VIDIOC_G_TUNER <VIDIOC_G also contains signal status information applicable when the tuner of the current video or radio input is queried. -.. note:: :ref:`VIDIOC_S_TUNER <VIDIOC_G_TUNER>` does not switch the +.. note:: + + :ref:`VIDIOC_S_TUNER <VIDIOC_G_TUNER>` does not switch the current tuner, when there is more than one at all. The tuner is solely determined by the current video input. Drivers must support both ioctls and set the ``V4L2_CAP_TUNER`` flag in the struct :ref:`v4l2_capability
Documentation/media/uapi/v4l/userp.rst +3 -1
@@ -88,7 +88,9 @@ To start and stop capturing or output applications call the :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` and :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctl. -.. note:: ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` removes all buffers from +.. note:: + + ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` removes all buffers from both queues and unlocks all buffers as a side effect. Since there is no notion of doing anything "now" on a multitasking system, if an application needs to synchronize with another event it should examine
Documentation/media/uapi/v4l/vidioc-dv-timings-cap.rst +3 -1
@@ -39,7 +39,9 @@ initialize the ``pad`` field to 0, zero the reserved array of struct ``VIDIOC_DV_TIMINGS_CAP`` ioctl on a video node and the driver will fill in the structure. -.. note:: Drivers may return different values after +.. note:: + + Drivers may return different values after switching the video input or output. When implemented by the driver DV capabilities of subdevices can be
Documentation/media/uapi/v4l/vidioc-enum-dv-timings.rst +3 -1
@@ -49,7 +49,9 @@ error code when the index is out of bounds. To enumerate all supported DV timings, applications shall begin at index zero, incrementing by one until the driver returns ``EINVAL``. -.. note:: Drivers may enumerate a different set of DV timings after +.. note:: + + Drivers may enumerate a different set of DV timings after switching the video input or output. When implemented by the driver DV timings of subdevices can be queried
Documentation/media/uapi/v4l/vidioc-enum-fmt.rst +6 -3
@@ -40,7 +40,9 @@ fill the rest of the structure or return an ``EINVAL`` error code. All formats are enumerable by beginning at index zero and incrementing by one until ``EINVAL`` is returned. -.. note:: After switching input or output the list of enumerated image +.. note:: + + After switching input or output the list of enumerated image formats may be different.
@@ -51,7 +53,6 @@ one until ``EINVAL`` is returned. :stub-columns: 0 :widths: 1 1 2 - - .. row 1 - __u32
@@ -113,7 +114,9 @@ one until ``EINVAL`` is returned. Several image formats are already defined by this specification in :ref:`pixfmt`. - .. attention:: These codes are not the same as those used + .. attention:: + + These codes are not the same as those used in the Windows world. - .. row 7
Documentation/media/uapi/v4l/vidioc-enum-frameintervals.rst +3 -1
@@ -73,7 +73,9 @@ the device supports. Only for the ``V4L2_FRMIVAL_TYPE_DISCRETE`` type does it make sense to increase the index value to receive more frame intervals. -.. note:: The order in which the frame intervals are returned has no +.. note:: + + The order in which the frame intervals are returned has no special meaning. In particular does it not say anything about potential default frame intervals.
Documentation/media/uapi/v4l/vidioc-enum-framesizes.rst +3 -1
@@ -72,7 +72,9 @@ the ``type`` field to determine the type of frame size enumeration the device supports. Only for the ``V4L2_FRMSIZE_TYPE_DISCRETE`` type does it make sense to increase the index value to receive more frame sizes. -.. note:: The order in which the frame sizes are returned has no special +.. note:: + + The order in which the frame sizes are returned has no special meaning. In particular does it not say anything about potential default format sizes.
Documentation/media/uapi/v4l/vidioc-enum-freq-bands.rst +3 -1
@@ -129,7 +129,9 @@ of the corresponding tuner/modulator is set. - :cspan:`2` The supported modulation systems of this frequency band. See :ref:`band-modulation`. - .. note:: Currently only one modulation system per frequency band + .. note:: + + Currently only one modulation system per frequency band is supported. More work will need to be done if multiple modulation systems are possible. Contact the linux-media mailing list
Documentation/media/uapi/v4l/vidioc-enumaudioout.rst +3 -1
@@ -41,7 +41,9 @@ structure or return an ``EINVAL`` error code when the index is out of bounds. To enumerate all audio outputs applications shall begin at index zero, incrementing by one until the driver returns ``EINVAL``. -.. note:: Connectors on a TV card to loop back the received audio signal +.. note:: + + Connectors on a TV card to loop back the received audio signal to a sound card are not audio outputs in this sense. See :ref:`VIDIOC_G_AUDIOout <VIDIOC_G_AUDOUT>` for a description of struct
Documentation/media/uapi/v4l/vidioc-g-audioout.rst +3 -1
@@ -51,7 +51,9 @@ return the ``EINVAL`` error code when the index is out of bounds. This is a write-only ioctl, it does not return the current audio output attributes as ``VIDIOC_G_AUDOUT`` does. -.. note:: Connectors on a TV card to loop back the received audio signal +.. note:: + + Connectors on a TV card to loop back the received audio signal to a sound card are not audio outputs in this sense.
Documentation/media/uapi/v4l/vidioc-g-edid.rst +3 -1
@@ -67,7 +67,9 @@ total number of available EDID blocks and it will return 0 without copying any data. This is an easy way to discover how many EDID blocks there are. -.. note:: If there are no EDID blocks available at all, then +.. note:: + + If there are no EDID blocks available at all, then the driver will set ``blocks`` to 0 and it returns 0. To set the EDID blocks of a receiver the application has to fill in the
Documentation/media/uapi/v4l/vidioc-g-ext-ctrls.rst +6 -2
@@ -127,7 +127,9 @@ still cause this situation. to a value large enough to store the payload result and ``ENOSPC`` is returned. - .. note:: For string controls, this ``size`` field should + .. note:: + + For string controls, this ``size`` field should not be confused with the length of the string. This field refers to the size of the memory that contains the string. The actual *length* of the string may well be much smaller.
@@ -265,7 +267,9 @@ still cause this situation. control and ``V4L2_CTRL_WHICH_DEF_VAL`` will return the default value of the control. - .. note:: You can only get the default value of the control, + .. note:: + + You can only get the default value of the control, you cannot set or try it. For backwards compatibility you can also use a control class here
Documentation/media/uapi/v4l/vidioc-g-modulator.rst +3 -1
@@ -130,7 +130,9 @@ To change the radio frequency the shall be modulated. It contains a set of flags as defined in :ref:`modulator-txsubchans`. - .. note:: The tuner ``rxsubchans`` flags are reused, but the + .. note:: + + The tuner ``rxsubchans`` flags are reused, but the semantics are different. Video output devices are assumed to have an analog or PCM audio input with 1-3 channels. The ``txsubchans`` flags select one or more channels
Documentation/media/uapi/v4l/vidioc-g-sliced-vbi-cap.rst +3 -1
@@ -40,7 +40,9 @@ output device, applications initialize the ``type`` field of a struct driver fills in the remaining fields or returns an ``EINVAL`` error code if the sliced VBI API is unsupported or ``type`` is invalid. -.. note:: The ``type`` field was added, and the ioctl changed from read-only +.. note:: + + The ``type`` field was added, and the ioctl changed from read-only to write-read, in Linux 2.6.19.
Documentation/media/uapi/v4l/vidioc-g-tuner.rst +6 -2
@@ -391,7 +391,9 @@ To change the radio frequency the carrier for a monaural secondary language. Only ``V4L2_TUNER_ANALOG_TV`` tuners can have this capability. - .. note:: The ``V4L2_TUNER_CAP_LANG2`` and ``V4L2_TUNER_CAP_SAP`` + .. note:: + + The ``V4L2_TUNER_CAP_LANG2`` and ``V4L2_TUNER_CAP_SAP`` flags are synonyms. ``V4L2_TUNER_CAP_SAP`` applies when the tuner supports the ``V4L2_STD_NTSC_M`` video standard.
@@ -502,7 +504,9 @@ To change the radio frequency the - The tuner receives a Second Audio Program. - .. note:: The ``V4L2_TUNER_SUB_LANG2`` and ``V4L2_TUNER_SUB_SAP`` + .. note:: + + The ``V4L2_TUNER_SUB_LANG2`` and ``V4L2_TUNER_SUB_SAP`` flags are synonyms. The ``V4L2_TUNER_SUB_SAP`` flag applies when the current video standard is ``V4L2_STD_NTSC_M``.
Documentation/media/uapi/v4l/vidioc-qbuf.rst +3 -1
@@ -137,7 +137,9 @@ EIO ``VIDIOC_DQBUF`` failed due to an internal error. Can also indicate temporary problems like signal loss. - .. note:: The driver might dequeue an (empty) buffer despite returning + .. note:: + + The driver might dequeue an (empty) buffer despite returning an error, or even stop capturing. Reusing such buffer may be unsafe though and its details (e.g. ``index``) may not be returned either. It is recommended that drivers indicate recoverable errors by setting
Documentation/media/uapi/v4l/vidioc-query-dv-timings.rst +3 -1
@@ -39,7 +39,9 @@ similar to sensing the video standard. To do so, applications call :ref:`v4l2_dv_timings <v4l2-dv-timings>`. Once the hardware detects the timings, it will fill in the timings structure. -.. note:: Drivers shall *not* switch timings automatically if new +.. note:: + + Drivers shall *not* switch timings automatically if new timings are detected. Instead, drivers should send the ``V4L2_EVENT_SOURCE_CHANGE`` event (if they support this) and expect that userspace will take action by calling :ref:`VIDIOC_QUERY_DV_TIMINGS`.
Documentation/media/uapi/v4l/vidioc-queryctrl.rst +12 -4
@@ -84,7 +84,9 @@ fills the rest of the structure or returns an ``EINVAL`` error code when the :ref:`v4l2_queryctrl <v4l2-queryctrl>` ``minimum`` to ``maximum``, inclusive. -.. note:: It is possible for ``VIDIOC_QUERYMENU`` to return +.. note:: + + It is possible for ``VIDIOC_QUERYMENU`` to return an ``EINVAL`` error code for some indices between ``minimum`` and ``maximum``. In that case that particular menu item is not supported by this driver. Also note that the ``minimum`` value is not necessarily 0.
@@ -188,7 +190,9 @@ See also the examples in :ref:`control`. ``_BITMASK``, ``_MENU`` or ``_INTEGER_MENU`` control. Not valid for other types of controls. - .. note:: Drivers reset controls to their default value only when + .. note:: + + Drivers reset controls to their default value only when the driver is first loaded, never afterwards. - .. row 8
@@ -306,7 +310,9 @@ See also the examples in :ref:`control`. ``_BOOLEAN``, ``_BITMASK``, ``_MENU``, ``_INTEGER_MENU``, ``_U8`` or ``_U16`` control. Not valid for other types of controls. - .. note:: Drivers reset controls to their default value only when + .. note:: + + Drivers reset controls to their default value only when the driver is first loaded, never afterwards. - .. row 8
@@ -728,7 +734,9 @@ See also the examples in :ref:`control`. case the hardware calculates the gain value based on the lighting conditions which can change over time. - .. note:: Setting a new value for a volatile control will have no + .. note:: + + Setting a new value for a volatile control will have no effect and no ``V4L2_EVENT_CTRL_CH_VALUE`` will be sent, unless the ``V4L2_CTRL_FLAG_EXECUTE_ON_WRITE`` flag (see below) is also set. Otherwise the new value will just be ignored.
Documentation/media/uapi/v4l/vidioc-querystd.rst +3 -1
@@ -43,7 +43,9 @@ will return V4L2_STD_UNKNOWN. When detection is not possible or fails, the set must contain all standards supported by the current video input or output. -.. note:: Drivers shall *not* switch the video standard +.. note:: + + Drivers shall *not* switch the video standard automatically if a new video standard is detected. Instead, drivers should send the ``V4L2_EVENT_SOURCE_CHANGE`` event (if they support this) and expect that userspace will take action by calling
Documentation/media/uapi/v4l/vidioc-streamon.rst +3 -1
@@ -76,7 +76,9 @@ then 0 is returned. Nothing happens in the case of ``VIDIOC_STREAMON``, but ``VIDIOC_STREAMOFF`` will return queued buffers to their starting state as mentioned above. -.. note:: Applications can be preempted for unknown periods right before +.. note:: + + Applications can be preempted for unknown periods right before or after the ``VIDIOC_STREAMON`` or ``VIDIOC_STREAMOFF`` calls, there is no notion of starting or stopping "now". Buffer timestamps can be used to synchronize with other events.
Documentation/media/uapi/v4l/vidioc-subscribe-event.rst +3 -1
@@ -54,7 +54,9 @@ using the :ref:`VIDIOC_DQEVENT` ioctl. - Type of the event, see :ref:`event-type`. - .. note:: ``V4L2_EVENT_ALL`` can be used with + .. note:: + + ``V4L2_EVENT_ALL`` can be used with :ref:`VIDIOC_UNSUBSCRIBE_EVENT <VIDIOC_SUBSCRIBE_EVENT>` for unsubscribing all events at once.
Documentation/media/v4l-drivers/bttv.rst +1 -0
@@ -586,6 +586,7 @@ Cards ----- .. note:: + For a more updated list, please check https://linuxtv.org/wiki/index.php/Hardware_Device_Information
Signature · 1 line
2.7.4
RFC PATCH v2 9/9 HACK: make pdfdocs build with media books
In reply to Mauro Carvalho Chehab---------------------------------
PLEASE DO NOT APPLY THIS UPSTREAM
---------------------------------
This hack addresses two issues with pdf generation from media books:
1) Sphinx doesn't do the right thing if a block of code is inside a table. This sounds a Sphinx bug. Perhaps it can be fixed by preloading some LaTeX code.
2) the file output doesn't do the right thing for PDF. This is likely due to the lack of some escape chars when generating the output rst file.
This hack makes the document to build fully.
Please notice that tables are not built well yet, as most are too big. We can very likely fix several of them by rotating the page to landscape.
--- Documentation/Makefile.sphinx | 1 + Documentation/media/uapi/v4l/vidioc-enum-fmt.rst | 8 ++++---- Documentation/media/uapi/v4l/vidioc-querycap.rst | 20 ++++++++++---------- 3 files changed, 15 insertions(+), 14 deletions(-)
Documentation/Makefile.sphinx +1 -0
@@ -49,6 +49,7 @@ ifeq ($(HAVE_PDFLATEX),0) @echo " SKIP Sphinx $@ target." else # HAVE_PDFLATEX $(call cmd,sphinx,latex) + (cd $(BUILDDIR); for i in *.rst; do echo >$$i; done) $(Q)$(MAKE) PDFLATEX=xelatex -C $(BUILDDIR)/latex endif # HAVE_PDFLATEX
Documentation/media/uapi/v4l/vidioc-enum-fmt.rst +4 -4
@@ -107,10 +107,10 @@ one until ``EINVAL`` is returned. .. _v4l2-fourcc: - .. code-block:: c - - #define v4l2_fourcc(a,b,c,d) (((__u32)(a)<<0)|((__u32)(b)<<8)|((__u32)(c)<<16)|((__u32)(d)<<24)) - +.. .. code-block:: c +.. +.. #define v4l2_fourcc(a,b,c,d) (((__u32)(a)<<0)|((__u32)(b)<<8)|((__u32)(c)<<16)|((__u32)(d)<<24)) +.. Several image formats are already defined by this specification in :ref:`pixfmt`.
Documentation/media/uapi/v4l/vidioc-querycap.rst +10 -10
@@ -118,16 +118,16 @@ specification the ioctl returns an ``EINVAL`` error code. - :cspan:`2` - .. code-block:: c - - #define KERNEL_VERSION(a,b,c) (((a) << 16) + ((b) << 8) + (c)) - - __u32 version = KERNEL_VERSION(0, 8, 1); - - printf ("Version: %u.%u.%u\\n", - (version >> 16) & 0xFF, - (version >> 8) & 0xFF, - version & 0xFF); +.. .. code-block:: c +.. +.. #define KERNEL_VERSION(a,b,c) (((a) << 16) + ((b) << 8) + (c)) +.. +.. __u32 version = KERNEL_VERSION(0, 8, 1); +.. +.. printf ("Version: %u.%u.%u\\n", +.. (version >> 16) & 0xFF, +.. (version >> 8) & 0xFF, +.. version & 0xFF); - .. row 6
Signature · 1 line
2.7.4