Latex: long option name overflows in Index

[marxin]

Describe the bug

Let's consider something like:

.. option:: -Wauggest-attribute=[pure|const|noreturn|format|cold|malloc]

   Suggest it.

Leads to the following with xelatex.

@jfbu

How to Reproduce

Build snippet.

Expected behavior

No response

Your project

Build the snippet

Screenshots

No response

OS

Linux

Python version

3.8

Sphinx version

4.3.0

Sphinx extensions

No response

Extra tools

No response

Additional context

No response

[jfbu]

Sphinx's make latexpdf uses LaTeX. And LaTeX has its limitations. Often as author of a document you can work around them, depending on level of mastering LaTeX. But solving all layout problems in a general way is impossible. Sphinx goes to great lengths already for some problems with grid tables and other areas.

In the case at hand, take any LaTeX document and add

successful|successful|successful|successful|successful|successful|successful|successful|successful|successful|successful|successful|successful|successful|successful|successful|successful|successful|successful|successful

to the tex file and compile to pdf. You will end up with a line extending and disappearing into the margin. Turns out TeX will not even hyphenate the word successful in this context, independent whether using pdftex or xetex, roman or monospace font family. And it never inserts out-of-the-box a linebreak at a |.

However in the Sphinx case you can look at the files in the latex build repertory and contributing to the latex runs. You will see in the file with extension .ind that contains the LaTeX mark-up for that part of the document typesetting the index that the | has been escaped to \textbar{}.

As LaTeX is a macro language you can redefine \textbar to allow a linebreak. You probably want to localize this to the index so the simplest is to check the Sphinx docs for the latex index, search for index in the sphinx latex docs you will see keys 'makeindex' and 'printindex'. Modifying the later default definition we can do this

latex_elements = {
    'printindex': r"""
\let\originaltextbar\textbar\def\textbar{\originaltextbar\linebreak[0]}
\printindex
""",
}

and there will linebreaks (inside the column of the per default 2-columns layout for the index) after the |.

You may wish to combine this (or replace this) with one or both of these additional LaTeX snippets inside the 'printindex' key value:

• \footnotesize\raggedright to use a smaller font size and avoid TeX stretching whitespace to try to justify paragraphs,
• \def\twocolumn[#1]{#1} to have a one-column, not two-column layout.

It is also possible to try to do something with the macro \sphinxstyleindexentry which one sees in the .ind file is the meaning assigned to the \spxentry mark-up. Its default, found in the sphinxlatexstyletext.sty file one finds in the latex build repertory of the current project is \def\sphinxstyleindexentry #1{\texttt{#1}} which simply says it uses monospace font. It is possible to redefine this to do whatever is needed, but will be reexecuted at each index entry. Hence I preferred the approach above which does a global redefinition of \textbar at the final part of the document where the index is printed.

[marxin]

Thanks for the suggestions. To be honest, the issue is related to #9965, where I would ideally do something like:

.. option:: -Wauggest-attribute=:samp:`={style}`

  :samp:`{style}` can any of `[pure|const|noreturn|format|cold|malloc]`

   Suggest it.

Note it's important style is in italic as it symbols that style is a variable and not one of the option values.
What do you think about it?

[jakobandersen]

How about changing the option directive to no put the part after = in the index entry? That is, the offending case will just get the index entry -Wsuggest-attribute.

[marxin]

How about changing the option directive to no put the part after = in the index entry? That is, the offending case will just get the index entry -Wsuggest-attribute.

Good idea, I've just made a pull request.