LaTeX: support for seealso directive should be via an environment to allow styling

[jfbu]

The LaTeX writer support for the "seealso" directive produces this kind of mark-up:

Text before


\sphinxstrong{See also:}


This is contents of seealso directive



Text after

from

Text before

.. seealso::

   This is contents of seealso directive

Text after

This makes impossible styling on the LaTeX side the way the contents are rendered (for example use some background color).

This is in contrast to most other elements of the LaTeX writer output, hence is a bug.

Admittedly our docs says

The content of the seealso directive should be a reST definition list. Example:

Still, a sphinxseealso environment would be useful to customize the included definition list. Besides there does not seem much rationale for restricting the contents of "seealso" directive to be definition lists only. Our doc says

For the HTML output, it is shown boxed off from the main flow of the text.

but without a LaTeX "sphinxseealso" environment, similar effect or even non similar is impossible for PDF output.

Environment info

• Sphinx version: 2.1.x and earlier

Additional context

• motivated from a discussion of the Sphinx user group

[tk0miya]

+1: Reasonable.

[n-peugnet]

@jfbu as you seem to be quite involved in the LaTeX rendering of Sphinx, is there a reason why you did not implement this change yet? It does not seem too difficult from the outside, but maybe it is more complicated than it looks?

[jfbu]

@n-peugnet Thanks for the ping. I had forgotten about this and perhaps there is a too long line of undone matters which I see when I check the latex (now builder:latex) label... and I am not always available. In truth I currently should not be available but as it seems I am procrastinating some important stuff I will look at this. A priori I concur there is no difficulty indeed.

[jfbu]

@n-peugnet done, thanks for reviving this forgotten issue.

[n-peugnet]

Thank you that was so fast!

One thing I noticed with your changes though, is that it seems the : is not passed to the \sphinxseealso macro, and it is up to the macro to add it (or not), whereas most of the similar macros are given the : at the end of the first argument. For instance all the admonitions (except the custom ones).

If I had to choose a preferred behaviour I would probably choose the former, but I think it would be a good thing to keep it similar to the admonition ones.

But considering the custom admonitions are already made this way it may not be so problematic.

Edit: One advantage of the second method is that the spacing between the text and the : can be adjusted depending on the language, as it is currently the case with the admonitions.
There is a space before the : in the French translation, but none in the English one.

Edit2: Sorry, it seems the French colon spacing is added in LaTeX by Babel

[jfbu]

Thank you that was so fast!

after 3 years and a few months delay, indeed.. and many major releases in-between...

One thing I noticed with your changes though, is that it seems the : is not passed to the \sphinxseealso macro, and it is up to the macro to add it (or not), whereas most of the similar macros are given the : at the end of the first argument. For instance all the admonitions (except the custom ones).

Yes. I always considered the automatic inclusion of a colon : at

sphinx/sphinx/writers/latex.py

Lines 1415 to 1419 in f4ab9ad

	def _visit_named_admonition(self, node: Element) -> None:
	label = admonitionlabels[node.tagname]
	self.body.append(CR + r'\begin{sphinxadmonition}{%s}{%s:}' %
	(node.tagname, label))
	self.no_latex_floats += 1

to be a legacy bug. Notice that this colon is not included in the gettext translatable strings

sphinx/sphinx/locale/__init__.py

Lines 244 to 255 in f4ab9ad

	admonitionlabels = {
	'attention': _('Attention'),
	'caution': _('Caution'),
	'danger': _('Danger'),
	'error': _('Error'),
	'hint': _('Hint'),
	'important': _('Important'),
	'note': _('Note'),
	'seealso': _('See also'),
	'tip': _('Tip'),
	'warning': _('Warning'),
	}

but hard-coded in the LaTeX mark-up as displayed above which is written by the Sphinx LaTeX writer.

Delimited macros allow a LaTeX user to remove the colon if needed from a macro argument, but such things are more routine to expert Plain TeX users than to LaTeX users. (the whole of LaTeX documentation never mentions them, and they become usable to LaTeX users only since a few years via syntax for defining user level commands from the xparse package now integrated into the recent LaTeX kernel additions ; as anyhow most LaTeX users are not even remotely acquainted with reading documentation more recent that the one from 30 years ago and don't really know basic things such as how TeX handles space tokens, one can not really expect them to feel at ease with removing an ending colon).

If I had to choose a preferred behaviour I would probably choose the former, but I think it would be a good thing to keep it similar to the admonition ones.

So far the seealso has not really been handled as an admonition by LaTeX and one reason for delay is perhaps that I hesitated where to put the (one-liner) code for it. I did put it in sphinxlatexadmonitions.sty in the end.

But considering the custom admonitions are already made this way it may not be so problematic.

Edit: One advantage of the second method is that the spacing between the text and the : can be adjusted depending on the language, as it is currently the case with the admonitions. There is a space before the : in the French translation, but none in the English one.

Edit2: Sorry, it seems the French colon spacing is added in LaTeX by Babel

Yes, the space in PDF output comes from the babel-french latex mechanism. It is not there in the latex files produced in the latex build directory. And if it were there the babel-french would "unskip" the induced space and insert its own custom spacing.

[jfbu]

One thing I noticed with your changes though, is that it seems the : is not passed to the \sphinxseealso macro, and it is up to the macro to add it (or not), whereas most of the similar macros are given the : at the end of the first argument. For instance all the admonitions (except the custom ones).

@n-peugnet Sorry I realize only today that your remark about placement of the colon in macro for seealso differs. And indeed you are right and I should have been more careful. The babel-french mechanism will not work because the colon : is not yet "active" in the sphinxlatexadmonitions.sty file, in contrast to a : encountered by LaTeX inside the document body. arrggghh. Ah well this was only merged in 6.1.0. May be it is not too dramatic if I change seealso to be more like the other admonitions. Although I do feel the added colon is annoying because it is hard to remove in LaTeX (precisely because of the fact that the : may be "normal" or "active").