linux-kernel - Re: [RFC PATCH 0/3] Documentation: switch to pdflatex and fix pdf 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: <CD125DBD-3451-4CFF-92B8-82B90F747C12@darmarit.de>
Date:	Sat, 13 Aug 2016 18:00:59 +0200
From:	Markus Heiser <markus.heiser@...marit.de>
To:	Jonathan Corbet <corbet@....net>
Cc:	Jani Nikula <jani.nikula@...el.com>,
	Mauro Carvalho Chehab <mchehab@...radead.org>,
	"Luis R. Rodriguez" <mcgrof@...nel.org>, linux-doc@...r.kernel.org,
	"linux-kernel@...r.kernel.org" <linux-kernel@...r.kernel.org>,
	Mauro Carvalho Chehab <mchehab@....samsung.com>,
	Daniel Vetter <daniel.vetter@...ll.ch>
Subject: Re: [RFC PATCH 0/3] Documentation: switch to pdflatex and fix pdf build


Am 13.08.2016 um 00:40 schrieb Jonathan Corbet <corbet@....net>:

> On Wed, 10 Aug 2016 18:54:06 +0300
> Jani Nikula <jani.nikula@...el.com> wrote:
> 
>> With these you should be able to get started with pdf generation. It's a
>> quick transition to pdflatex, the patches are not very pretty, but the
>> pdf output is. Patch 3/3 works as an example where to add your stuff
>> (latex_documents in conf.py) and how.
> 
> OK, now I have a bone to pick with you.
> 
> I applied this, then decided to install the needed toolchain on the
> Tumbleweed system I've been playing with; it wanted to install 1,727
> packages to get pdflatex.  Pandoc just doesn't seem so bad anymore.

I'am complete disenchanted on this topic. My experience is:

1) You wan't get any reasonable typesetting engine which preserves
your disk space. I don't know how many files or packages are installed,
the only thing I know is, a TeX installation is always >1GB.

2) You wan't get a (pdf, ps,..) book with a perfect layout without
any handcraft or at least a *theming*. TeX has many options to influence
the layout and Sphinx provides it's own LaTeX-document class (sphinxmanual)
which is IMHO awful.

> So I switched to the Fedora system, and found myself in a twisty maze of
> missing font files, missing style files, missing babel crap, etc., each
> doled out to me one file per run.  But I did eventually get PDFs out of
> it.

On debian it should be enough to install *base* and *recommended*

    sudo apt-get install
          texlive-base texlive-latex-recommended

> The output isn't great; among other things, it seems to be about 1/2 blank
> pages.

1/2 ? .. I have only empty pages at the start of parts or chapters, which
is a typical layout setting.

>  But it's something.

This is the sphinxmanual document class.
 
> I've applied this so we have something to play with, but it doesn't feel
> like a great solution.  This is the sort of installation hell that we
> wanted to get away from.  

See above, on debian it should be enough to install the two meta packages.

> It makes me wonder how hard it can really be to
> fix rst2pdf; I wish I could say I'll find some time to figure that out.
> Sigh.

I gave it a try, but as I come closer to the sources I realized that
it is hair-raising. I looked at the issues, added a comment to a related
issue, a few days later the issue was closed without any comment or code
change.

https://github.com/rst2pdf/rst2pdf/issues/556#issuecomment-228779542

My advice, if you don't like to waste your time: forget it.

Some thoughts of mine, wrote in an earlier mail:

> The sphinx-doc build-in LaTeX builder
> 
> * http://www.sphinx-doc.org/en/stable/config.html#options-for-latex-output
> 
> has some drawbacks, e.g. it produce LaTeX for the pdfTeX engine.
> LaTeX is by default ASCII and it needs some "inputenc" to supporta wider
> range of characters. This is not very helpful if you have a toolchain
> in an international community.
> 
> The alternative to LaTeX is to use the XeTeX engine, which supports UTF-8
> encoded input by default and supports TrueType/OpenType fonts directly.
> Thats why I started to write a XeLaTeX builder ...
> 
> * https://github.com/return42/sphkerneldoc/blob/master/scripts/site-python/xelatex_ext/__init__.py#L15 
> 
> ... but I can't predict when this will be finished ...
> 
> However which tool is used, my experience is, that building
> PDF (books) with a minimum of quality is not simple.
> Layout width tables, split table content over pages, switch
> from landscape to portrait and versus, the flow of objects etc.
> .. all this will need some manually interventions.


-- Markus --