[PATCH 0/5] PDF output fixes

[PATCH 0/5] PDF output fixes

[Mauro Carvalho Chehab]

In order to be able to build all PDF books, besides the two patches I
already sent:

    docs: pdf: add all Documentation/*/index.rst to PDF output
    docs: automarkup.py: ignore exceptions when seeking for xrefs

A few others are needed:

- patch 1 removes nested tables for a few files I converted, as 
  Sphinx LaTeX builder doesn't support it;
- Patches 2 to 4 addresses some minor issues on some books,
  usually requiring some blank lines, extra whitespaces or some
  tag replacement;
- Patch 5 is required in order to be able to build the translations
  PDF book, as it adds Asian fonts support to XeLaTeX.

This patch series is at:

	https://git.linuxtv.org/mchehab/experimental.git/log/?h=extra_fixes_v1

And it is on the top of the ReST conversions that IMO should be
sent at the end of this merge window.

Mauro Carvalho Chehab (5):
  docs: don't use nested tables
  docs: arm: fix a breakage with pdf output
  docs: block: fix pdf output
  docs: kbuild: fix build with pdf and fix some minor issues
  docs: conf.py: add CJK package needed by translations

 Documentation/admin-guide/laptops/sonypi.rst  | 26 +++++++++----------
 .../admin-guide/laptops/toshiba_haps.rst      |  8 +++---
 Documentation/arm/spear/overview.rst          |  1 +
 Documentation/block/biodoc.rst                |  9 ++++---
 Documentation/conf.py                         |  4 +++
 Documentation/driver-api/nvdimm/btt.rst       |  2 +-
 Documentation/kbuild/issues.rst               | 20 ++++++++------
 Documentation/kbuild/kbuild.rst               |  3 ++-
 Documentation/kbuild/kconfig-language.rst     | 12 +++++++++
 Documentation/kbuild/kconfig.rst              |  8 ++++--
 Documentation/kbuild/makefiles.rst            |  1 +
 Documentation/s390/debugging390.rst           |  2 +-
 12 files changed, 61 insertions(+), 35 deletions(-)

-- 
2.21.0

[PATCH 4/5] docs: kbuild: fix build with pdf and fix some minor issues

[Mauro Carvalho Chehab]

The tag ".. include" should be replaced by ".. literalinclude" at
issues.rst, otherwise it causes TeX to crash due to excessive usage
of stack with Sphinx 2.0.

While here, solve a few minor issues at the kbuild book output by
adding extra blank lines.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 Documentation/kbuild/issues.rst           | 20 ++++++++++++--------
 Documentation/kbuild/kbuild.rst           |  3 ++-
 Documentation/kbuild/kconfig-language.rst | 12 ++++++++++++
 Documentation/kbuild/kconfig.rst          |  8 ++++++--
 Documentation/kbuild/makefiles.rst        |  1 +
 5 files changed, 33 insertions(+), 11 deletions(-)

diff --git a/Documentation/kbuild/issues.rst b/Documentation/kbuild/issues.rst
index 9fdded4b681c..bdab01f733f6 100644
--- a/Documentation/kbuild/issues.rst
+++ b/Documentation/kbuild/issues.rst
@@ -1,11 +1,15 @@
-Recursion issue #1
-------------------
+================
+Recursion issues
+================
 
- .. include:: Kconfig.recursion-issue-01
-    :literal:
+issue #1
+--------
 
-Recursion issue #2
-------------------
+.. literalinclude:: Kconfig.recursion-issue-01
+   :language: kconfig
 
- .. include:: Kconfig.recursion-issue-02
-    :literal:
+issue #2
+--------
+
+.. literalinclude:: Kconfig.recursion-issue-02
+   :language: kconfig
diff --git a/Documentation/kbuild/kbuild.rst b/Documentation/kbuild/kbuild.rst
index e774e760522d..bc3915ca38d1 100644
--- a/Documentation/kbuild/kbuild.rst
+++ b/Documentation/kbuild/kbuild.rst
@@ -18,7 +18,7 @@ This file lists all modules that are built into the kernel. This is used
 by modprobe to not fail when trying to load something builtin.
 
 modules.builtin.modinfo
---------------------------------------------------
+-----------------------
 This file contains modinfo from all modules that are built into the kernel.
 Unlike modinfo of a separate module, all fields are prefixed with module name.
 
@@ -153,6 +153,7 @@ Install script called when using "make install".
 The default name is "installkernel".
 
 The script will be called with the following arguments:
+
    - $1 - kernel version
    - $2 - kernel image file
    - $3 - kernel map file
diff --git a/Documentation/kbuild/kconfig-language.rst b/Documentation/kbuild/kconfig-language.rst
index 2bc8a7803365..74bef19f69f0 100644
--- a/Documentation/kbuild/kconfig-language.rst
+++ b/Documentation/kbuild/kconfig-language.rst
@@ -53,6 +53,7 @@ A menu entry can have a number of attributes. Not all of them are
 applicable everywhere (see syntax).
 
 - type definition: "bool"/"tristate"/"string"/"hex"/"int"
+
   Every config option must have a type. There are only two basic types:
   tristate and string; the other types are based on these two. The type
   definition optionally accepts an input prompt, so these two examples
@@ -66,11 +67,13 @@ applicable everywhere (see syntax).
 	prompt "Networking support"
 
 - input prompt: "prompt" <prompt> ["if" <expr>]
+
   Every menu entry can have at most one prompt, which is used to display
   to the user. Optionally dependencies only for this prompt can be added
   with "if".
 
 - default value: "default" <expr> ["if" <expr>]
+
   A config option can have any number of default values. If multiple
   default values are visible, only the first defined one is active.
   Default values are not limited to the menu entry where they are
@@ -112,6 +115,7 @@ applicable everywhere (see syntax).
   Optionally dependencies for this default value can be added with "if".
 
 - dependencies: "depends on" <expr>
+
   This defines a dependency for this menu entry. If multiple
   dependencies are defined, they are connected with '&&'. Dependencies
   are applied to all other options within this menu entry (which also
@@ -127,6 +131,7 @@ applicable everywhere (see syntax).
 	default y
 
 - reverse dependencies: "select" <symbol> ["if" <expr>]
+
   While normal dependencies reduce the upper limit of a symbol (see
   below), reverse dependencies can be used to force a lower limit of
   another symbol. The value of the current menu symbol is used as the
@@ -146,6 +151,7 @@ applicable everywhere (see syntax).
 	the illegal configurations all over.
 
 - weak reverse dependencies: "imply" <symbol> ["if" <expr>]
+
   This is similar to "select" as it enforces a lower limit on another
   symbol except that the "implied" symbol's value may still be set to n
   from a direct dependency or with a visible prompt.
@@ -176,6 +182,7 @@ applicable everywhere (see syntax).
   configure that subsystem out without also having to unset these drivers.
 
 - limiting menu display: "visible if" <expr>
+
   This attribute is only applicable to menu blocks, if the condition is
   false, the menu block is not displayed to the user (the symbols
   contained there can still be selected by other symbols, though). It is
@@ -183,12 +190,14 @@ applicable everywhere (see syntax).
   entries. Default value of "visible" is true.
 
 - numerical ranges: "range" <symbol> <symbol> ["if" <expr>]
+
   This allows to limit the range of possible input values for int
   and hex symbols. The user can only input a value which is larger than
   or equal to the first symbol and smaller than or equal to the second
   symbol.
 
 - help text: "help" or "---help---"
+
   This defines a help text. The end of the help text is determined by
   the indentation level, this means it ends at the first line which has
   a smaller indentation than the first line of the help text.
@@ -197,6 +206,7 @@ applicable everywhere (see syntax).
   the file as an aid to developers.
 
 - misc options: "option" <symbol>[=<value>]
+
   Various less common options can be defined via this option syntax,
   which can modify the behaviour of the menu entry and its config
   symbol. These options are currently possible:
@@ -325,6 +335,7 @@ end a menu entry:
 The first five also start the definition of a menu entry.
 
 config::
+
 	"config" <symbol>
 	<config options>
 
@@ -332,6 +343,7 @@ This defines a config symbol <symbol> and accepts any of above
 attributes as options.
 
 menuconfig::
+
 	"menuconfig" <symbol>
 	<config options>
 
diff --git a/Documentation/kbuild/kconfig.rst b/Documentation/kbuild/kconfig.rst
index 88129af7e539..a9a855f894b3 100644
--- a/Documentation/kbuild/kconfig.rst
+++ b/Documentation/kbuild/kconfig.rst
@@ -264,6 +264,7 @@ NCONFIG_MODE
 This mode shows all sub-menus in one large tree.
 
 Example::
+
 	make NCONFIG_MODE=single_menu nconfig
 
 ----------------------------------------------------------------------
@@ -277,9 +278,12 @@ Searching in xconfig:
 	names, so you have to know something close to what you are
 	looking for.
 
-	Example:
+	Example::
+
 		Ctrl-F hotplug
-	or
+
+	or::
+
 		Menu: File, Search, hotplug
 
 	lists all config symbol entries that contain "hotplug" in
diff --git a/Documentation/kbuild/makefiles.rst b/Documentation/kbuild/makefiles.rst
index 093f2d79ab95..f31158457753 100644
--- a/Documentation/kbuild/makefiles.rst
+++ b/Documentation/kbuild/makefiles.rst
@@ -384,6 +384,7 @@ more details, with real examples.
 -----------------------
 
 	Kbuild tracks dependencies on the following:
+
 	1) All prerequisite files (both `*.c` and `*.h`)
 	2) `CONFIG_` options used in all prerequisite files
 	3) Command-line used to compile target
-- 
2.21.0

Re: [PATCH 0/5] PDF output fixes

[Jonathan Corbet]

On Tue,  9 Jul 2019 15:33:18 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:

> In order to be able to build all PDF books, besides the two patches I
> already sent:
> 
>     docs: pdf: add all Documentation/*/index.rst to PDF output
>     docs: automarkup.py: ignore exceptions when seeking for xrefs
> 
> A few others are needed:
> 
> - patch 1 removes nested tables for a few files I converted, as 
>   Sphinx LaTeX builder doesn't support it;
> - Patches 2 to 4 addresses some minor issues on some books,
>   usually requiring some blank lines, extra whitespaces or some
>   tag replacement;
> - Patch 5 is required in order to be able to build the translations
>   PDF book, as it adds Asian fonts support to XeLaTeX.

