[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 1/5] docs: don't use nested tables

[Mauro Carvalho Chehab]

Nested tables aren't supported for pdf output on Sphinx 1.7.9:

	admin-guide/laptops/sonypi:: nested tables are not yet implemented.
	admin-guide/laptops/toshiba_haps:: nested tables are not yet implemented.
	driver-api/nvdimm/btt:: nested tables are not yet implemented.
	s390/debugging390:: nested tables are not yet implemented.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 Documentation/admin-guide/laptops/sonypi.rst  | 26 +++++++++----------
 .../admin-guide/laptops/toshiba_haps.rst      |  8 +++---
 Documentation/driver-api/nvdimm/btt.rst       |  2 +-
 Documentation/s390/debugging390.rst           |  2 +-
 4 files changed, 18 insertions(+), 20 deletions(-)

diff --git a/Documentation/admin-guide/laptops/sonypi.rst b/Documentation/admin-guide/laptops/sonypi.rst
index 2a1975ed7ee4..c6eaaf48f7c1 100644
--- a/Documentation/admin-guide/laptops/sonypi.rst
+++ b/Documentation/admin-guide/laptops/sonypi.rst
@@ -53,7 +53,7 @@ module or sonypi.<param>=<value> on the kernel boot line when sonypi is
 statically linked into the kernel). Those options are:
 
 	=============== =======================================================
-	minor: 		minor number of the misc device /dev/sonypi,
+	minor:		minor number of the misc device /dev/sonypi,
 			default is -1 (automatic allocation, see /proc/misc
 			or kernel logs)
 
@@ -89,24 +89,22 @@ statically linked into the kernel). Those options are:
 			set to 0xffffffff, meaning that all possible events
 			will be tried. You can use the following bits to
 			construct your own event mask (from
-			drivers/char/sonypi.h):
+			drivers/char/sonypi.h)::
 
-				========================	======
-				SONYPI_JOGGER_MASK 		0x0001
-				SONYPI_CAPTURE_MASK 		0x0002
-				SONYPI_FNKEY_MASK 		0x0004
-				SONYPI_BLUETOOTH_MASK 		0x0008
-				SONYPI_PKEY_MASK 		0x0010
-				SONYPI_BACK_MASK 		0x0020
-				SONYPI_HELP_MASK 		0x0040
-				SONYPI_LID_MASK 		0x0080
-				SONYPI_ZOOM_MASK 		0x0100
-				SONYPI_THUMBPHRASE_MASK 	0x0200
+				SONYPI_JOGGER_MASK		0x0001
+				SONYPI_CAPTURE_MASK		0x0002
+				SONYPI_FNKEY_MASK		0x0004
+				SONYPI_BLUETOOTH_MASK		0x0008
+				SONYPI_PKEY_MASK		0x0010
+				SONYPI_BACK_MASK		0x0020
+				SONYPI_HELP_MASK		0x0040
+				SONYPI_LID_MASK			0x0080
+				SONYPI_ZOOM_MASK		0x0100
+				SONYPI_THUMBPHRASE_MASK		0x0200
 				SONYPI_MEYE_MASK		0x0400
 				SONYPI_MEMORYSTICK_MASK		0x0800
 				SONYPI_BATTERY_MASK		0x1000
 				SONYPI_WIRELESS_MASK		0x2000
-				========================	======
 
 	useinput:	if set (which is the default) two input devices are
 			created, one which interprets the jogdial events as
diff --git a/Documentation/admin-guide/laptops/toshiba_haps.rst b/Documentation/admin-guide/laptops/toshiba_haps.rst
index 11dfc428c080..d28b6c3f2849 100644
--- a/Documentation/admin-guide/laptops/toshiba_haps.rst
+++ b/Documentation/admin-guide/laptops/toshiba_haps.rst
@@ -75,11 +75,11 @@ The sysfs files under /sys/devices/LNXSYSTM:00/LNXSYBUS:00/TOS620A:00/ are:
 protection_level   The protection_level is readable and writeable, and
 		   provides a way to let userspace query the current protection
 		   level, as well as set the desired protection level, the
-		   available protection levels are:
+		   available protection levels are::
 
-		   ============   =======   ==========   ========
-		   0 - Disabled   1 - Low   2 - Medium   3 - High
-		   ============   =======   ==========   ========
+		     ============   =======   ==========   ========
+		     0 - Disabled   1 - Low   2 - Medium   3 - High
+		     ============   =======   ==========   ========
 
 reset_protection   The reset_protection entry is writeable only, being "1"
 		   the only parameter it accepts, it is used to trigger
diff --git a/Documentation/driver-api/nvdimm/btt.rst b/Documentation/driver-api/nvdimm/btt.rst
index 2d8269f834bd..107395c042ae 100644
--- a/Documentation/driver-api/nvdimm/btt.rst
+++ b/Documentation/driver-api/nvdimm/btt.rst
@@ -83,7 +83,7 @@ flags, and the remaining form the internal block number.
 ======== =============================================================
 Bit      Description
 ======== =============================================================
-31 - 30	 Error and Zero flags - Used in the following way:
+31 - 30	 Error and Zero flags - Used in the following way::
 
 	   == ==  ====================================================
 	   31 30  Description
diff --git a/Documentation/s390/debugging390.rst b/Documentation/s390/debugging390.rst
index d49305fd5e1a..73ad0b06c666 100644
--- a/Documentation/s390/debugging390.rst
+++ b/Documentation/s390/debugging390.rst
@@ -170,7 +170,7 @@ currently running at.
 |        +----------------+-------------------------------------------------+
 |        |    32          | Basic Addressing Mode                           |
 |        |                |                                                 |
-|        |                | Used to set addressing mode                     |
+|        |                | Used to set addressing mode::                   |
 |        |                |                                                 |
 |        |                |    +---------+----------+----------+            |
 |        |                |    | PSW 31  | PSW 32   |          |            |
-- 
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 $@