LaTeX: make contents, topic, and sidebar separately customizable #12704

jfbu · 2024-07-28T18:52:36Z

And give them some nice defaults to start with.

Subject:

Feature or Bugfix

Feature

Purpose

So far, and since dawn of time the contents, topic, and sidebar directives have been styled the same way (except perhaps for their titles which had separate customizing LaTeX macros associated with them) simply because they were mapped to the same LaTeX environment (which very long time ago was incompatible with pagebreaks).

The aim of this PR is to separate them, and also to give them nice defaults immediately.

Detail

Here is how it looked at 6.1.0 (contents, then sidebar, and finally topic)

Here is how it looked at 7.4.0:

Here is how it wil look with this PR merged:

And give them some nice defaults to start with.

AA-Turner · 2024-07-31T07:30:20Z

I'm not qualified to review this -- @jfbu please merge when you're happy!

A

jfbu · 2024-07-31T08:27:48Z

@AA-Turner Do you think this can be part of a 8.0.d release or should wait 8.1.0? i.e. If merging now, should I create a 8.0.3 entry with a Feature added sub-section?

AA-Turner · 2024-07-31T08:30:32Z

This will go into 8.1 -- 0.0.X releases are bug-fix only for problems in feature releases. There's no reason we can't do Sphinx 8.1 fairly soon though, perhaps end of August or early September.

A

jfbu · 2024-07-31T08:35:23Z

Yes, understood. Thanks.

jfbu · 2024-07-31T09:21:14Z

I have prepared the CHANGES entry for 8.1.0. (in a prior comment I had not yet seen that there was a 8.1.0 section ready after recent refactoring of CHANGES.rst).

picnixz · 2024-08-05T05:47:00Z

I'm interested in reviewing it but only next week (those changes are too hard to review on a phone). Could you wait until then please?

jfbu · 2024-08-05T07:01:57Z

@picnixz Thanks! I will thus officially request your review 😃 but don't feel time-pressured I was targeting perhaps September or October or whenever we do a release with new features. One aspect is that contrarily to two years ago at 5.1.0 when we added much customizability to admonitions, topics/contents (still then handled via idenical rendering, due to legacy situation which this PR lifts) and code-blocks (#10648), this time for this last piece (which is relatively minor addition which uses existing code-base to separate topics/contents/sidebar into three independent entities), the new defaults do exploit the new capacities. I think PDF output from Sphinx should come "batteries-included" else big projects which concentrates most of their efforts on how HTML/ePub look like and lack LaTeX-self-confident workforce will never use what we offer for PDF output.

jfbu · 2024-08-08T19:56:53Z

I updated the sidebar top width which on further thoughs looked too thin in comparison of bottom width in particular which has a shadow. New looks:

picnixz

Could we have some tests? just to check that the arguments are correctly forwarded? it's sometimes hard to spot a typo in LaTeX, especially when the IDE support is not good.

CHANGES.rst

picnixz · 2024-08-12T08:13:18Z

doc/latex.rst


-    Default: ``5pt``
+   At 8.1.0 it became possible to style separately the :dudir:`topic`,


Suggested change

At 8.1.0 it became possible to style separately the :dudir:`topic`,

Since Sphinx 8.1.0, it is now possible to style separately the :dudir:`topic`,

Don't want to nit-pick, not native speaker but once I adopt Since shouldn't I drop the now?