So, modulo my one comment on the last patch the series seems OK, though I
don't like having to work around limitations in PDF generation this way.
Can't you just make rst2pdf work instead? :)

I guess it makes sense for these to go with the big band-aid-removal patch
set.

Thanks,

jon

P.S. it seems that rst2pdf is actually being developed again:
https://akrabat.com/rst2pdf-back-from-the-dead/ .  I wonder how far
they'll get with it.

Re: [PATCH 0/5] PDF output fixes

[Mauro Carvalho Chehab]

Em Fri, 12 Jul 2019 14:19:21 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> On Tue,  9 Jul 2019 15:33:18 -0300
> Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
> 
> > In order to be able to build all PDF books, besides the two patches I
> > already sent:
> > 
> >     docs: pdf: add all Documentation/*/index.rst to PDF output
> >     docs: automarkup.py: ignore exceptions when seeking for xrefs
> > 
> > A few others are needed:
> > 
> > - patch 1 removes nested tables for a few files I converted, as 
> >   Sphinx LaTeX builder doesn't support it;
> > - Patches 2 to 4 addresses some minor issues on some books,
> >   usually requiring some blank lines, extra whitespaces or some
> >   tag replacement;
> > - Patch 5 is required in order to be able to build the translations
> >   PDF book, as it adds Asian fonts support to XeLaTeX.  
> 
> So, modulo my one comment on the last patch the series seems OK, though I
> don't like having to work around limitations in PDF generation this way.

Yeah, I feel the pain. I didn't like writing those patches either.

> Can't you just make rst2pdf work instead? :)

Well, we can try. Last time we tried, there were lots of things missing
for it to work. 

Based on:

	https://pypi.org/project/rst2pdf/

The project got stuck back on Dec, 2012, up to the beginning of this
year. Maybe the issues we had in the past got fixed.

Also, right now, rst2pdf only supports Python 2.7.

I would wait for it to support Python 3.x before doing the actual
migration.

-

I don't remember the exact details, but when rst2pdf were
used with some documents, it didn't produce a valid PDF file, but perhaps
someone fixed it.

Assuming that rst2pdf works now, there are still several LaTeX specific
hacks on some files:

	$ git grep -l latex|grep rst|wc -l
	     28  

I guess almost all of them are related to the lack of proper support
at ReST markup language that would allow adjusting the output to fit
within the page limits. 

On media, we need two types of additional features:

1) Sphinx pdf builder uses two different LaTeX ways of producing a table.
(tabular x tabularx x longtable - don't remember anymore the exact
two dialects it uses).

One of the dialect allows a table to be on multiple pages; the other
one doesn't. The builder decides the dialect if a table has more than 30
columns, but there's a way to force longtable (by changing the css style).

Not sure if rst2pdf honors the same css style.

2) Table scaling / font resize. The Sphinx PDF builder doesn't scale
the fonts inside a table, nor the ReST dialect allows changing the font
size. So, we had to use raw LaTeX dialects for it to work.

Anyway, I'm enclosing an experimental patch that would enable rst2pdf.
It is not at production level.

It also shows some crashes like this one:

[ERROR] pdfbuilder.py:133 format not resolved, probably missing URL scheme or undefined destination target for 'Callback%20Registry'
Traceback (most recent call last):
  File "/devel/v4l/docs/sphinx_1.7.9/lib/python2.7/site-packages/rst2pdf/pdfbuilder.py", line 130, in write
    docwriter.write(doctree, destination)
  File "/devel/v4l/docs/sphinx_1.7.9/lib/python2.7/site-packages/docutils/writers/__init__.py", line 80, in write
    self.translate()
  File "/devel/v4l/docs/sphinx_1.7.9/lib/python2.7/site-packages/rst2pdf/pdfbuilder.py", line 633, in translate
    compressed=self.compressed)
  File "/devel/v4l/docs/sphinx_1.7.9/lib/python2.7/site-packages/rst2pdf/createpdf.py", line 664, in createPdf
    pdfdoc.multiBuild(elements)
  File "/devel/v4l/docs/sphinx_1.7.9/lib/python2.7/site-packages/reportlab/platypus/doctemplate.py", line 1154, in multiBuild
    self.canv.save()
  File "/devel/v4l/docs/sphinx_1.7.9/lib/python2.7/site-packages/reportlab/pdfgen/canvas.py", line 1242, in save
    self._doc.SaveToFile(self._filename, self)
  File "/devel/v4l/docs/sphinx_1.7.9/lib/python2.7/site-packages/reportlab/pdfbase/pdfdoc.py", line 215, in SaveToFile
    data = self.GetPDFData(canvas)
  File "/devel/v4l/docs/sphinx_1.7.9/lib/python2.7/site-packages/reportlab/pdfbase/pdfdoc.py", line 241, in GetPDFData
    return self.format()
  File "/devel/v4l/docs/sphinx_1.7.9/lib/python2.7/site-packages/reportlab/pdfbase/pdfdoc.py", line 423, in format
    IOf = IO.format(self)
  File "/devel/v4l/docs/sphinx_1.7.9/lib/python2.7/site-packages/reportlab/pdfbase/pdfdoc.py", line 871, in format
    fcontent = format(self.content, document, toplevel=1)   # yes this is at top level
  File "/devel/v4l/docs/sphinx_1.7.9/lib/python2.7/site-packages/reportlab/pdfbase/pdfdoc.py", line 80, in format
    f = element.format(document)
  File "/devel/v4l/docs/sphinx_1.7.9/lib/python2.7/site-packages/reportlab/pdfbase/pdfdoc.py", line 1608, in format
    return D.format(document)
  File "/devel/v4l/docs/sphinx_1.7.9/lib/python2.7/site-packages/reportlab/pdfbase/pdfdoc.py", line 679, in format
    L = [(format(PDFName(k),document)+b" "+format(dict[k],document)) for k in keys]
  File "/devel/v4l/docs/sphinx_1.7.9/lib/python2.7/site-packages/reportlab/pdfbase/pdfdoc.py", line 80, in format
    f = element.format(document)
  File "/devel/v4l/docs/sphinx_1.7.9/lib/python2.7/site-packages/reportlab/pdfbase/pdfdoc.py", line 1773, in format
    if f is None: raise ValueError("format not resolved, probably missing URL scheme or undefined destination target for '%s'" % self.name)
ValueError: format not resolved, probably missing URL scheme or undefined destination target for 'Callback%20Registry'
FAILED


> 
> I guess it makes sense for these to go with the big band-aid-removal patch
> set.

OK, I'll send it together with the big patchset.

> 
> Thanks,
> 
> jon
> 
> P.S. it seems that rst2pdf is actually being developed again:
> https://akrabat.com/rst2pdf-back-from-the-dead/ .  I wonder how far
> they'll get with it.

Thanks,
Mauro

[PATCH RFC] docs: experimental: build PDF with rst2pdf

Change the logic to use rst2pdf instead of LaTeX.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>

diff --git a/Documentation/Makefile b/Documentation/Makefile
index e145e4db508b..cc913f96a66d 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -95,9 +95,10 @@ pdfdocs:
 
 else # HAVE_PDFLATEX
 
-pdfdocs: latexdocs
+pdfdocs:
 	@$(srctree)/scripts/sphinx-pre-install --version-check
-	$(foreach var,$(SPHINXDIRS), $(MAKE) PDFLATEX="$(PDFLATEX)" LATEXOPTS="$(LATEXOPTS)" -C $(BUILDDIR)/$(var)/latex || exit;)
+	mkdir -p $(BUILDDIR)/pdf
+	@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,pdf,$(var),pdf,$(var)))
 
 endif # HAVE_PDFLATEX
 
diff --git a/Documentation/conf.py b/Documentation/conf.py
index fa0a42b47e62..4db8a62d7c6a 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -35,13 +35,14 @@ needs_sphinx = '1.3'
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'cdomain',
-              'kfigure', 'sphinx.ext.ifconfig', 'automarkup']
+              'kfigure', 'sphinx.ext.ifconfig', 'automarkup', 'rst2pdf.pdfbuilder']
 
-# The name of the math extension changed on Sphinx 1.4
-if (major == 1 and minor > 3) or (major > 1):
-    extensions.append("sphinx.ext.imgmath")
-else:
-    extensions.append("sphinx.ext.pngmath")
+# FIXME: when rst2pdf.pdfbuilder is added, the code below causes an error
+## The name of the math extension changed on Sphinx 1.4
+#if (major == 1 and minor > 3) or (major > 1):
+#    extensions.append("sphinx.ext.imgmath")
+#else:
+#    extensions.append("sphinx.ext.pngmath")
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -564,12 +565,15 @@ epub_exclude_files = ['search.html']
 #
 # See the Sphinx chapter of http://ralsina.me/static/manual.pdf
 #
-# FIXME: Do not add the index file here; the result will be too big. Adding
-# multiple PDF files here actually tries to get the cross-referencing right
-# *between* PDF files.
-pdf_documents = [
-    ('kernel-documentation', u'Kernel', u'Kernel', u'J. Random Bozo'),
-]
+
+# Add all LaTeX files to PDF documents as well
+pdf_documents = []
+for l in latex_documents:
+    doc = l[0]
+    fn = l[1].replace("tex", "pdf")
+    name = l[2]
+    authors = l[3]
+    pdf_documents.append((doc, fn, name, authors))
 
 # kernel-doc extension configuration for running Sphinx directly (e.g. by Read
 # the Docs). In a normal build, these are supplied from the Makefile via command
diff --git a/Documentation/media/Makefile b/Documentation/media/Makefile
index d75d70f191bc..3050136ed489 100644
--- a/Documentation/media/Makefile
+++ b/Documentation/media/Makefile
@@ -53,12 +53,13 @@ $(BUILDDIR)/lirc.h.rst: ${UAPI}/lirc.h ${PARSER} $(SRC_DIR)/lirc.h.rst.exception
 
 # Media build rules
 
-.PHONY: all html epub xml latex
+.PHONY: all html epub xml latex pdf
 
 all: $(IMGDOT) $(BUILDDIR) ${TARGETS}
 html: all
 epub: all
 xml: all
+pdf: all
 latex: $(IMGPDF) all
 linkcheck:
 

Re: [PATCH 0/5] PDF output fixes

[Mauro Carvalho Chehab]

Em Fri, 12 Jul 2019 19:27:05 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> escreveu:

> Em Fri, 12 Jul 2019 14:19:21 -0600
> Jonathan Corbet <corbet@lwn.net> escreveu:
> 
> > On Tue,  9 Jul 2019 15:33:18 -0300
> > Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
> >   
> > > In order to be able to build all PDF books, besides the two patches I
> > > already sent:
> > > 
> > >     docs: pdf: add all Documentation/*/index.rst to PDF output
> > >     docs: automarkup.py: ignore exceptions when seeking for xrefs
> > > 
> > > A few others are needed:
> > > 
> > > - patch 1 removes nested tables for a few files I converted, as 
> > >   Sphinx LaTeX builder doesn't support it;
> > > - Patches 2 to 4 addresses some minor issues on some books,
> > >   usually requiring some blank lines, extra whitespaces or some
> > >   tag replacement;
> > > - Patch 5 is required in order to be able to build the translations
> > >   PDF book, as it adds Asian fonts support to XeLaTeX.    
> > 
> > So, modulo my one comment on the last patch the series seems OK, though I
> > don't like having to work around limitations in PDF generation this way.  
> 
> Yeah, I feel the pain. I didn't like writing those patches either.
> 
> > Can't you just make rst2pdf work instead? :)  
> 
> Well, we can try. Last time we tried, there were lots of things missing
> for it to work. 
> 
> Based on:
> 
> 	https://pypi.org/project/rst2pdf/
> 
> The project got stuck back on Dec, 2012, up to the beginning of this
> year. Maybe the issues we had in the past got fixed.
> 
> Also, right now, rst2pdf only supports Python 2.7.
> 
> I would wait for it to support Python 3.x before doing the actual
> migration.
> 
> -
> 
> I don't remember the exact details, but when rst2pdf were
> used with some documents, it didn't produce a valid PDF file, but perhaps
> someone fixed it.
> 
> Assuming that rst2pdf works now, there are still several LaTeX specific
> hacks on some files:
> 
> 	$ git grep -l latex|grep rst|wc -l
> 	     28  
> 
> I guess almost all of them are related to the lack of proper support
> at ReST markup language that would allow adjusting the output to fit
> within the page limits. 
> 
> On media, we need two types of additional features:
> 
> 1) Sphinx pdf builder uses two different LaTeX ways of producing a table.
> (tabular x tabularx x longtable - don't remember anymore the exact
> two dialects it uses).
> 
> One of the dialect allows a table to be on multiple pages; the other
> one doesn't. The builder decides the dialect if a table has more than 30
> columns, but there's a way to force longtable (by changing the css style).
> 
> Not sure if rst2pdf honors the same css style.
> 
> 2) Table scaling / font resize. The Sphinx PDF builder doesn't scale
> the fonts inside a table, nor the ReST dialect allows changing the font
> size. So, we had to use raw LaTeX dialects for it to work.
> 
> Anyway, I'm enclosing an experimental patch that would enable rst2pdf.
> It is not at production level.
> 
> It also shows some crashes like this one:
> 
> [ERROR] pdfbuilder.py:133 format not resolved, probably missing URL scheme or undefined destination target for 'Callback%20Registry'
> Traceback (most recent call last):
>   File "/devel/v4l/docs/sphinx_1.7.9/lib/python2.7/site-packages/rst2pdf/pdfbuilder.py", line 130, in write
>     docwriter.write(doctree, destination)
>   File "/devel/v4l/docs/sphinx_1.7.9/lib/python2.7/site-packages/docutils/writers/__init__.py", line 80, in write
>     self.translate()
>   File "/devel/v4l/docs/sphinx_1.7.9/lib/python2.7/site-packages/rst2pdf/pdfbuilder.py", line 633, in translate
>     compressed=self.compressed)
>   File "/devel/v4l/docs/sphinx_1.7.9/lib/python2.7/site-packages/rst2pdf/createpdf.py", line 664, in createPdf
>     pdfdoc.multiBuild(elements)
>   File "/devel/v4l/docs/sphinx_1.7.9/lib/python2.7/site-packages/reportlab/platypus/doctemplate.py", line 1154, in multiBuild
>     self.canv.save()
>   File "/devel/v4l/docs/sphinx_1.7.9/lib/python2.7/site-packages/reportlab/pdfgen/canvas.py", line 1242, in save
>     self._doc.SaveToFile(self._filename, self)
>   File "/devel/v4l/docs/sphinx_1.7.9/lib/python2.7/site-packages/reportlab/pdfbase/pdfdoc.py", line 215, in SaveToFile
>     data = self.GetPDFData(canvas)
>   File "/devel/v4l/docs/sphinx_1.7.9/lib/python2.7/site-packages/reportlab/pdfbase/pdfdoc.py", line 241, in GetPDFData
>     return self.format()
>   File "/devel/v4l/docs/sphinx_1.7.9/lib/python2.7/site-packages/reportlab/pdfbase/pdfdoc.py", line 423, in format
>     IOf = IO.format(self)
>   File "/devel/v4l/docs/sphinx_1.7.9/lib/python2.7/site-packages/reportlab/pdfbase/pdfdoc.py", line 871, in format
>     fcontent = format(self.content, document, toplevel=1)   # yes this is at top level
>   File "/devel/v4l/docs/sphinx_1.7.9/lib/python2.7/site-packages/reportlab/pdfbase/pdfdoc.py", line 80, in format
>     f = element.format(document)
>   File "/devel/v4l/docs/sphinx_1.7.9/lib/python2.7/site-packages/reportlab/pdfbase/pdfdoc.py", line 1608, in format
>     return D.format(document)
>   File "/devel/v4l/docs/sphinx_1.7.9/lib/python2.7/site-packages/reportlab/pdfbase/pdfdoc.py", line 679, in format
>     L = [(format(PDFName(k),document)+b" "+format(dict[k],document)) for k in keys]
>   File "/devel/v4l/docs/sphinx_1.7.9/lib/python2.7/site-packages/reportlab/pdfbase/pdfdoc.py", line 80, in format
>     f = element.format(document)
>   File "/devel/v4l/docs/sphinx_1.7.9/lib/python2.7/site-packages/reportlab/pdfbase/pdfdoc.py", line 1773, in format
>     if f is None: raise ValueError("format not resolved, probably missing URL scheme or undefined destination target for '%s'" % self.name)
> ValueError: format not resolved, probably missing URL scheme or undefined destination target for 'Callback%20Registry'
> FAILED
> 
> 
> > 
> > I guess it makes sense for these to go with the big band-aid-removal patch
> > set.  
> 
> OK, I'll send it together with the big patchset.
> 
> > 
> > Thanks,
> > 
> > jon
> > 
> > P.S. it seems that rst2pdf is actually being developed again:
> > https://akrabat.com/rst2pdf-back-from-the-dead/ .  I wonder how far
> > they'll get with it.  
> 
> Thanks,
> Mauro
> 
> [PATCH RFC] docs: experimental: build PDF with rst2pdf

