Skip to contentSkip to conversation

Fix PDF build errors

RFC PATCH In review Mauro Carvalho Chehab 5 participants 17 messages Nov 1, 2016 – Nov 3, 2016 Documentation

lore
Share & tools
lore
#0 lore raw

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
#1 lore raw

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

Fixes e61a39baf74d ("[media] index.rst: Fix LaTeX error in interactive mode on Sphinx 1.4.x")
---
 Documentation/conf.py         | 4 ++++
 Documentation/media/index.rst | 5 -----
 2 files changed, 4 insertions(+), 5 deletions(-)
Documentation/conf.py +4 -0
index d9bad21dd427..814c336e5f5e 100644
@@ -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
index e347a3e7bdef..7f8f0af620ce 100644
@@ -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
#2 lore raw

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 -C Documentation/output/./latex

Fixes e61a39baf74d ("[media] index.rst: Fix LaTeX error in interactive mode on Sphinx 1.4.x")

---
Documentation/conf.py | 4 ++++
Documentation/media/index.rst | 5 -----

2 files changed, 4 insertions(+), 5 deletions(-)
Documentation/conf.py +0 -0
index d9bad21dd427..814c336e5f5e 100644

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
index e347a3e7bdef..7f8f0af620ce 100644
@@ -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
#3 lore raw

Re: [PATCH RFC 1/4] docs-rst: fix PDF build errors

In reply to Mauro Carvalho Chehab

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 -C Documentation/output/./latex

Fixes e61a39baf74d ("[media] index.rst: Fix LaTeX error in interactive mode on Sphinx 1.4.x")

---
Documentation/conf.py | 4 ++++
Documentation/media/index.rst | 5 -----

2 files changed, 4 insertions(+), 5 deletions(-)
Documentation/conf.py +0 -0
index d9bad21dd427..814c336e5f5e 100644

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

#4 lore raw

RFC PATCH 2/4 subdev-formats.rst: we need a pdf picture for bayer

In reply to Mauro Carvalho Chehab

The 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
index e144370f62a0..489a685945e2 100644
@@ -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
new file mode 100644
index 0000000000000000000000000000000000000000..8ccef608cabd2cfdd6cfb3e80a5055d5cb05d814
GIT binary patch
Signature · 1 line
2.7.4
#5 lore raw
In reply to Mauro Carvalho Chehab

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

#6 lore raw

RFC PATCH 3/4 subdev-formats.rst: don't use adjustbox on a longtable

In reply to Mauro Carvalho Chehab

adjustbox 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
index 489a685945e2..cfffcfbe98fa 100644
@@ -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
#7 lore raw

RFC PATCH 4/4 subdev-formats.rst: add missing columns to tabularcolumns

In reply to Mauro Carvalho Chehab

There 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
index cfffcfbe98fa..ac9e96049d04 100644
@@ -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
#8 lore raw
In reply to Mauro Carvalho Chehab
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 c296287c65f4b6ad6272171456dcf8508c92ae2f Mon 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
index 814c336e5f5e..0c758a4f61f1 100644
@@ -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
#9 lore raw

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

LaTeX/PDF output is ugly... for each new stuff, we need to re-validate its output :-(

Quoted 46 lines

BR,
Jani.

From c296287c65f4b6ad6272171456dcf8508c92ae2f Mon 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 +0 -0
index 814c336e5f5e..0c758a4f61f1 100644

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

#10 lore raw
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 c296287c65f4b6ad6272171456dcf8508c92ae2f Mon 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 +0 -0
index 814c336e5f5e..0c758a4f61f1 100644

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

Signature · 1 line
Jani Nikula, Intel Open Source Technology Center
#11 lore raw

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

#12 lore raw
In reply to Jani Nikula
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

#13 lore raw
In reply to Jani Nikula

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

#14 lore raw

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 2

This 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

#15 lore raw

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 2

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

#16 lore raw
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