Re: [RFC PATCH 0/3] Documentation: switch to pdflatex and fix pdf build

[Markus Heiser]

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

> On Wed, 10 Aug 2016 18:54:06 +0300
> Jani Nikula <jani.nikula@xxxxxxxxx> 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 --