Merge branch 'xelatex' into doc/4.9

Mauro says:

	This patch series fix Sphinx to allow it to build the media
	documentation as a PDF file.

	The first patch is actually a bug fix: one of the previous patch
	broke compilation for PDF as a hole, as it added an extra
	parenthesis to a function call.

	The second patch just removes a left over code for rst2pdf.

	The other patches change from "pdflatex" to "xelatex" and address
	several issues that prevent building the media books.

	I think this patch series belong to docs-next. Feel free to merge
	them there, if you agree. There's one extra patch that touches
	Documentation/conf.py, re-adding the media book to the PDF build,
	but IMHO this one would be better to be merged via the media tree,
	after the fixes inside the media documentation to fix the build.

3 files changed, 60 insertions, 16 deletions

diff --git a/Documentation/Makefile.sphinx b/Documentation/Makefile.sphinx
index ea0664cece12..ba4efb1f68f3 100644
--- a/Documentation/Makefile.sphinx
+++ b/Documentation/Makefile.sphinx
@@ -29,7 +29,7 @@ else ifneq ($(DOCBOOKS),)
 else # HAVE_SPHINX
 
 # User-friendly check for pdflatex
-HAVE_PDFLATEX := $(shell if which pdflatex >/dev/null 2>&1; then echo 1; else echo 0; fi)
+HAVE_PDFLATEX := $(shell if which xelatex >/dev/null 2>&1; then echo 1; else echo 0; fi)
 
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
@@ -68,11 +68,11 @@ htmldocs:
 
 pdfdocs:
 ifeq ($(HAVE_PDFLATEX),0)
-	$(warning The 'pdflatex' command was not found. Make sure you have it installed and in PATH to produce PDF output.)
+	$(warning The 'xelatex' command was not found. Make sure you have it installed and in PATH to produce PDF output.)
 	@echo "  SKIP    Sphinx $@ target."
 else # HAVE_PDFLATEX
-	@$(call loop_cmd,sphinx,latex,.,latex,.))
-	$(Q)$(MAKE) -C $(BUILDDIR)/latex
+	@$(call loop_cmd,sphinx,latex,.,latex,.)
+	$(Q)$(MAKE) PDFLATEX=xelatex LATEXOPTS="-interaction=nonstopmode" -C $(BUILDDIR)/latex
 endif # HAVE_PDFLATEX
 
 epubdocs:
diff --git a/Documentation/conf.py b/Documentation/conf.py
index 43e41ed74584..23e2f0bbcfc8 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -14,6 +14,11 @@
 
 import sys
 import os
+import sphinx
+
+# Get Sphinx version
+major, minor, patch = map(int, sphinx.__version__.split("."))
+
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -31,12 +36,11 @@ from load_config import loadConfig
 # ones.
 extensions = ['kernel-doc', 'rstFlatTable', 'kernel_include']
 
-# Gracefully handle missing rst2pdf.
-try:
-    import rst2pdf
-    extensions += ['rst2pdf.pdfbuilder']
-except ImportError:
-    pass
+# The name of the math extension changed on Sphinx 1.4
+if minor > 3:
+    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']
@@ -253,16 +257,56 @@ htmlhelp_basename = 'TheLinuxKerneldoc'
 
 latex_elements = {
 # The paper size ('letterpaper' or 'a4paper').
-#'papersize': 'letterpaper',
+'papersize': 'a4paper',
 
 # The font size ('10pt', '11pt' or '12pt').
-#'pointsize': '10pt',
-
-# Additional stuff for the LaTeX preamble.
-#'preamble': '',
+'pointsize': '8pt',
 
 # Latex figure (float) alignment
 #'figure_align': 'htbp',
+
+# Don't mangle with UTF-8 chars
+'inputenc': '',
+'utf8extra': '',
+
+# Additional stuff for the LaTeX preamble.
+    'preamble': '''
+	% Adjust margins
+	\\usepackage[margin=0.5in, top=1in, bottom=1in]{geometry}
+
+        % Allow generate some pages in landscape
+        \\usepackage{lscape}
+
+        % Put notes in gray color and let them be inside a table
+
+        \\definecolor{MyGray}{rgb}{0.80,0.80,0.80}
+
+        \\makeatletter\\newenvironment{graybox}{%
+           \\begin{lrbox}{\\@tempboxa}\\begin{minipage}{\\columnwidth}}{\\end{minipage}\\end{lrbox}%
+           \\colorbox{MyGray}{\\usebox{\\@tempboxa}}
+        }\\makeatother
+
+        \\makeatletter
+        \\renewenvironment{notice}[2]{
+          \\begin{graybox}
+          \\bf\\it
+          \\def\\py@noticetype{#1}
+          \\par\\strong{#2}
+          \\csname py@noticestart@#1\\endcsname
+        }
+	{
+          \\csname py@noticeend@\\py@noticetype\\endcsname
+          \\end{graybox}
+        }
+	\\makeatother
+
+	% Use some font with UTF-8 support with XeLaTeX
+        \\usepackage{fontspec}
+        \\setsansfont{DejaVu Serif}
+        \\setromanfont{DejaVu Sans}
+        \\setmonofont{DejaVu Sans Mono}
+
+     '''
 }
 
 # Grouping the document tree into LaTeX files. List of tuples
diff --git a/Documentation/sphinx/parse-headers.pl b/Documentation/sphinx/parse-headers.pl
index 34bd9e2630b0..74089b0da798 100755
--- a/Documentation/sphinx/parse-headers.pl
+++ b/Documentation/sphinx/parse-headers.pl
@@ -220,7 +220,7 @@ $data =~ s/\n\s+\n/\n\n/g;
 #
 # Add escape codes for special characters
 #
-$data =~ s,([\_\`\*\<\>\&\\\\:\/\|]),\\$1,g;
+$data =~ s,([\_\`\*\<\>\&\\\\:\/\|\%\$\#\{\}\~\^]),\\$1,g;
 
 $data =~ s,DEPRECATED,**DEPRECATED**,g;