Re: PDF misery

[Mauro Carvalho Chehab <mchehab@kernel.org>]

Em Mon, 19 Feb 2024 00:49:08 +0900
Akira Yokosawa <akiyks@gmail.com> escreveu:

> Hi,
> 
> On 2024/02/18 6:29, Jonathan Corbet wrote:
> ...
> > One is the dreaded Latex "too deeply nested" message that causes
> > everything to explode while generating filesystems.pdf.  The problem,
> > specifically, is .../filesystems/xfs/xfs-online-fsck-design.rst, which
> > blows the limits in two ways.  This patch "fixes" it - this clearly
> > isn't something to apply, it's just a demonstration of the problem:  
> 
> So, there is a handy answer in the Sphinx documentation.
> 
> Just look at https://www.sphinx-doc.org/en/master/latex.html
> and search 'maxlistdepth'.

Hmm... there are some other interesting options there, like the
verbatim ones. One of the problems that required lots of changes at
the media uAPI part of the docs is because code blocks are reproduced
as-is, without wrapping, making them to either be truncated or going
past the margin. That's specially painful on code blocks inside tables.

The way it was solved was this this patch:

	3b4c963243b1 ("docs: conf.py: adjust the LaTeX document output")

plus several changes on media docs with redesign changes (before and after
the above patch), plus several and several macros at the .rst files to
change font size and carefully adjusting columns sizes on tables.

It sounds that since then other verbatim options got added. So, perhaps
the PDF output could be improved on newer Sphinx versions.

> 
> You can set this variable in conf.py, say,
> 
>     'maxlistdepth': '9',

Good catch!

> 
> Now the deep lists in xfs-online-fsck-design.rst can be built
> into PDF.
> 
> Problem solved.
> 
> It's getting late here, so can anybody prepare a proper patch
> with my
> 
> Suggested-by: Akira Yokosawa <akiyks@gmail.com>
> 
> ?
> 
>         Thanks, Akira



Thanks,
Mauro