Latex: do not allow splitting for :option: roles

[marxin]

Describe the bug

For:

Use these options: :option:`-Wno-shift-overflow3` :option:`-Wno-shift-overflow3` :option:`-Wno-shift-overflow3` :option:`-Wno-shift-overflow3` :option:`-Wno-shift-overflow3` :option:`-Wno-shift-overflow3` :option:`-Wno-shift-overflow3` :option:`-Wno-shift-overflow3` :option:`-Wno-shift-overflow3` :option:`-Wno-shift-overflow3` :option:`-Wno-shift-overflow3` :option:`-Wno-shift-overflow3` :option:`-Wno-shift-overflow3` :option:`-Wno-shift-overflow3`.

I don't want to allow splitting of the options:

How to Reproduce

Build the 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

[marxin]

HTML counter-part was #9909. CCing @jfbu.

[jfbu]

What is LaTeX engine, pdflatex or xelatex?

Update: surely xelatex, as I reproduced it with it.

With the default setting I can not reproduce:

from

xxxxxxxxxxxxxxx 123456 123456 123456 12 Use these options: :option:`-Wno-shift-overflow3` :option:`-Wno-shift-overflow3` :option:`-Wno-shift-overflow3` :option:`-Wno-shift-overflow3` :option:`-Wno-shift-overflow3` :option:`-Wno-shift-overflow3` :option:`-Wno-shift-overflow3` :option:`-Wno-shift-overflow3` :option:`-Wno-shift-overflow3` :option:`-Wno-shift-overflow3` :option:`-Wno-shift-overflow3` :option:`-Wno-shift-overflow3` :option:`-Wno-shift-overflow3` :option:`-Wno-shift-overflow3`.

xxxxxxxxxxxxxxx 123456 123456 123456 1 Use these options: :option:`-Wno-shift-overflow3` :option:`-Wno-shift-overflow3` :option:`-Wno-shift-overflow3` :option:`-Wno-shift-overflow3` :option:`-Wno-shift-overflow3` :option:`-Wno-shift-overflow3` :option:`-Wno-shift-overflow3` :option:`-Wno-shift-overflow3` :option:`-Wno-shift-overflow3` :option:`-Wno-shift-overflow3` :option:`-Wno-shift-overflow3` :option:`-Wno-shift-overflow3` :option:`-Wno-shift-overflow3` :option:`-Wno-shift-overflow3`.

and default settings (in particular letter size paper).

Could you post the actual LaTeX mark-up as seen in the .tex file ? At my locale it involves:

{\hyperref[\detokenize{index:cmdoption-11}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{\sphinxhyphen{}Wno\sphinxhyphen{}shift\sphinxhyphen{}overflow3}}}}}

It appears that \sphinxcode which does by default \texttt (monospace font) is what prevents linebreaks.

But, for xelatex, fonts behave differently. Try this in conf.py

latex_elements = {
    'preamble': r'\def\sphinxhyphen{\mbox{-}}',
}

The actual bug here may be that the linebreaks were not observed with pdflatex: the latex code comments say

sphinx/sphinx/texinputs/sphinxlatexstyletext.sty

Lines 77 to 80 in edd1478

	% It inserts a potential breakpoint after the hyphen. This is to keep in sync
	% with behavior in code-blocks, parsed and inline literals. For a breakpoint
	% before the hyphen use \leavevmode\kern\z@- (within \makeatletter/\makeatother)
	\protected\def\sphinxhyphen#1{-\kern\z@}

so it seems linebreaks were expected. But the \texttt{} with pdflatex prevents them...

[jfbu]

Memo: this issue also has to do with the

\defaultfontfeatures[\rmfamily,\sffamily,\ttfamily]{}

which was added at #6888 to the latex preamble when using xelatex engine in order to fix #6886.

Without it xelatex like pdflatex would not have linebreaks after dashes when using monospace font family. But this addition fixed the #6886 (and see also related #6890) problems with curly quotes .

[marxin]

Update: surely xelatex, as I reproduced it with it.

Yes, I use latex_engine = 'xelatex'.

[marxin]