There are a few issues with the quick hack to use rst2pdf. The
enclosed one works better.

Yet, from the existing 70 books (on my experimental tree), rst2pdf breaks 
with 14 ones.

It seems that the problem is related to broken cross-references. The html
builder handles it nicely, but rst2pdf seems to crash when it can't solve
all references. That sounds somewhat similar to the bug we solved with the
automarkup extension.


Thanks,
Mauro



[PATCH] docs: experimental: build PDF with rst2pdf

Change the logic to use rst2pdf instead of LaTeX.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>

diff --git a/Documentation/Makefile b/Documentation/Makefile
index e145e4db508b..a298bbcf6fa7 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -89,18 +89,22 @@ latexdocs:
 
 ifeq ($(HAVE_PDFLATEX),0)
 
-pdfdocs:
+oldpdfdocs:
 	$(warning The '$(PDFLATEX)' command was not found. Make sure you have it installed and in PATH to produce PDF output.)
 	@echo "  SKIP    Sphinx $@ target."
 
 else # HAVE_PDFLATEX
 
-pdfdocs: latexdocs
+oldpdfdocs: latexdocs
 	@$(srctree)/scripts/sphinx-pre-install --version-check
 	$(foreach var,$(SPHINXDIRS), $(MAKE) PDFLATEX="$(PDFLATEX)" LATEXOPTS="$(LATEXOPTS)" -C $(BUILDDIR)/$(var)/latex || exit;)
 
 endif # HAVE_PDFLATEX
 
