Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

LaTeX: separate terms from their definitions by a CR (close #9985) #9999

Merged
merged 3 commits into from Dec 23, 2021

Conversation

jfbu
Copy link
Contributor

@jfbu jfbu commented Dec 20, 2021

Close #9985

Also, in passing, this adds better rendering of glossary terms with a common definition (less vertical whitespace):
Fix #10000

Hence both Bugfix (too much whitespace between glossary terms sharing common definitionà) and New feature (separate terms from defintions by a CR in pdf output).

As far as I tested briefly, this does not cause breakage if used with numpy's hack into LaTeX description lists, but the hack of their project should be removed entirely, as it causes bad extraneous vertical whitespace.

Related #9988

@jfbu jfbu added this to the 5.0.0 milestone Dec 20, 2021
@jfbu
Copy link
Contributor Author

jfbu commented Dec 20, 2021

I used this test:

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

test
  hello
    again

  hello
    again


indented

  more test
    hello
      again

    hello [1]_
      again

    hello
      again

      :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.

See :term:`boson` and :term:`über` and :term:`myon`.

.. comment :term:`ähnlich`.

.. [1] coucou

test-glossary
=============

.. glossary::
   :sorted:

   boson
      Particle with integer spin.

   *fermion*
      Particle with half-integer spin.

   tauon
   myon
   electron
      Examples for fermions.

   über
      Gewisse

   .. änhlich
       Dinge

and obtain this output in pdf:

Capture d’écran 2021-12-20 à 18 59 37

Capture d’écran 2021-12-20 à 19 00 11

The current PR has a potential limitation if a term has a footnote. But in fact, adding a footnote to a term in a glossary causes a problem, the term is not indexed properly. Anyway, the alternative approach is currently available at https://github.com/jfbu/sphinx/tree/9985_latex_on_master_v2 (test files not updated). It is cleaner approach perhaps, with less LaTeX macro definitions, and more mark-up output from Sphinx latex writer.

@jfbu jfbu requested a review from tk0miya December 20, 2021 18:33
@jfbu jfbu changed the title LaTeX: separate terms from their definitions by a CR (fix #9985) LaTeX: separate terms from their definitions by a CR (close #9985) Dec 20, 2021
@jfbu jfbu added type:bug type:enhancement enhance or introduce a new feature labels Dec 20, 2021
@jfbu
Copy link
Contributor Author

jfbu commented Dec 20, 2021

Probably the fulllineitems environment with \pysigline for object signatures and description should be refactored to use similar parbox dimensions as here. The approach of https://github.com/jfbu/sphinx/tree/9985_latex_on_master_v2 shows how perhaps a refactoring of support for multi-line signatures should be done, in a somewhat cleaner way than current approach in sphinxlatexobjects.sty which has too complicated TeX macros.

But I am delaying that to perhaps another PR which could replace this one with the https://github.com/jfbu/sphinx/tree/9985_latex_on_master_v2 approach and at the same time unify with handling of object descriptions.

@tk0miya
Copy link
Member

tk0miya commented Dec 22, 2021

Thank you for your work, as always :-)
LGTM!

@jfbu
Copy link
Contributor Author

jfbu commented Dec 22, 2021

mypy test fails after merging master branch into this one, but this regards files unrelated to this PR: https://github.com/sphinx-doc/sphinx/runs/4610549456?check_suite_focus=true

@tk0miya
Copy link
Member

tk0miya commented Dec 23, 2021

I fixed the warnings from mypy on the HEAD of master branch now. So please merge it to your branch.

@jfbu
Copy link
Contributor Author

jfbu commented Dec 23, 2021

@tk0miya tests pass after merging master, now merging into master, thanks

@jfbu jfbu merged commit 468384f into sphinx-doc:master Dec 23, 2021
@jfbu jfbu deleted the 9985_latex_on_master branch December 23, 2021 17:57
jfbu added a commit to jfbu/sphinx that referenced this pull request Dec 23, 2021
@github-actions github-actions bot locked as resolved and limited conversation to collaborators Jan 23, 2022
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
builder:latex type:bug type:enhancement enhance or introduce a new feature
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

2 participants