linux-kernel - [PATCH 04/17] Changes.rst: add minimal requirements for documentation build

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-Id: <38cce9fcfe7fea8f5da435f47a5f883f9e4b9306.1473893776.git.mchehab@s-opensource.com>
Date:   Wed, 14 Sep 2016 20:05:49 -0300
From:   Mauro Carvalho Chehab <mchehab@...pensource.com>
To:     Linux Doc Mailing List <linux-doc@...r.kernel.org>
Cc:     Mauro Carvalho Chehab <mchehab@...pensource.com>,
        Mauro Carvalho Chehab <mchehab@...radead.org>,
        Jonathan Corbet <corbet@....net>,
        Mauro Carvalho Chehab <mchehab@...nel.org>,
        David Woodhouse <David.Woodhouse@...el.com>,
        Benoit Lemarchand <benoit.lemarchand@...il.com>,
        David Howells <dhowells@...hat.com>,
        Markus Heiser <markus.heiser@...marit.de>,
        Jani Nikula <jani.nikula@...ux.intel.com>,
        LKML <linux-kernel@...r.kernel.org>
Subject: [PATCH 04/17] Changes.rst: add minimal requirements for documentation build

As discussed at linux-doc ML, the best is to keep all documents
backward compatible with Sphinx version 1.2, as it is the latest
version found on some distros like Debian.

All books currently support it.

Please notice that, while it mentions the eventual need of
XeLaTex and texlive to build pdf files, this is not a minimal
requirement, as one could just be interested on building html
documents. Also, identifying the minimal requirements for
texlive packages is not trivial, as each distribution seems to
use different criteria on grouping LaTex functionalities.

While here, update the current kernel version to 4.x.

Signed-off-by: Mauro Carvalho Chehab <mchehab@...pensource.com>
---
 Documentation/development-process/Changes.rst | 36 ++++++++++++++++++++++++++-
 1 file changed, 35 insertions(+), 1 deletion(-)

diff --git a/Documentation/development-process/Changes.rst b/Documentation/development-process/Changes.rst
index 97f7bf178340..754cd50c1bc6 100644
--- a/Documentation/development-process/Changes.rst
+++ b/Documentation/development-process/Changes.rst
@@ -7,7 +7,7 @@ Intro
 =====
 
 This document is designed to provide a list of the minimum levels of
-software necessary to run the 3.0 kernels.
+software necessary to run the 4.x kernels.
 
 This document is originally based on my "Changes" file for 2.0.x kernels
 and therefore owes credit to the same people as that file (Jared Mauch,
@@ -53,8 +53,10 @@ mcelog                 0.6              mcelog --version
 iptables               1.4.2            iptables -V
 openssl & libcrypto    1.0.0            openssl version
 bc                     1.06.95          bc --version
+Sphinx\ [#f1]_	       1.2		sphinx-build --version
 ====================== ===============  ========================================
 
+.. [#f1] Sphinx is needed only to build the Kernel documentation
 
 Kernel compilation
 ******************
@@ -309,6 +311,30 @@ On x86 kernels the mcelog utility is needed to process and log machine check
 events when ``CONFIG_X86_MCE`` is enabled. Machine check events are errors
 reported by the CPU. Processing them is strongly encouraged.
 
+Kernel documentation
+********************
+
+Sphinx
+------
+
+The ReST markups currently used by the Documentation/ files are meant to be
+built with ``Sphinx`` version 1.2 or upper. If you're desiring to build
+PDF outputs, it is recommended to use version 1.4.6.
+
+.. note::
+
+  Please notice that, for PDF and LaTeX output, you'll also need ``XeLaTeX``
+  version 3.14159265. Depending on the distribution, you may also need
+  to install a series of ``texlive`` packages that provide the minimal
+  set of functionalities required for ``XeLaTex`` to work.
+
+Other tools
+-----------
+
+In order to produce documentation from DocBook, you'll also need ``xmlto``.
+Please notice, however, that we're currently migrating all documents to use
+``Sphinx``.
+
 Getting updated software
 ========================
 
@@ -455,3 +481,11 @@ NFS-Utils
 ---------
 
 - <http://nfs.sourceforge.net/>
+
+Kernel documentation
+********************
+
+Sphinx
+------
+
+- <http://www.sphinx-doc.org/>
-- 
2.7.4