+pdfdocs:
+	@$(srctree)/scripts/sphinx-pre-install --version-check
+	@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,pdf,$(var),pdf,$(var)))
+
 epubdocs:
 	@$(srctree)/scripts/sphinx-pre-install --version-check
 	@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,epub,$(var),epub,$(var)))
@@ -126,6 +130,7 @@ dochelp:
 	@echo  '  htmldocs        - HTML'
 	@echo  '  latexdocs       - LaTeX'
 	@echo  '  oldpdfdocs      - PDF'
+	@echo  '  pdfdocs         - PDF, using experimental rst2pdf support'
 	@echo  '  epubdocs        - EPUB'
 	@echo  '  xmldocs         - XML'
 	@echo  '  linkcheckdocs   - check for broken external links (will connect to external hosts)'
diff --git a/Documentation/conf.py b/Documentation/conf.py
index fa0a42b47e62..f53ea57aebe3 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -43,6 +43,8 @@ if (major == 1 and minor > 3) or (major > 1):
 else:
     extensions.append("sphinx.ext.pngmath")
 
+extensions.append("rst2pdf.pdfbuilder")
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
@@ -564,12 +566,15 @@ epub_exclude_files = ['search.html']
 #
 # See the Sphinx chapter of http://ralsina.me/static/manual.pdf
 #