But, for xelatex, fonts behave differently. Try this in conf.py

latex_elements = {
    'preamble': r'\def\sphinxhyphen{\mbox{-}}',
}

I can confirm this fixes the problem! You can build my project with:

git clone https://github.com/marxin/texi2rst-generated
cd texi2rst-generated/sphinx/demo
make latexpdf

[marxin]

Could you post the actual LaTeX mark-up as seen in the .tex file ? At my locale it involves:

Use these options: {\hyperref[\detokenize{demo:cmdoption-Wno-shift-overflow3}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{\sphinxhyphen{}Wno\sphinxhyphen{}shift\sphinxhyphen{}overflow3}}}}} {\hyperref[\detokenize{demo:cmdoption-Wno-shift-overflow3}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{\sphinxhyphen{}Wno\sphinxhyphen{}shift\sphinxhyphen{}overflow3}}}}} {\hyperref[\detokenize{demo:cmdoption-Wno-shift-overflow3}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{\sphinxhyphen{}Wno\sphinxhyphen{}shift\sphinxhyphen{}overflow3}}}}} {\hyperref[\detokenize{demo:cmdoption-Wno-shift-overflow3}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{\sphinxhyphen{}Wno\sphinxhyphen{}shift\sphinxhyphen{}overflow3}}}}} {\hyperref[\detokenize{demo:cmdoption-Wno-shift-overflow3}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{\sphinxhyphen{}Wno\sphinxhyphen{}shift\sphinxhyphen{}overflow3}}}}} {\hyperref[\detokenize{demo:cmdoption-Wno-shift-overflow3}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{\sphinxhyphen{}Wno\sphinxhyphen{}shift\sphinxhyphen{}overflow3}}}}} {\hyperref[\detokenize{demo:cmdoption-Wno-shift-overflow3}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{\sphinxhyphen{}Wno\sphinxhyphen{}shift\sphinxhyphen{}overflow3}}}}} {\hyperref[\detokenize{demo:cmdoption-Wno-shift-overflow3}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{\sphinxhyphen{}Wno\sphinxhyphen{}shift\sphinxhyphen{}overflow3}}}}} {\hyperref[\detokenize{demo:cmdoption-Wno-shift-overflow3}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{\sphinxhyphen{}Wno\sphinxhyphen{}shift\sphinxhyphen{}overflow3}}}}} {\hyperref[\detokenize{demo:cmdoption-Wno-shift-overflow3}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{\sphinxhyphen{}Wno\sphinxhyphen{}shift\sphinxhyphen{}overflow3}}}}} {\hyperref[\detokenize{demo:cmdoption-Wno-shift-overflow3}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{\sphinxhyphen{}Wno\sphinxhyphen{}shift\sphinxhyphen{}overflow3}}}}} {\hyperref[\detokenize{demo:cmdoption-Wno-shift-overflow3}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{\sphinxhyphen{}Wno\sphinxhyphen{}shift\sphinxhyphen{}overflow3}}}}} {\hyperref[\detokenize{demo:cmdoption-Wno-shift-overflow3}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{\sphinxhyphen{}Wno\sphinxhyphen{}shift\sphinxhyphen{}overflow3}}}}} {\hyperref[\detokenize{demo:cmdoption-Wno-shift-overflow3}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{\sphinxhyphen{}Wno\sphinxhyphen{}shift\sphinxhyphen{}overflow3}}}}}.

[jfbu]

Could you post the actual LaTeX mark-up as seen in the .tex file ? At my locale it involves:

Use these options: {\hyperref[\detokenize{demo:cmdoption-Wno-shift-overflow3}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{\sphinxhyphen{}Wno\sphinxhyphen{}shift\sphinxhyphen{}overflow3}}}}} {\hyperref[\detokenize{demo:cmdoption-Wno-shift-overflow3}]{\sphinxcrossref{\sphinxcode{\sphinxupquote{\sphinxhyphen{}Wno\sphinxhyphen{}shift\sphinxhyphen{}overflow3}}}}} etc...

Ok thanks for confirmation this is exactly same mark-up as I observed at my locale (i was in the dark for a while was asking for more details).

The root cause is the diverging behaviour of xelatex compared to pdflatex.

This appears as an after-effect of the fact it was configured to not apply TeX ligatures such as replacing -- by a long dash.

I am not sure how to proceed now, because, although possibly not good for options, breaking at - in literals was actually intended. But it did not happen with pdflatex... (in this case of inline literals, when the - is escaped by mark-up into \sphinxhyphen which is not the case for code-blocks or parsed-literals)

[marxin]

I am not sure how to proceed now, because, although possibly not good for options, breaking at - in literals was actually intended.

I see, makes sense. What about emitting something like \sphinx_never_break_hyphen within :option: directives that will never be broken?

[jfbu]

I see, makes sense. What about emitting something like \sphinx_never_break_hyphen within :option: directives that will never be broken?

:option: uses same latex mark-up as for inline literals. I will think about situation...

[marxin]

Btw. I've just tried the xelatex with the 'preamble': r'\def\sphinxhyphen{\mbox{-}}' and the result is not good for:

*Diagnostic Message Formatting Options*

  See :ref:`diagnostic-message-formatting-options`.

  :option:`-fmessage-length`:samp:`={n}`
  :option:`-fdiagnostics-plain-output`
  :option:`-fdiagnostics-show-location`:samp:`=[once|every-line]`
  :option:`-fdiagnostics-color`:samp:`=[auto|never|always]`
  :option:`-fdiagnostics-urls`:samp:`=[auto|never|always]`
  :option:`-fdiagnostics-format`:samp:`=[text|json]`
  :option:`-fno-diagnostics-show-option`  :option:`-fno-diagnostics-show-caret`
  :option:`-fno-diagnostics-show-labels`  :option:`-fno-diagnostics-show-line-numbers`
  :option:`-fno-diagnostics-show-cwe`
  :option:`-fdiagnostics-minimum-margin-width`:samp:`={width}`
  :option:`-fdiagnostics-parseable-fixits`  :option:`-fdiagnostics-generate-patch`
  :option:`-fdiagnostics-show-template-tree`  :option:`-fno-elide-type`
  :option:`-fdiagnostics-path-format`:samp:`=[none|separate-events|inline-events]`
  :option:`-fdiagnostics-show-path-depths`
  :option:`-fno-show-column`
  :option:`-fdiagnostics-column-unit`:samp:`=[display|byte]`
  :option:`-fdiagnostics-column-origin`:samp:`={origin}`
  :option:`-fdiagnostics-escape-format`:samp:`=[unicode|bytes]`

While pdflatex looks fine:

[jfbu]

From quick look this is simply due to xelatex font being wider. In both cases some lines are overfull with TeX going into the margin because it does not know how to break things. Also it spreads white space in the line to try to fill it which explains the layout of non-overfull lines.

Perhaps you can try to add this to latex_elements['preamble'] as well

\defaultfontfeatures[\ttfamily]{ Scale = 0.9 }

or some other factor.

But this will not fix the fact that TeX which is conceived to typeset natural language has no a priori knowledge of breaking overlong lines.

Or try to find another font, the default is doing

\setmonofont{FreeMono}[
  Extension      = .otf,
  UprightFont    = *,
  ItalicFont     = *Oblique,
  BoldFont       = *Bold,
  BoldItalicFont = *BoldOblique,
]

[jfbu]

But this will not fix the fact that TeX which is conceived to typeset natural language has no a priori knowledge of breaking overlong lines.

I mean overlong lines with symbols such as [, |, ] or non natural words like long option names when the linebreaks at - have been prohibited by some mechanism.

[jakobandersen]

I see, makes sense. What about emitting something like \sphinx_never_break_hyphen within :option: directives that will never be broken?

:option: uses same latex mark-up as for inline literals. I will think about situation...