Err.. yes, it sounds better (I'm also not an English native).

picnixz · 2024-08-12T08:13:39Z

doc/latex.rst


-    See :ref:`additionalcss` for ``div.topic_box-shadow`` which allows to
-    configure separately the widths of the vertical and horizontal shadows.
+    .. versionchanged:: 8.1.0 New separate defaults. See :ref:`additionalcss`.


I don't know whether it should be a versionchanged or a deprecated since they are kept for backward compatibility.

Also, I would separate 8.1.0 from "New":

.. versionchanged:: 8.1.0 New...

Same obversation for the other .. version* directives that you added.

I don't know whether it should be a versionchanged or a deprecated since they are kept for backward compatibility.

I will check that.

Also, I would separate 8.1.0 from "New":

.. versionchanged:: 8.1.0 New...

Formerly I think I used

.. versionchanged:: X.y.z description

and one can see many examples in doc/latex.rst. Now I am very confused about how this directive is supposed to be used.

Same obversation for the other .. version* directives that you added.

All those versionchanged removed in next push, and a clearer explanation in "important" box before.

picnixz · 2024-08-12T08:21:43Z

doc/latex.rst

-  margin.
+  *except* for:
+
+  - the contents_ directive: ``4pt 4pt``, i.e. the shadow has a width of


This might seem an overkill, but would it be possible to create a picture that displays the mdiffernt metrics, a bit like https://mirror.init7.net/ctan/macros/latex/contrib/geometry/geometry.pdf (page 3)? I think a picture would be easier to understand than a descriptive text. This can be done in a separate PR since you did not change the actual description (just put it in a bullet list).

arrgghh... I am starting to think we should have used longfbox whose doc already has nice pictures (sadly the package is broken for years because it was developed at a time pict2e defined a \@tempdimd but later dropped it) 😃. Well, doesn't CSS documentation sites for HTML fit the bill already? The behavior of box-shadow is directly emulating it, with a more restricted syntax, but the way "inset" keyword or negative dimensions impact result should be exactly as in CSS. At least this is what I remember from when this was done.

doc/latex.rst

picnixz · 2024-08-12T08:24:16Z

doc/latex.rst

+     ``\sphinxstylenotetitle``; ``\sphinxdotitlerow{note}{#1}``
+     ``\sphinxstylehinttitle``; ``\sphinxdotitlerow{hint}{#1}``


Could you align the column? (namely align ``\sphinxdotitlerow with ``{\footnotesize from above)

Done in next push.

doc/latex.rst

sphinx/texinputs/sphinx.sty

picnixz · 2024-08-12T08:45:38Z

sphinx/texinputs/sphinxlatexshadowbox.sty

@@ -113,4 +148,31 @@
   \spewnotes
  }

+% 8.1.0
+\newenvironment{sphinxtopic}
+               {\begin{sphinxShadowBox}\relax}{\end{sphinxShadowBox}}


Do you really need the \relax? if not, maybe it's better to explicitly use [topic] even though it's the default.

The environment now admis an optional argument. I put the \relax to be extra sure some [ will not fool it. However you are right it can not happen for topic directive as it requires a title so Sphinx will always output stuff like this

\begin{sphinxtopic} \sphinxstyletopictitle{A}

and there can't be a problem.

Yes using [topic] explictly is clearer for people reading this .sty file but it is probably slightly less efficient, now that doesn't matter. If people want to use directly the environment they have to be cautious though with the [ trap, so adding the [topic] here would help them avoid mistakes.

+0 for using [topic] will wait my 12 hours of usual sleep for a decision 😃

After some closer look, and for reasons already mentioned, the \relax is not needed indeed. Besides Sphinx escapes [ to {[} to avoid potential problems (mainly in lists). Then I hesitated with using the explicit [topic] or nothing at all, and opted for nothing at all, in the end. No strong opinion.

I personally prefer the explicit topic because the default was only kept for backwards compatibility. In the future, we might at some point remove it or change it for whatever reasons. How do you feel about this?

ok, agreed. I have pushed with [topic] added.

@picnixz For the record there is a subtle point with LaTeX environments. With \newenvironment{test}{}{} and

a% \begin{test} b% \end{test}c

you will find a bc in output, because the EOL of \begin{test}\n gives a space token which is not ignored as we are mid-paragraph. If now the test environment is defined via \newenvironment{test}[1][topic]{}{} the output will be abc. This is because the environment searches for [ and swallows spaces doing so.

Our sphinxtopic, sphinxcontents, sphinxsidebar all inject the [ and the EOL space is not swallowed. This does not matter because the paragraph is not started, so TeX ignores this space, but it sees it.

Oh thank you for this! One thing I always found extremely tricky in LaTeX (and TeX) is about those space tokens and how they are dealt with... So it helps a lot when you explain it!

About my example, LaTeX provides \ignorespacesafterend which you can use when defining the end part of an environment but no \ignorespacesatbegin which user could put in the begin part.

About what you say about spaces I fully agree. There is a blatant lack of a serious document "TeX/LaTeX spaces explained". With the promotion of LaTeX3 with whom programmers do not have to worry at all anymore about spaces in their source code (they get ignored by default), I am sure situation will degrade because the folks doing LaTeX "programming" have less incentives to care about spaces...

sphinx/texinputs/sphinxlatexshadowbox.sty

picnixz · 2024-08-12T09:05:23Z

I forgot commenting about the design itself.

Contents: shadows are a bit too large IMO. I would halve them.
Sidebar: I personally don't like the new look and would I preferred the original look by default. The issue is that I cannot tell whether it's a shadow or a border... and it seems they are being mixed.

I have other PRs to do so I won't be able to add some visual examples now but I'll try to do it this week.

jfbu · 2024-08-18T19:57:35Z

@picnixz
Here is contents with 2pt, 3pt or 4pt shadow. 4pt is the legacy setting, and the rounded corner is since 7.4.0.

I am not enthused by 2pt, neutral about 3pt, and more in favor of 4pt. The design is not one one sees on every page, it is only for contents directive hence usually will be encountered if at all at start of chapters.

EDIT: Forgot to say that I used

.. contents::
   :local:

which has the side effect to suppress the title (if none is explicitly given) from the Docutils node. For the rendering with title bar see previous screenshots in this thread.

picnixz · 2024-08-19T07:43:05Z

The design is not one one sees on every page

Ok you convinced me with this one. I think 4pt is ok. Sorry for forgetting about this by the way... and thank you as always for your precise reports... I'll review the latest changes now.

picnixz

Final formulation nitpicks.

sphinx/texinputs/sphinx.sty

doc/latex.rst

Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>

jfbu · 2024-08-19T14:47:34Z

Thanks a lot for your help @picnixz. I have some tasks now so will make a final check in a few hours, expecting to merge this around 9PM European summer time.

picnixz · 2024-08-19T15:13:36Z

I won't be online at that time but AFAICT, nothing else stands out. And if there are typos we need to fix, then we'll fix them in a follow-up PR.

jfbu · 2024-08-19T18:44:29Z

Merged! Thanks again for you helping hand!

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

jfbu added this to the 8.x milestone Jul 28, 2024

LaTeX: make contents, topic, and sidebar separately customizable

e903f38

And give them some nice defaults to start with.

jfbu force-pushed the latex_contents_vs_topic_vs_sidebar branch from 768c32c to e903f38 Compare July 28, 2024 19:01

jfbu added 2 commits July 29, 2024 10:17

Let titlerow macro auto-detect if using or not icon

d6c0614

Docs

0f1d446

jfbu force-pushed the latex_contents_vs_topic_vs_sidebar branch from b6a5506 to 0f1d446 Compare July 29, 2024 08:24

jfbu added 3 commits July 29, 2024 10:49

Mark-up glitch in docs

bf34ac6

LaTeX docs missing updates

07adb47

LaTeX docs again, mainly pre-existing typos

e5e3866

Merge branch 'master' into latex_contents_vs_topic_vs_sidebar

0ed2afa

jfbu added 2 commits July 31, 2024 11:07

Update LaTeX code comments

019d31c

Update CHANGES for PR sphinx-doc#12704

617b80c

Again LaTeX code comments

ed08c49

jfbu requested a review from picnixz August 5, 2024 07:02

jfbu added 3 commits August 8, 2024 21:47

Merge branch 'master' into latex_contents_vs_topic_vs_sidebar

22ab8d1

Use 2pt for sidebar top border width to better match the bottom 1pt+2pt

8ee7838

Update docs

fcb2607

Merge branch 'master' into latex_contents_vs_topic_vs_sidebar

e01347a

picnixz reviewed Aug 12, 2024

View reviewed changes

jfbu added 5 commits August 13, 2024 10:22

Fix sphinx-doc#12778

5eff50e

Update CHANGES.rst with sphinx-doc#12778 fix

4de5e37

Use [topic] explicitly for sphinxtopic wrapper of sphinxShadowBox

c0054d2

Use \newcommand* for \sphinxstyletopictitle and friends

7f633d8

Add test

cb795d6

jfbu force-pushed the latex_contents_vs_topic_vs_sidebar branch from 6e6ec19 to cb795d6 Compare August 13, 2024 09:24

jfbu added 3 commits August 13, 2024 11:41

Dear Ruff your style is not my taste!

67fff70

Ruff: calm down now!

97a4323

Merge branch 'master' into latex_contents_vs_topic_vs_sidebar

ed06f03

picnixz self-requested a review August 19, 2024 07:43

picnixz approved these changes Aug 19, 2024

View reviewed changes

jfbu and others added 6 commits August 19, 2024 16:15

Update doc/latex.rst (suggestion 1)

6626dfe

Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>

Apply suggestions from code review

75ae998

Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>

Line wrap after 8.1.0 (and one 7.4.0) in multiple versionchanged

842a770

A full stop

b46ef6e

Better wording for horizontal shadows extending into margin

1b920aa

Use indents of 2 spaces not 4 at some locations in LaTeX code

fc148fd

jfbu added 2 commits August 19, 2024 20:29

Update CHANGES.rst

3df4ce0

One more versionchanged linewrap in doc/latex.rst

279d761

jfbu merged commit 1c131df into sphinx-doc:master Aug 19, 2024
22 checks passed

jfbu deleted the latex_contents_vs_topic_vs_sidebar branch August 19, 2024 18:45

jfbu mentioned this pull request Aug 19, 2024

LaTeX: contrarily to doc, div.topic_box-shadow if used with a single dimension only sets the x-offset, and y-offset remains nil #12778

Closed

github-actions bot locked as resolved and limited conversation to collaborators Sep 20, 2024

AA-Turner modified the milestones: 8.x, 8.1.0 Oct 6, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

LaTeX: make contents, topic, and sidebar separately customizable #12704

LaTeX: make contents, topic, and sidebar separately customizable #12704

jfbu commented Jul 28, 2024 •

edited

Loading

AA-Turner commented Jul 31, 2024

jfbu commented Jul 31, 2024

AA-Turner commented Jul 31, 2024

jfbu commented Jul 31, 2024

jfbu commented Jul 31, 2024 •

edited

Loading

picnixz commented Aug 5, 2024

jfbu commented Aug 5, 2024

jfbu commented Aug 8, 2024

picnixz left a comment

picnixz Aug 12, 2024

jfbu Aug 12, 2024

picnixz Aug 12, 2024

picnixz Aug 12, 2024

jfbu Aug 12, 2024

jfbu Aug 13, 2024

picnixz Aug 12, 2024

jfbu Aug 12, 2024

picnixz Aug 12, 2024

jfbu Aug 13, 2024

picnixz Aug 12, 2024

jfbu Aug 12, 2024

jfbu Aug 13, 2024

picnixz Aug 13, 2024

jfbu Aug 13, 2024

jfbu Aug 13, 2024 •

edited

Loading

picnixz Aug 13, 2024

jfbu Aug 13, 2024

picnixz commented Aug 12, 2024

jfbu commented Aug 18, 2024 •

edited

Loading

picnixz commented Aug 19, 2024

picnixz left a comment

jfbu commented Aug 19, 2024

picnixz commented Aug 19, 2024

jfbu commented Aug 19, 2024


		Default: ``5pt``
		At 8.1.0 it became possible to style separately the :dudir:`topic`,

	At 8.1.0 it became possible to style separately the :dudir:`topic`,
	Since Sphinx 8.1.0, it is now possible to style separately the :dudir:`topic`,

		``\sphinxstylenotetitle``; ``\sphinxdotitlerow{note}{#1}``
		``\sphinxstylehinttitle``; ``\sphinxdotitlerow{hint}{#1}``

LaTeX: make contents, topic, and sidebar separately customizable #12704

LaTeX: make contents, topic, and sidebar separately customizable #12704

Conversation

jfbu commented Jul 28, 2024 • edited Loading

Feature or Bugfix

Purpose

Detail

AA-Turner commented Jul 31, 2024

jfbu commented Jul 31, 2024

AA-Turner commented Jul 31, 2024

jfbu commented Jul 31, 2024

jfbu commented Jul 31, 2024 • edited Loading

picnixz commented Aug 5, 2024

jfbu commented Aug 5, 2024

jfbu commented Aug 8, 2024

picnixz left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jfbu Aug 13, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

picnixz commented Aug 12, 2024

jfbu commented Aug 18, 2024 • edited Loading

picnixz commented Aug 19, 2024

picnixz left a comment

Choose a reason for hiding this comment

jfbu commented Aug 19, 2024

picnixz commented Aug 19, 2024

jfbu commented Aug 19, 2024

jfbu commented Jul 28, 2024 •

edited

Loading

jfbu commented Jul 31, 2024 •

edited

Loading

jfbu Aug 13, 2024 •

edited

Loading

jfbu commented Aug 18, 2024 •

edited

Loading