[PATCH] docs: Instruct LaTeX to cope with deeper nesting

[PATCH] docs: Instruct LaTeX to cope with deeper nesting

[Jonathan Corbet]

The addition of the XFS online fsck documentation starting with
commit a8f6c2e54ddc ("xfs: document the motivation for online fsck design")
added a deeper level of nesting than LaTeX is prepared to deal with.  That
caused a pdfdocs build failure with the helpful "Too deeply nested" error
message buried deeply in Documentation/output/filesystems.log.

Increase the "maxlistdepth" parameter to instruct LaTeX that it needs to
deal with the deeper nesting whether it wants to or not.

Suggested-by: Akira Yokosawa <akiyks@gmail.com>
Link: https://lore.kernel.org/linux-doc/67f6ac60-7957-4b92-9d72-a08fbad0e028@gmail.com/
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
 Documentation/conf.py | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 5830b01c5642..da64c9fb7e07 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -388,6 +388,12 @@ latex_elements = {
         verbatimhintsturnover=false,
     ''',
 
+    #
+    # Some of our authors are fond of deep nesting; tell latex to
+    # cope.
+    #
+    'maxlistdepth': '10',
+
     # For CJK One-half spacing, need to be in front of hyperref
     'extrapackages': r'\usepackage{setspace}',
 
-- 
2.43.0

Re: [PATCH] docs: Instruct LaTeX to cope with deeper nesting

[Akira Yokosawa]

On Mon, 19 Feb 2024 09:05:38 -0700, Jonathan Corbet wrote:
> The addition of the XFS online fsck documentation starting with
> commit a8f6c2e54ddc ("xfs: document the motivation for online fsck design")
> added a deeper level of nesting than LaTeX is prepared to deal with.  That
> caused a pdfdocs build failure with the helpful "Too deeply nested" error
> message buried deeply in Documentation/output/filesystems.log.
> 
> Increase the "maxlistdepth" parameter to instruct LaTeX that it needs to
> deal with the deeper nesting whether it wants to or not.
> 
> Suggested-by: Akira Yokosawa <akiyks@gmail.com>
> Link: https://lore.kernel.org/linux-doc/67f6ac60-7957-4b92-9d72-a08fbad0e028@gmail.com/
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Tested-by: Akira Yokosawa <akiyks@gmail.com>

And it seems this one might deserve

Cc: stable@vger.kernel.org # v6.4

too, in case someone tries "make pdfdocs" against 6.6.x LTS 
and 6.7.x stable branches.

Commit a8f6c2e54ddc did nothing wrong on its own, so a Fixes: tag
is inappropriate here.

> ---
>  Documentation/conf.py | 6 ++++++
>  1 file changed, 6 insertions(+)
> 
> diff --git a/Documentation/conf.py b/Documentation/conf.py
> index 5830b01c5642..da64c9fb7e07 100644
> --- a/Documentation/conf.py
> +++ b/Documentation/conf.py
> @@ -388,6 +388,12 @@ latex_elements = {
>          verbatimhintsturnover=false,
>      ''',
>  
> +    #
> +    # Some of our authors are fond of deep nesting; tell latex to
> +    # cope.

I like this wording! :-)

        Thanks, Akira

> +    #
> +    'maxlistdepth': '10',
> +
>      # For CJK One-half spacing, need to be in front of hyperref
>      'extrapackages': r'\usepackage{setspace}',
>

Re: [PATCH] docs: Instruct LaTeX to cope with deeper nesting

[Jonathan Corbet]

Akira Yokosawa <akiyks@gmail.com> writes:

> On Mon, 19 Feb 2024 09:05:38 -0700, Jonathan Corbet wrote:
>> The addition of the XFS online fsck documentation starting with
>> commit a8f6c2e54ddc ("xfs: document the motivation for online fsck design")
>> added a deeper level of nesting than LaTeX is prepared to deal with.  That
>> caused a pdfdocs build failure with the helpful "Too deeply nested" error
>> message buried deeply in Documentation/output/filesystems.log.
>> 
>> Increase the "maxlistdepth" parameter to instruct LaTeX that it needs to
>> deal with the deeper nesting whether it wants to or not.
>> 
>> Suggested-by: Akira Yokosawa <akiyks@gmail.com>
>> Link: https://lore.kernel.org/linux-doc/67f6ac60-7957-4b92-9d72-a08fbad0e028@gmail.com/
>> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
>
> Tested-by: Akira Yokosawa <akiyks@gmail.com>

Thanks

> And it seems this one might deserve
>
> Cc: stable@vger.kernel.org # v6.4
>
> too, in case someone tries "make pdfdocs" against 6.6.x LTS 
> and 6.7.x stable branches.

Agreed, that was in my plans.

> Commit a8f6c2e54ddc did nothing wrong on its own, so a Fixes: tag
> is inappropriate here.

And a Fixes tag was definitely *not* in the plan.

Thanks,

jon

Re: [PATCH] docs: Instruct LaTeX to cope with deeper nesting

[Akira Yokosawa]

On Tue, 20 Feb 2024 14:55:03 -0700, Jonathan Corbet wrote:
> Akira Yokosawa <akiyks@gmail.com> writes:
> 
>> On Mon, 19 Feb 2024 09:05:38 -0700, Jonathan Corbet wrote:
>>> The addition of the XFS online fsck documentation starting with
>>> commit a8f6c2e54ddc ("xfs: document the motivation for online fsck design")
>>> added a deeper level of nesting than LaTeX is prepared to deal with.  That
>>> caused a pdfdocs build failure with the helpful "Too deeply nested" error
>>> message buried deeply in Documentation/output/filesystems.log.
>>>
>>> Increase the "maxlistdepth" parameter to instruct LaTeX that it needs to
>>> deal with the deeper nesting whether it wants to or not.
>>>
>>> Suggested-by: Akira Yokosawa <akiyks@gmail.com>
>>> Link: https://lore.kernel.org/linux-doc/67f6ac60-7957-4b92-9d72-a08fbad0e028@gmail.com/
>>> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
>>
>> Tested-by: Akira Yokosawa <akiyks@gmail.com>
> 
> Thanks
> 
>> And it seems this one might deserve
>>
>> Cc: stable@vger.kernel.org # v6.4
>>
>> too, in case someone tries "make pdfdocs" against 6.6.x LTS 
>> and 6.7.x stable branches.
> 
> Agreed, that was in my plans.
> 
>> Commit a8f6c2e54ddc did nothing wrong on its own, so a Fixes: tag
>> is inappropriate here.
> 
> And a Fixes tag was definitely *not* in the plan.

Now I see this in docs-fixes.

BTW, I expected Vergard's fix to the translations extension would
also be in the -fixes branch, but it is now in the -mw branch as
commit 2bd6f4d99e12.

Can you please have a look at it?

        Thanks, Akira

> 
> Thanks,
> 
> jon

Re: [PATCH] docs: Instruct LaTeX to cope with deeper nesting

[Jonathan Corbet]

Akira Yokosawa <akiyks@gmail.com> writes:

> BTW, I expected Vergard's fix to the translations extension would
> also be in the -fixes branch, but it is now in the -mw branch as
> commit 2bd6f4d99e12.

Yeah, I'd meant to do that, got caught up in the PDF nightmare.  I'll
put it there; that will force a rebase onto docs-next, but so it goes.

Thanks,

jon