I think it is fine to prevent line-breaking in literals. A similar change was recently made for HTML (#9929), so that would be consistent.

[marxin]

Looking more at the pdflatex output, even that is not ideal:

Please look at the 4th line from the bottom. So I do worry I'll have to place there some equivalent to @gol that we use in Texinfo right now:

...
@item Warning Options
@xref{Warning Options,,Options to Request or Suppress Warnings}.
@gccoptlist{-fsyntax-only  -fmax-errors=@var{n}  -Wpedantic @gol
-pedantic-errors @gol
-w  -Wextra  -Wall  -Wabi=@var{n} @gol
-Waddress  -Wno-address-of-packed-member  -Waggregate-return @gol
-Walloc-size-larger-than=@var{byte-size}  -Walloc-zero @gol
-Walloca  -Walloca-larger-than=@var{byte-size} @gol
-Wno-aggressive-loop-optimizations @gol
-Warith-conversion @gol
-Warray-bounds  -Warray-bounds=@var{n}  -Warray-compare @gol
-Wno-attributes  -Wattribute-alias=@var{n} -Wno-attribute-alias @gol
...

[jfbu]

I think it is fine to prevent line-breaking in literals. A similar change was recently made for HTML (#9929), so that would be consistent.

Thanks for tip, yes I will make PR. In retrospect line splitting was already prohibited in inline literals and parsed literals at dashes, with pdflatex, so I will base the PR on 4.3.x branch as a bugfix for xelatex (I hesitated as #9929 was merged into 4.x branch). Also because I made PRs on 4.3.x related to latex recently, but I hesitate still now which branch is better target.

[jfbu]

@marxin I guess having each :option:`optionname` in its own paragraph is not an option (sic) due to vertical spacing? you can not use a list for similar reason?

[jfbu]

.. |gol| raw:: latex

               \\


Use these options: :option:`-Wno-shift-overflow3`\ |gol| :option:`-Wno-shift-overflow3`\ |gol| :option:`-Wno-shift-overflow3`\ |gol| :option:`-Wno-shift-overflow3`\ |gol| :option:`-Wno-shift-overflow3`\ |gol| :option:`-Wno-shift-overflow3`\ |gol| :option:`-Wno-shift-overflow3`\ |gol| :option:`-Wno-shift-overflow3`\ |gol| :option:`-Wno-shift-overflow3`\ |gol| :option:`-Wno-shift-overflow3`\ |gol| :option:`-Wno-shift-overflow3`\ |gol| :option:`-Wno-shift-overflow3`\ |gol| :option:`-Wno-shift-overflow3`\ |gol| :option:`-Wno-shift-overflow3`.

[marxin]

@marxin I guess having each :option:`optionname in its own paragraph is not an option (sic) due to vertical spacing? you can not use a list for similar reason?

Exactly, that's too much of the vertical spacing.

[marxin]

.. |gol| raw:: latex

               \\


Use these options: :option:`-Wno-shift-overflow3`\ |gol| :option:`-Wno-shift-overflow3`\ |gol| :option:`-Wno-shift-overflow3`\ |gol| :option:`-Wno-shift-overflow3`\ |gol| :option:`-Wno-shift-overflow3`\ |gol| :option:`-Wno-shift-overflow3`\ |gol| :option:`-Wno-shift-overflow3`\ |gol| :option:`-Wno-shift-overflow3`\ |gol| :option:`-Wno-shift-overflow3`\ |gol| :option:`-Wno-shift-overflow3`\ |gol| :option:`-Wno-shift-overflow3`\ |gol| :option:`-Wno-shift-overflow3`\ |gol| :option:`-Wno-shift-overflow3`\ |gol| :option:`-Wno-shift-overflow3`.

Great, that works perfectly, I'm going to use it very likely (note one does not need the \ before |gol|).
Thanks for help!

[marxin]

Thanks for the fix. One more question: how difficult would it be to add a new directive:

..optionlisting:

  :option:`-fdiagnostics-plain-output`
  :option:`-fdiagnostics-show-location`:samp:`=[once|every-line]`
  :option:`-fdiagnostics-color`:samp:`=[auto|never|always]`

That would emit |gol| at the end of each line? Instead of manually placing the |gol| at the end of every line.
Thank you.

[jfbu]

Thanks for the fix. One more question: how difficult would it be to add a new directive:

please raise a new issue/feature request for discussion

[marxin]

please raise a new issue/feature request for discussion

Sure, done in #9995.