-# FIXME: Do not add the index file here; the result will be too big. Adding
-# multiple PDF files here actually tries to get the cross-referencing right
-# *between* PDF files.
-pdf_documents = [
-    ('kernel-documentation', u'Kernel', u'Kernel', u'J. Random Bozo'),
-]
+
+# Add all LaTeX files to PDF documents as well
+pdf_documents = []
+for l in latex_documents:
+    doc = l[0]
+    fn = l[1].replace(".tex", "")
+    name = l[2]
+    authors = l[3]
+    pdf_documents.append((doc, fn, name, authors))
 
 # kernel-doc extension configuration for running Sphinx directly (e.g. by Read
 # the Docs). In a normal build, these are supplied from the Makefile via command
diff --git a/Documentation/media/Makefile b/Documentation/media/Makefile
index d75d70f191bc..3050136ed489 100644
--- a/Documentation/media/Makefile
+++ b/Documentation/media/Makefile
@@ -53,12 +53,13 @@ $(BUILDDIR)/lirc.h.rst: ${UAPI}/lirc.h ${PARSER} $(SRC_DIR)/lirc.h.rst.exception
 
 # Media build rules
 
-.PHONY: all html epub xml latex
+.PHONY: all html epub xml latex pdf
 
 all: $(IMGDOT) $(BUILDDIR) ${TARGETS}
 html: all
 epub: all
 xml: all
+pdf: all
 latex: $(IMGPDF) all
 linkcheck:
 
diff --git a/Makefile b/Makefile
index 5bbaf5ee6f5b..99ae519fccf9 100644
--- a/Makefile
+++ b/Makefile
@@ -1562,7 +1562,7 @@ $(help-board-dirs): help-%:
 # Documentation targets
 # ---------------------------------------------------------------------------
 DOC_TARGETS := xmldocs latexdocs pdfdocs htmldocs epubdocs cleandocs \
-	       linkcheckdocs dochelp refcheckdocs
+	       linkcheckdocs dochelp refcheckdocs oldpdfdocs
 PHONY += $(DOC_TARGETS)
 $(DOC_TARGETS): scripts_basic FORCE
 	$(Q)$(MAKE) $(build)=Documentation $@