Close #9985: LaTeX: Separate term and description of definition list by a new line

[tk0miya]

Feature or Bugfix

• Feature

Purpose

• refs: Latex: terms are not separated by a newline #9985

[jfbu]

Perhaps we will need some more subtle approach due to nesting case:

Listing:

:samp:`{file}.cc` :samp:`{file}.cp` :samp:`{file}.cxx` :samp:`{file}.cpp` :samp:`{file}.CPP` :samp:`{file}.c++` :samp:`{file}.C`
  C++ source code that must be preprocessed.  Note that in :samp:`.cxx`,
  the last two letters must both be literally :samp:`x`.  Likewise,
  :samp:`.C` refers to a literal capital C.

:samp:`{file}.mm` :samp:`{file}.M`
  case1:
    Objective-C++ source code that must be preprocessed.
  case2:
    Objective-C++ source code that must be preprocessed.


:samp:`{file}.mii`
  Objective-C++ source code that should not be preprocessed.

:samp:`{file}.hh` :samp:`{file}.H` :samp:`{file}.hp` :samp:`{file}.hxx` :samp:`{file}.hpp` :samp:`{file}.HPP` :samp:`{file}.h++` :samp:`{file}.tcc`
  C++ header file to be turned into a precompiled header or Ada spec

produces extra whitespace with this PR:

Compare to current situation:

What do you think @tk0miya, is it needed to think about some other approach to avoid above whitespace? Right now I can think of some approach needing some LaTeX macros but I have not worked out the details.

[jfbu]

@tk0miya @marxin I remember now numpy achieves this generally speaking for description lists using some rather old buggy latex package and some extra patch https://github.com/numpy/numpy/blob/0302205105161c6bbae5d45fe4e7a5a624f0dbf4/doc/source/conf.py#L239-L263

I thus tested their hack

latex_elements = {
    'preamble': r'''
% In the parameters section, place a newline after the Parameters
% header
\usepackage{expdlist}
\let\latexdescription=\description
\def\description{\latexdescription{}{} \breaklabel}
% but expdlist old LaTeX package requires fixes:
% 1) remove extra space
\usepackage{etoolbox}
\makeatletter
\patchcmd\@item{{\@breaklabel} }{{\@breaklabel}}{}{}
\makeatother
% 2) fix bug in expdlist's way of breaking the line after long item label
\makeatletter
\def\breaklabel{%
    \def\@breaklabel{%
        \leavevmode\par
        % now a hack because Sphinx inserts \leavevmode after term node
        \def\leavevmode{\def\leavevmode{\unhbox\voidb@x}}%
    }%
}
\makeatother
''',
}

and it gives this

where I find there is too much whitespace between terms and definitions. I wonder by the way if this was already the case two or three years ago, or if something changed.

whatever we do we must perhaps be careful not to break important projects such as https://github.comnumpy/numpy or at least tell them about needed adjustments. Because it seems #9985 is about making default behaviour such as in numpy pdf docs.

[jfbu]

If I combine this with the current status of numpy doc which patches LaTeX it creates build failure:

! LaTeX Error: There's no line here to end.

See the LaTeX manual or LaTeX Companion for explanation.
Type  H <return>  for immediate help.
 ...                                              
                                                  
l.110 \sphinxAtStartPar
                       
? 

(using the test as in #9988 (comment), or even as in original #9985 example without nesting)

[jfbu]

where I find there is too much whitespace between terms and definitions. I wonder by the way if this was already the case two or three years ago, or if something changed.

only to mention that checking a 2019 build from source I had on my disk of numpy-ref.pdf the generous vertical whitespace between (general) term in a description list and description of term was already there

I feel if we do upstream at Sphinx something with same effect it should give less whitespace.

memo: any change in this area may be breaking to numpy or projects having copied its LaTeX hack and will require proper announce or test.

[tk0miya]

I think adopting numpy's way is better to us. It's simple and consistent to fix the behavior of description environment from LaTeX side.

We can put a CR code just before a paragraph to avoid extra whitespace before nested list. But I worry about it makes LaTeX code inconsistent, and it will prevent to fix other problems in the future.

BTW, indeed, this would be a breaking change. So it would be better to merge into the master branch (v5.0).

[jfbu]

I think adopting numpy's way is better to us. It's simple and consistent to fix the behavior of description environment from LaTeX side.

1. we can share the numpy design but should avoid to copy over their hack: it is based on an out-dated LaTeX package and patches some internal LaTeX macros, it is not good approach (saying that although I tried to contribute to their project by editing this hack myself). Also, I feel the vertical whitespace it triggers is excessive (as is vertical spacing generally speaking in LaTeX regarding lists with very hard to control by user situation)
2. for object descriptions, Sphinx LaTeX macros \pysigline/\pysiglinewithargsret implement a better mechanism than numpy hack by simply letting the label occupy all available whitespace on line, so next contents is pushed below. Unfortunately the code in sphinxlatexobjects.sty is complicated by the task supporting multi-line signatures. A simpler version will be enough for us here (I have not thought through the details yet).
3. In my view, in some cases description lists as in LaTeX's defaut which applies no CR between label and item contents is sometimes better visually, (if both are short), but perhaps it is needed to ensure latex and html look the same indeed. So I am OK implementing this design change but it is breaking both regarding the output, and, quite probably, breaking to projects using hacks such as numpy does.

MEMO: the \leavevmode in the produced tex file comes from 1bd5ec7. It ensures a CR (with the excessive in my view vertical spacing typical of LaTeX lists that I mentioned above) if the item contents are themselves a sub-list. What we want to is ensure a CR in all cases.

An alternative to imitating \pysigline LaTeX tricks with \item could be to exploit \sphinxAtStartPar and redefine it in such description list context for the first instance encountered immediately after afer the item label: if we move to it responsability of adding the \\ from your patch, then the \\ will get inserted only this paragraph case, not in the sublist case.

[tk0miya]

In my view, in some cases description lists as in LaTeX's defaut which applies no CR between label and item contents is sometimes better visually, (if both are short), but perhaps it is needed to ensure latex and html look the same indeed.

I think the best style is different for each medium. So it's okay that description lists are represented in different styles between LaTeX and HTML.

I did not collect statistics about preferred styles from people. But I guess many people would be familiar with the HTML style (because HTML browsers are always around in our life). TBH, I also prefer the HTML one. So I think it's better to change the style of the description lists. It would be much better if we can switch the style easily :-)

[jfbu]

So I think it's better to change the style of the description lists. It would be much better if we can switch the style easily :-)

Good suggestion! I need to do some work on this to check all instances for description lists. I find in writers/latex.py visit_definition_list(), visit_field_list() which each employ directly a LaTeX description environment, and there is visit_desc() which uses fulllineitems itself a Sphinx latex custom kind of description environment, which achieved already in its way a "full line item" behaviour like #9985 asks for terms.

With #9999, the behaviour of definition lists will be much similar to the fulllineitems used for object descriptions, but the LaTeX macros are very different. In future it would be worthwhile perhaps to unify and this could be opportunity add some toggle for customization; the \sphinxlineitem of #9999 handling definition lists does not have hooks for customizing it.

In the case of multi-line terms (as is possibly in glossaries and now better supported for LaTeX by #9999, and as is possible in object signatures), the task of not inserting a CR between a multi-line "label" and the item "contents" will need some modifications of LaTeX macros of #9999 or of current fulllineitems.