PDF misery

[Jonathan Corbet <corbet@lwn.net>]

So, FYI, I have Vegard's PDF-generation fix applied here, but I've not
pushed it yet (even though I think it's fine) because I wanted to be
sure that all was well with PDF generation.  Bear with me as I ramble
for a bit...

I'll confess to not paying as much attention to PDF output as I should.
Partly that's from a perception that not many people care about it
(though a few really do), and partly because PDF generation has always
been a bit of a house of cards that turns into a real pain whenever
anybody looks at it hard.

Somebody looked at it hard.

My fairly standard Fedora 39 system can't do a pdfdocs build at all.
There are a couple of untoward things that get in the way.

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:

-----
diff --git a/Documentation/filesystems/xfs/xfs-online-fsck-design.rst b/Documentation/filesystems/xfs/xfs-online-fsck-design.rst
index 352516feef6f..1762a9415ec1 100644
--- a/Documentation/filesystems/xfs/xfs-online-fsck-design.rst
+++ b/Documentation/filesystems/xfs/xfs-online-fsck-design.rst
@@ -739,15 +739,6 @@ For a given fstests filesystem configuration:
         7. Subtract a small quantity
         8. Randomize the contents
 
-        * ...test the reactions of:
-
-          1. The kernel verifiers to stop obviously bad metadata
-          2. Offline checking (``xfs_repair -n``)
-          3. Offline repair (``xfs_repair``)
-          4. Online checking (``xfs_scrub -n``)
-          5. Online repair (``xfs_scrub``)
-          6. Both repair tools (``xfs_scrub`` and then ``xfs_repair`` if online repair doesn't succeed)
-
 This is quite the combinatoric explosion!
 
 Fortunately, having this much test coverage makes it easy for XFS developers to
@@ -2093,7 +2084,6 @@ of the records, so naturally the xfarray must also support sorting the record
 set prior to bulk loading.
 
 Case Study: Sorting xfarrays
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The sorting algorithm used in the xfarray is actually a combination of adaptive
 quicksort and a heapsort subalgorithm in the spirit of

-----
The first change removes the deepest level of nesting in an impressive
set of enumerated lists; the second removes the nth-level subsection
heading markup for "Sorting xfarrays".  Having either of those present
will cause Latex to blow a fuse.

I'm surprised that nobody else is reporting this problem.  I honestly
don't see a fix other than changing the organization of the document to
avoid both deeply nested itemized lists and section structure, which is
less than entirely desirable.  I think there are good reasons for
avoiding structures that deep, but limitations in the tooling aren't one
of them.

Incidentally, on F38, I also run into a similar Latex error in
.../userspace-api/media/v4l/pixfmt-rgb.html, which has a set of tables
from hell.  On F39, that somehow works.  Weird.

The *other* problem is that PDF generation of the Chinese, Korean, or
Japanese translations fails with:

  xdvipdfmx:fatal: Invalid TTC index number

This, I am thinking, is likely some sort of F39 bug.  xdvipdfmx is
finding the CJK fonts just fine, but then something clearly goes wrong.
I'll try to find the time to narrow that down and perhaps put in a
proper bug report.

Meanwhile, I wish I knew what to do to make the PDF build a bit more
robust.  I wish that rst2pdf or rinohtype would progress to the point
where they could be used, and Latex could be taken out of the picture,
but no such luck.

Oh well...sorry for rambling at you...I wish I had a good plan for
making this whole thing better.

jon