Fix PDF build errors
cover Fix PDF build errors
This series address a series of errors during PDF generation from media documentation.
Please notice that patch 2 carries on a PDF conversion from a PNG image, because Sphinx is not smart enough to do the convertion.
This is a temporary solution (That's why I'm marking this series as RFC).
I'm working on a more permanent access where the image format required by Sphinx for PDF output will be met.
Mauro Carvalho Chehab (4):
docs-rst: fix PDF build errors
[media] subdev-formats.rst: we need a pdf picture for bayer [media] subdev-formats.rst: don't use adjustbox on a longtable [media] subdev-formats.rst: add missing columns to tabularcolumns
Documentation/conf.py | 4 ++++ Documentation/media/index.rst | 5 ----- Documentation/media/uapi/v4l/subdev-formats.rst | 17 +++++++++++------ .../media/uapi/v4l/subdev-formats_files/bayer.pdf | Bin 0 -> 11131 bytes 4 files changed, 15 insertions(+), 11 deletions(-) create mode 100644 Documentation/media/uapi/v4l/subdev-formats_files/bayer.pdf
Signature · 1 line
2.7.4
RFC PATCH 1/4 docs-rst: fix PDF build errors
PDF build on Kernel 4.9-rc? returns an error. This is because we're re-defining a command too late. Move such redefinition to LaTeX preamble.
Tested by building the documentation on interactive mode:
make PDFLATEX=xelatex -C Documentation/output/./latex
--- Documentation/conf.py | 4 ++++ Documentation/media/index.rst | 5 ----- 2 files changed, 4 insertions(+), 5 deletions(-)
Documentation/conf.py +4 -0
@@ -332,6 +332,10 @@ latex_elements = { ''' } +# Fix reference escape troubles with Sphinx 1.4.x +if minor > 3: + latex_elements['preamble'] += '\\renewcommand*{\\DUrole}[2]{ #2 }' + # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, # author, documentclass [howto, manual, or own class]).
Documentation/media/index.rst +0 -5
@@ -1,11 +1,6 @@ Linux Media Subsystem Documentation =================================== -.. Sphinx 1.4.x has a definition for DUrole that doesn't work on alltt blocks -.. raw:: latex - - \renewcommand*{\DUrole}[2]{ #2 } - Contents: .. toctree::
Signature · 1 line
2.7.4
Re: [PATCH RFC 1/4] docs-rst: fix PDF build errors
Am 01.11.2016 um 23:44 schrieb Mauro Carvalho Chehab <[email protected]>:
Quoted 20 lines
PDF build on Kernel 4.9-rc? returns an error. This is because we're re-defining a command too late. Move such redefinition to LaTeX preamble.
Tested by building the documentation on interactive mode:
make PDFLATEX=xelatex -CDocumentation/output/./latexFixes e61a39baf74d ("[media] index.rst: Fix LaTeX error in interactive mode on Sphinx 1.4.x")Signed-off-by Mauro Carvalho Chehab <[email protected]>---
Documentation/conf.py| 4 ++++Documentation/media/index.rst| 5 -----2 files changed, 4 insertions(+), 5 deletions(-)Documentation/conf.py +0
-0
Documentation/conf.py latex_elements = { · line 337
Quoted 6 lines
Documentation/conf.py +3
-0@@ -332,6 +332,10 @@ latex_elements = { ''' } +# Fix reference escape troubles with Sphinx 1.4.x +if minor > 3: + latex_elements['preamble'] += '\\renewcommand*{\\DUrole}[2]{ #2 }'
For Sphinx's version detection we should also include the major version number e.g::
if major == 1 and minor > 3:
BTW: can you also fix ...
# The name of the math extension changed on Sphinx 1.4
-if minor > 3:
- extensions.append("sphinx.ext.imgmath")
-else:
+if major == 1 and minor < 4:
extensions.append("sphinx.ext.pngmath")
+else:
+ extensions.append("sphinx.ext.imgmath")
-- Markus --
Quoted 28 lines
Documentation/conf.py +1
-0+ # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, # author, documentclass [howto, manual, or own class]).Documentation/media/index.rst +0
-0@@ -1,11 +1,6 @@Linux Media Subsystem Documentation
===================================-.. Sphinx 1.4.x has a definition for DUrole that doesn't work on alltt blocks -.. raw:: latex
Documentation/media/index.rst +0
-3- - \renewcommand*{\DUrole}[2]{ #2 } -Contents:
.. toctree::
Signature · 7 lines
2.7.4 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH RFC 1/4] docs-rst: fix PDF build errors
In reply to Mauro Carvalho ChehabAm 01.11.2016 um 23:44 schrieb Mauro Carvalho Chehab <[email protected]>:
Quoted 20 lines
PDF build on Kernel 4.9-rc? returns an error. This is because we're re-defining a command too late. Move such redefinition to LaTeX preamble.
Tested by building the documentation on interactive mode:
make PDFLATEX=xelatex -CDocumentation/output/./latexFixes e61a39baf74d ("[media] index.rst: Fix LaTeX error in interactive mode on Sphinx 1.4.x")Signed-off-by Mauro Carvalho Chehab <[email protected]>---
Documentation/conf.py| 4 ++++Documentation/media/index.rst| 5 -----2 files changed, 4 insertions(+), 5 deletions(-)Documentation/conf.py +0
-0
Documentation/conf.py latex_elements = { · line 337
Quoted 6 lines
Documentation/conf.py +3
-0@@ -332,6 +332,10 @@ latex_elements = { ''' } +# Fix reference escape troubles with Sphinx 1.4.x +if minor > 3: + latex_elements['preamble'] += '\\renewcommand*{\\DUrole}[2]{ #2 }'
Sorry forget to mention: when adding content to the preamble I recommend to add a leading and trailing new-line.
-- Markus --
RFC PATCH 2/4 subdev-formats.rst: we need a pdf picture for bayer
In reply to Mauro Carvalho ChehabThe png picture is not ok on Sphinx 1.4.8.
--- Documentation/media/uapi/v4l/subdev-formats.rst | 4 +--- .../media/uapi/v4l/subdev-formats_files/bayer.pdf | Bin 0 -> 11131 bytes 2 files changed, 1 insertion(+), 3 deletions(-) create mode 100644 Documentation/media/uapi/v4l/subdev-formats_files/bayer.pdf
Documentation/media/uapi/v4l/subdev-formats.rst +1 -3
@@ -1515,13 +1515,11 @@ be named ``MEDIA_BUS_FMT_SRGGB10_2X8_PADHI_LE``. .. _bayer-patterns: .. figure:: subdev-formats_files/bayer.* - :alt: bayer.png + :alt: bayer.pdf / bayer.png :align: center **Figure 4.8 Bayer Patterns** - - The following table lists existing packed Bayer formats. The data organization is given as an example for the first pixel only.
Documentation/media/uapi/v4l/subdev-formats_files/bayer.pdf new file binary +0 -0
Signature · 1 line
2.7.4
Em Tue, 1 Nov 2016 16:44:09 -0600
Mauro Carvalho Chehab <[email protected]> escreveu:
Quoted 10 lines
This series address a series of errors during PDF generation from media documentation.
Please notice that patch 2 carries on a PDF conversion from a PNG image, because Sphinx is not smart enough to do the convertion.
This is a temporary solution (That's why I'm marking this series as RFC).
I'm working on a more permanent access where the image format
In time:
"more permanent solution"
Quoted 8 lines
required by Sphinx for PDF output will be met.
Mauro Carvalho Chehab (4):
docs-rst: fix PDF build errors
[media]subdev-formats.rst: we need a pdf picture for bayer [media]subdev-formats.rst: don't use adjustbox on a longtable [media]subdev-formats.rst: add missing columns to tabularcolumns
Quoted 7 lines
Documentation/conf.py | 4 ++++ Documentation/media/index.rst | 5 ----- Documentation/media/uapi/v4l/subdev-formats.rst | 17 +++++++++++------ .../media/uapi/v4l/subdev-formats_files/bayer.pdf | Bin 0 -> 11131 bytes 4 files changed, 15 insertions(+), 11 deletions(-) create mode 100644 Documentation/media/uapi/v4l/subdev-formats_files/bayer.pdf
Cheers,
Mauro
RFC PATCH 3/4 subdev-formats.rst: don't use adjustbox on a longtable
In reply to Mauro Carvalho Chehabadjustbox doesn't work on longtables. Also, this
causes an error on LaTeX in interactive mode.
So, use, instead, a tiny font.
--- Documentation/media/uapi/v4l/subdev-formats.rst | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-)
Documentation/media/uapi/v4l/subdev-formats.rst +9 -2
@@ -1524,9 +1524,16 @@ The following table lists existing packed Bayer formats. The data organization is given as an example for the first pixel only. +.. HACK: ideally, we would be using adjustbox here. However, Sphinx +.. is a very bad behaviored guy: if the table has more than 30 cols, +.. it switches to long table, and there's no way to override it. + + .. raw:: latex - \newline\newline\begin{adjustbox}{width=\columnwidth} + \begingroup + \tiny + \setlength{\tabcolsep}{2pt} .. tabularcolumns:: |p{7.6cm}|p{1.6cm}|p{0.7cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|
@@ -2312,7 +2319,7 @@ organization is given as an example for the first pixel only. .. raw:: latex - \end{adjustbox}\newline\newline + \endgroup Packed YUV Formats
Signature · 1 line
2.7.4
RFC PATCH 4/4 subdev-formats.rst: add missing columns to tabularcolumns
In reply to Mauro Carvalho ChehabThere are several missing columns on the size specification, causing LaTeX to complain on interactive mode.
--- Documentation/media/uapi/v4l/subdev-formats.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/media/uapi/v4l/subdev-formats.rst +1 -1
@@ -1535,7 +1535,7 @@ organization is given as an example for the first pixel only. \tiny \setlength{\tabcolsep}{2pt} -.. tabularcolumns:: |p{7.6cm}|p{1.6cm}|p{0.7cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}| +.. tabularcolumns:: |p{4.0cm}|p{0.7cm}|p{0.3cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| .. _v4l2-mbus-pixelcode-bayer:
Signature · 1 line
2.7.4
Quoted 8 lines · Mauro Carvalho Chehab
This series address a series of errors during PDF generation from media documentation.
Please notice that patch 2 carries on a PDF conversion from a PNG image, because Sphinx is not smart enough to do the convertion.
This is a temporary solution (That's why I'm marking this series as RFC).
This seems to work on top of docs-next.
...but it'll break again if we include the missing admin-guide in the build. :(
BR,
Jani.
Quoted 1 line
From
c296287c65f4b6ad6272171456dcf8508c92ae2fMon Sep 17 00:00:00 2001
From: Jani Nikula <[email protected]>
Date: Wed, 2 Nov 2016 13:05:59 +0200
Subject: [PATCH] Documentation/sphinx: include admin-guide in the latex/pdf
build
Organization: Intel Finland Oy - BIC 0357606-4 - Westendinkatu 7, 02160 Espoo
Cc: Jani Nikula <[email protected]>
Fix the warning:
WARNING: "latex_documents" config value references unknown document user/index
---
Sadly, this breaks the pdf build with:
! TeX capacity exceeded, sorry [main memory size=5000000]. \FV@Space ...ionary {\copy \sphinxvisiblespacebox
}{\sphinxafterbreak } {\ke...
l.3711 ...\PYG{n}{be} \PYG{n}{used} \PYG{n+nb}{to}
Output written on linux-user.pdf (15 pages).
Transcript written on linux-user.log.
Makefile:66: recipe for target 'linux-user.pdf' failed make[2]: *** [linux-user.pdf] Error 1 Documentation/Makefile.sphinx:83: recipe for target 'pdfdocs' failed make[1]: *** [pdfdocs] Error 2
Makefile:1442: recipe for target 'pdfdocs' failed
make: *** [pdfdocs] Error 2
--- Documentation/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/conf.py +1 -1
@@ -340,7 +340,7 @@ if minor > 3: # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ - ('user/index', 'linux-user.tex', 'Linux Kernel User Documentation', + ('admin-guide/index', 'linux-user.tex', 'Linux Kernel User Documentation', 'The kernel development community', 'manual'), ('kernel-documentation', 'kernel-documentation.tex', 'The Linux Kernel Documentation', 'The kernel development community', 'manual'),
Signature · 7 lines
2.1.4 -- Jani Nikula, Intel Open Source Technology Center
Mauro Carvalho Chehab
Reviewed-byEm Wed, 02 Nov 2016 13:14:47 +0200
Jani Nikula <[email protected]> escreveu:
Quoted 11 lines · Mauro Carvalho Chehab
Quoted 8 lines
This series address a series of errors during PDF generation from media documentation.
Please notice that patch 2 carries on a PDF conversion from a PNG image, because Sphinx is not smart enough to do the convertion.
This is a temporary solution (That's why I'm marking this series as RFC).
This seems to work on top of docs-next.
Yes.
Quoted 2 lines
...but it'll break again if we include the missing admin-guide in the build. :(
LaTeX/PDF output is ugly... for each new stuff, we need to re-validate its output :-(
Quoted 46 lines
BR,
Jani.From
c296287c65f4b6ad6272171456dcf8508c92ae2fMon Sep 17 00:00:00 2001
From: Jani Nikula <[email protected]>
Date: Wed, 2 Nov 2016 13:05:59 +0200
Subject: [PATCH]Documentation/sphinx: include admin-guide in the latex/pdf
build
Organization: Intel Finland Oy - BIC 0357606-4 - Westendinkatu 7, 02160 Espoo
Cc: Jani Nikula <[email protected]>Fix the warning:
WARNING: "
latex_documents" config value references unknown document user/indexSigned-off-by Jani Nikula <[email protected]>---
Sadly, this breaks the pdf build with:
! TeX capacity exceeded, sorry [main memory size=5000000]. \FV@Space ...ionary {\copy \sphinxvisiblespacebox
}{\sphinxafterbreak } {\ke...
l.3711 ...\PYG{n}{be} \PYG{n}{used} \PYG{n+nb}{to}Output written on linux-user.pdf (15 pages).
Transcript written on linux-user.log.
Makefile:66: recipe for target 'linux-user.pdf' failed make[2]: *** [linux-user.pdf] Error 1Documentation/Makefile.sphinx:83: recipe for target 'pdfdocs' failed make[1]: *** [pdfdocs] Error 2
Makefile:1442: recipe for target 'pdfdocs' failed
make: *** [pdfdocs] Error 2--- Documentation/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)Documentation/conf.py +0
-0
Documentation/conf.py if minor > 3: · line 343
Quoted 5 lines
Documentation/conf.py +1
-1@@ -340,7 +340,7 @@ if minor > 3: # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ - ('user/index', 'linux-user.tex', 'Linux Kernel User Documentation', + ('admin-guide/index', 'linux-user.tex', 'Linux Kernel User Documentation',
Oh! It seems I forgot to rename the guide name here :(
Your patch looks OK!
Documentation/conf.py if minor > 3: · line 346
Quoted 3 lines
Documentation/conf.py +0
-0'The kernel development community', 'manual'), ('kernel-documentation', 'kernel-documentation.tex', 'The Linux Kernel Documentation', 'The kernel development community', 'manual'),
Cheers,
Mauro
Quoted 15 lines · Mauro Carvalho Chehab
Em Wed, 02 Nov 2016 13:14:47 +0200
Jani Nikula <[email protected]> escreveu:Quoted 11 lines · Mauro Carvalho Chehab
Quoted 8 lines
This series address a series of errors during PDF generation from media documentation.
Please notice that patch 2 carries on a PDF conversion from a PNG image, because Sphinx is not smart enough to do the convertion.
This is a temporary solution (That's why I'm marking this series as RFC).
This seems to work on top of docs-next.
Quoted 7 lines
Yes.
Quoted 2 lines
...but it'll break again if we include the missing admin-guide in the build. :(
LaTeX/PDF output is ugly... for each new stuff, we need to re-validate its output :-(
Once we have this working, I think the only way to keep it working is to have continuous testing of the pdf build. That won't keep the output pretty, but it'll help ensure passing build.
Perhaps 0day could eventually start running 'make DOCBOOKS="" pdfdocs' after the htmldocs target? Cc: Fengguang and kbuild-all.
BR,
Jani.
Quoted 70 lines
Quoted 49 lines
BR,
Jani.From
c296287c65f4b6ad6272171456dcf8508c92ae2fMon Sep 17 00:00:00 2001
From: Jani Nikula <[email protected]>
Date: Wed, 2 Nov 2016 13:05:59 +0200
Subject: [PATCH]Documentation/sphinx: include admin-guide in the latex/pdf
build
Organization: Intel Finland Oy - BIC 0357606-4 - Westendinkatu 7, 02160 Espoo
Cc: Jani Nikula <[email protected]>Fix the warning:
WARNING: "
latex_documents" config value references unknown document user/indexSigned-off-by Jani Nikula <[email protected]>---
Sadly, this breaks the pdf build with:
! TeX capacity exceeded, sorry [main memory size=5000000]. \FV@Space ...ionary {\copy \sphinxvisiblespacebox
}{\sphinxafterbreak } {\ke...
l.3711 ...\PYG{n}{be} \PYG{n}{used} \PYG{n+nb}{to}Output written on linux-user.pdf (15 pages).
Transcript written on linux-user.log.
Makefile:66: recipe for target 'linux-user.pdf' failed make[2]: *** [linux-user.pdf] Error 1Documentation/Makefile.sphinx:83: recipe for target 'pdfdocs' failed make[1]: *** [pdfdocs] Error 2
Makefile:1442: recipe for target 'pdfdocs' failed
make: *** [pdfdocs] Error 2--- Documentation/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)Documentation/conf.py +0
-0Documentation/conf.py if minor > 3: · line 343
Quoted 5 lines
Documentation/conf.py +1
-1@@ -340,7 +340,7 @@ if minor > 3: # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ - ('user/index', 'linux-user.tex', 'Linux Kernel User Documentation', + ('admin-guide/index', 'linux-user.tex', 'Linux Kernel User Documentation',Oh! It seems I forgot to rename the guide name here :(
Your patch looks OK!
Reviewed-by Mauro Carvalho Chehab <[email protected]>Documentation/conf.py if minor > 3: · line 346
Quoted 3 lines
Documentation/conf.py +0
-0'The kernel development community', 'manual'), ('kernel-documentation', 'kernel-documentation.tex', 'The Linux Kernel Documentation', 'The kernel development community', 'manual'),Cheers,
Mauro
Signature · 1 line
Jani Nikula, Intel Open Source Technology Center
Em Wed, 02 Nov 2016 15:27:50 +0200
Jani Nikula <[email protected]> escreveu:
Quoted 21 lines · Mauro Carvalho Chehab
Quoted 20 lines
Em Wed, 02 Nov 2016 13:14:47 +0200
Jani Nikula <[email protected]> escreveu:Quoted 11 lines · Mauro Carvalho Chehab
Quoted 8 lines
This series address a series of errors during PDF generation from media documentation.
Please notice that patch 2 carries on a PDF conversion from a PNG image, because Sphinx is not smart enough to do the convertion.
This is a temporary solution (That's why I'm marking this series as RFC).
This seems to work on top of docs-next.
Yes.
Quoted 2 lines
...but it'll break again if we include the missing admin-guide in the build. :(
Quoted 6 lines
Quoted 2 lines
LaTeX/PDF output is ugly... for each new stuff, we need to re-validate its output :-(
Once we have this working, I think the only way to keep it working is to have continuous testing of the pdf build. That won't keep the output pretty, but it'll help ensure passing build.
Yes.
Quoted 2 lines
Perhaps 0day could eventually start running 'make DOCBOOKS="" pdfdocs' after the htmldocs target? Cc: Fengguang and kbuild-all.
Good idea! it will be really helpful if Fengguang could automate the testing process once we fix it.
Regards,
Mauro
Quoted 24 lines · Jani Nikula
Quoted 15 lines · Mauro Carvalho Chehab
Em Wed, 02 Nov 2016 13:14:47 +0200
Jani Nikula <[email protected]> escreveu:Quoted 11 lines · Mauro Carvalho Chehab
Quoted 8 lines
This series address a series of errors during PDF generation from media documentation.
Please notice that patch 2 carries on a PDF conversion from a PNG image, because Sphinx is not smart enough to do the convertion.
This is a temporary solution (That's why I'm marking this series as RFC).
This seems to work on top of docs-next.
Quoted 7 lines
Yes.
Quoted 2 lines
...but it'll break again if we include the missing admin-guide in the build. :(
LaTeX/PDF output is ugly... for each new stuff, we need to re-validate its output :-(
Quoted 6 lines
Once we have this working, I think the only way to keep it working is to have continuous testing of the pdf build. That won't keep the output pretty, but it'll help ensure passing build.
Perhaps 0day could eventually start running 'make DOCBOOKS="" pdfdocs' after the htmldocs target? Cc: Fengguang and kbuild-all.
OK. We'll add the 'pdfdocs' test right after 'htmldocs'. Thank you for the tip.
Regards,
Fengguang
Am 02.11.2016 um 12:14 schrieb Jani Nikula <[email protected]>:
Quoted 16 lines · Mauro Carvalho Chehab
Quoted 8 lines
This series address a series of errors during PDF generation from media documentation.
Please notice that patch 2 carries on a PDF conversion from a PNG image, because Sphinx is not smart enough to do the convertion.
This is a temporary solution (That's why I'm marking this series as RFC).
This seems to work on top of docs-next.
...but it'll break again if we include the missing admin-guide in the build. :(
Sadly, this breaks the pdf build with:
Quoted 5 lines
! TeX capacity exceeded, sorry [main memory size=5000000]. \FV@Space ...ionary {\copy \sphinxvisiblespacebox }{\sphinxafterbreak } {\ke...
l.3711 ...\PYG{n}{be} \PYG{n}{used} \PYG{n+nb}{to} or 2
This is the verbatim block of the kernel parameters with more than 4300 lines in.
IMO, Verbatim exceeded, because in sphinx.sty is a redefinition of the LaTeX Verbatim command which might be sloppy / see sphinx.sty::
\renewcommand{\Verbatim}[1][1]{%
....
The renew-Verbatim has been removed later:
https://github.com/sphinx-doc/sphinx/commit/f9880bfcc8b19a7d197badeb6ab412abfca19891
I my POC I use such a modified sphinx.sty
https://github.com/return42/sphkerneldoc/blob/master/_tex/sphinx.sty
with it, the PDF is build:
https://h2626237.stratoserver.net/kernel/books/admin-guide/pdf/linux-user.pdf
Using modified sphinx.sty has the drawback, that it is not up- or downward compatible to the installed Sphinx version.
So in short, I think it is the best to come back to the reasons and just split kernel parameters in several blocks and using the 'none' option to prevent rendering as C .. E.g:
.. code-block:: none
acpi= [HW,ACPI,X86,ARM64]
Advanced Configuration and Power Interface
Format: { force | on | off | strict | noirq | rsdt |
copy_dsdt }-- Markus --
Em Wed, 2 Nov 2016 17:08:08 +0100
Markus Heiser <[email protected]> escreveu:
Quoted 28 lines
Am 02.11.2016 um 12:14 schrieb Jani Nikula <[email protected]>:
Quoted 16 lines · Mauro Carvalho Chehab
Quoted 8 lines
This series address a series of errors during PDF generation from media documentation.
Please notice that patch 2 carries on a PDF conversion from a PNG image, because Sphinx is not smart enough to do the convertion.
This is a temporary solution (That's why I'm marking this series as RFC).
This seems to work on top of docs-next.
...but it'll break again if we include the missing admin-guide in the build. :(
Sadly, this breaks the pdf build with:Quoted 5 lines
! TeX capacity exceeded, sorry [main memory size=5000000]. \FV@Space ...ionary {\copy \sphinxvisiblespacebox }{\sphinxafterbreak } {\ke...
l.3711 ...\PYG{n}{be} \PYG{n}{used} \PYG{n+nb}{to} or 2This is the verbatim block of the kernel parameters with more than 4300 lines in.
Quoted 6 lines
IMO, Verbatim exceeded, because in sphinx.sty is a redefinition of the LaTeX Verbatim command which might be sloppy / see sphinx.sty::
\renewcommand{\Verbatim}[1][1]{%
....
Argh! I really hate those ugly hacks that Sphinx do for LaTeX output...
Btw, I remember I had to touch on a TeXLive style in order to workaround the memory size when testing LaTeX output for some book, but it ended by causing some other issues.
Quoted 13 lines
The renew-Verbatim has been removed later:
https://github.com/sphinx-doc/sphinx/commit/f9880bfcc8b19a7d197badeb6ab412abfca19891
I my POC I use such a modified sphinx.sty
https://github.com/return42/sphkerneldoc/blob/master/_tex/sphinx.sty
with it, the PDF is build:
https://h2626237.stratoserver.net/kernel/books/admin-guide/pdf/linux-user.pdf
Quoted 8 lines
Using modified sphinx.sty has the drawback, that it is not up- or downward compatible to the installed Sphinx version.
So in short, I think it is the best to come back to the reasons and just split kernel parameters in several blocks and using the 'none' option to prevent rendering as C .. E.g:
.. code-block:: none
I'm staring to think that we should just redefine the default for ::
to be "none", and use the "C" handling **only** when explicitly requested.
I remember that Jon did such suggestion sometime ago.
If we change it to "none", it will still spend lots of memory for verbatim?
Cheers,
Mauro
Am 02.11.2016 um 17:47 schrieb Mauro Carvalho Chehab <[email protected]>:
Quoted 64 lines
Em Wed, 2 Nov 2016 17:08:08 +0100
Markus Heiser <[email protected]> escreveu:Quoted 28 lines
Am 02.11.2016 um 12:14 schrieb Jani Nikula <[email protected]>:
Quoted 16 lines · Mauro Carvalho Chehab
Quoted 8 lines
This series address a series of errors during PDF generation from media documentation.
Please notice that patch 2 carries on a PDF conversion from a PNG image, because Sphinx is not smart enough to do the convertion.
This is a temporary solution (That's why I'm marking this series as RFC).
This seems to work on top of docs-next.
...but it'll break again if we include the missing admin-guide in the build. :(
Sadly, this breaks the pdf build with:Quoted 5 lines
! TeX capacity exceeded, sorry [main memory size=5000000]. \FV@Space ...ionary {\copy \sphinxvisiblespacebox }{\sphinxafterbreak } {\ke...
l.3711 ...\PYG{n}{be} \PYG{n}{used} \PYG{n+nb}{to} or 2This is the verbatim block of the kernel parameters with more than 4300 lines in.
Quoted 6 lines
IMO, Verbatim exceeded, because in sphinx.sty is a redefinition of the LaTeX Verbatim command which might be sloppy / see sphinx.sty::
\renewcommand{\Verbatim}[1][1]{%
....Argh! I really hate those ugly hacks that Sphinx do for LaTeX output...
Btw, I remember I had to touch on a TeXLive style in order to workaround the memory size when testing LaTeX output for some book, but it ended by causing some other issues.
Quoted 20 lines
The renew-Verbatim has been removed later:
https://github.com/sphinx-doc/sphinx/commit/f9880bfcc8b19a7d197badeb6ab412abfca19891
I my POC I use such a modified sphinx.sty
https://github.com/return42/sphkerneldoc/blob/master/_tex/sphinx.sty
with it, the PDF is build:
https://h2626237.stratoserver.net/kernel/books/admin-guide/pdf/linux-user.pdf
Using modified sphinx.sty has the drawback, that it is not up- or downward compatible to the installed Sphinx version.
So in short, I think it is the best to come back to the reasons and just split kernel parameters in several blocks and using the 'none' option to prevent rendering as C .. E.g:
Quoted 7 lines
Quoted 1 line
.. code-block:: none
I'm staring to think that we should just redefine the default for ::
to be "none", and use the "C" handling **only** when explicitly requested.I remember that Jon did such suggestion sometime ago.
*shrug* ... I think about kernel-doc comments in the sources, mostly you will have small examples and won't those verbose ".. code-block::" markup / using "::" keeps the comment compact.
Quoted 3 lines
If we change it to "none", it will still spend lots of memory for verbatim?
Yes .. we need to split kernel parameter's into smaller verbatime blocks.
Quoted 10 lines · Markus Heiser
Am 02.11.2016 um 17:47 schrieb Mauro Carvalho Chehab <[email protected]>:
Quoted 5 lines
I'm staring to think that we should just redefine the default for ::
to be "none", and use the "C" handling **only** when explicitly requested.I remember that Jon did such suggestion sometime ago.
*shrug* ... I think about kernel-doc comments in the sources, mostly you will have small examples and won't those verbose ".. code-block::" markup / using "::" keeps the comment compact.
I sent the patch [1] to default to "none". It's never wrong, not even for code. But getting the highlighting wrong, OTOH, is pretty bad. We have that.
And really, if you look at the kernel-doc comments and the rst documentation, we don't have all that many literal blocks that would benefit from syntax highlighting in the first place.
BR,
Jani.
[1] http://lkml.kernel.org/r/[email protected]
Signature · 1 line
Jani Nikula, Intel Open Source Technology Center