Skip to content

LaTeX: Add math_numsep support to latex builder - #12652

Merged
jfbu merged 15 commits into
sphinx-doc:masterfrom
thfanning:math_numsep
Aug 18, 2024
Merged

LaTeX: Add math_numsep support to latex builder#12652
jfbu merged 15 commits into
sphinx-doc:masterfrom
thfanning:math_numsep

Conversation

@thfanning

Copy link
Copy Markdown
Contributor

Subject: math_numsep support in LaTeX builder

Feature or Bugfix

  • Feature

Purpose

  • Add math_numsep support to latex builder.

Detail

  • math_numsep defines the text separator to use between section numbers and equation numbers.
  • This works for HTML, but is not easy for users to integrate into LaTeX.
  • When not using Sphinx, an author might use a solution like \renewcommand{\theequation}{\thesection-\arabic{equation}}, but this is not viable due to the complexity in Sphinx's numbering.
  • Sphinx number definitions are in ./sphinx/texinputs/sphinxlatexnumfig.sty
  • This patch exports the configuration option to the latex numbering definition for parity with HTML.

Relates

@jfbu jfbu added type:enhancement enhance or introduce a new feature builder:latex labels Jul 22, 2024

@jfbu jfbu left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I checked separate chunks now I need to revisit the whole LaTeX file to make sure this does not break some at-this-time not seen constraints.

Comment thread sphinx/texinputs/sphinx.sty Outdated
Comment thread sphinx/texinputs/sphinxlatexnumfig.sty Outdated
Comment thread sphinx/texinputs/sphinxlatexnumfig.sty Outdated
Comment thread sphinx/writers/latex.py Outdated
Comment thread tests/test_builders/test_build_latex.py Outdated

@jfbu jfbu left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM with nits.

With

latex_theme = 'howto'
# latex_toplevel_sectioning = 'part'

numfig = True
math_numfig = True
numfig_secnum_depth = 1
math_numsep = "-"

there is a problem in the output with prefixed dots. This problem goes away if the suggested change above is merged. But even with the suggested change, then if we uncomment the latex_toplevel_sectioning line a new problem arises that the separator is used but there is nothing before it.

(I had a bit forgotten the numfig and numfig_secnum_depth things which are bit complex in sphinx.writers.latex.)

I see how to address the issue I raised via somewhat scary hack to get rid of an extra prefixed dot. (We would then use it also for chapter) Maybe you will come out with simpler way to address raised difficulty which would be better for long term maintenance.

Comment thread sphinx/writers/latex.py Outdated
@AA-Turner AA-Turner added this to the 8.x milestone Jul 23, 2024
@jfbu

jfbu commented Jul 23, 2024

Copy link
Copy Markdown
Contributor

LGTM with nits.

I have pushed some own code which fixes the issues I had. Ideally some test should be modified so what we can check that for example using math_numsep = "-" is obeyed via the mathnumsep=- in LaTeX. Actually it would be safer if mathnumsep={%s} syntax (here the {..} are real braces to end in LaTeX) was used --- for example if separator is set to a comma. I will push an additional commit and will check in passing if test can be updated as I requested.

edit: both done in later commit.

@jfbu

jfbu commented Jul 23, 2024

Copy link
Copy Markdown
Contributor

Ready to go. I don't think it is worthwile to add a versionchanged in doc/usage/configuration.rst only to say LaTeX support was added at 8.0 as the 7.4.x series is so recent?

(but maybe some CHANGES update when it gets merged after 8.0.0)

Edit: On further thoughts I will add a latex doc as it seems necessary to explain what to do if string for html is not suitable for latex.

@jfbu

jfbu commented Jul 31, 2024

Copy link
Copy Markdown
Contributor

@thfanning I have merged master, removed the disabling in preamble, and prepared CHANGES.rst for 8.1.0 release. Are you ok with current state of this PR? We could add a .. versionchanged:: 8.1.0 entry to doc/usage/configuration.rst to say it applies to latex builder as well but other entries in Options for Maths say nothing specific, so maybe it is actually better not to worry.

@AA-Turner AA-Turner changed the title [latex] Add math_numsep support to latex builder. LaTeX: Add math_numsep support to latex builder. Aug 11, 2024
@AA-Turner AA-Turner changed the title LaTeX: Add math_numsep support to latex builder. LaTeX: Add math_numsep support to latex builder Aug 11, 2024
@jfbu

jfbu commented Aug 18, 2024

Copy link
Copy Markdown
Contributor

Thanks for contribution!

@jfbu
jfbu merged commit e0f2009 into sphinx-doc:master Aug 18, 2024
@github-actions github-actions Bot locked as resolved and limited conversation to collaborators Sep 20, 2024
@AA-Turner AA-Turner removed this from the 8.x milestone Oct 6, 2024
@AA-Turner AA-Turner added this to the 8.1.0 milestone Oct 6, 2024
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

builder:latex type:enhancement enhance or introduce a new feature

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants