LaTeX: image using width set at 10% in nested lists or nested quoted paragraphs gets smaller and smaller

[jfbu]

Describe the bug

When using :width: 10% the effective dimension decreases in quoted paragraphes or list items. The result is counter-intuitive, because the text font size keep being the same only the effective text width diminishes. But surely 10% should refer either to page width or to text area width.

How to Reproduce

===================
 FOO documentation
===================


image in quoted paragraphs using width at 10%
=============================================

|sphinx|

 |sphinx|

  |sphinx|

   |sphinx|

    |sphinx|

     |sphinx|

      |sphinx|


image in nested lists using width at 10%
========================================

1. |sphinx|

   1. |sphinx|

      1. |sphinx|

         1. |sphinx|

            we stop here, else needed to use ``'maxlistdepth'`` of
            ``latex_elements`` to avoid LaTeX error about too many
            levels of nesting.

.. |sphinx| image:: img.png
            :width: 10%

Environment Information

Platform:              darwin;
Python version:        3.13.3 (v3.13.3:6280bb54784, Apr  8 2025, 10:47:54) [Clang 15.0.0 (clang-1500.3.9.4)])
Python implementation: CPython
Sphinx version:        8.3.0+/e1bd9cb38
Docutils version:      0.21.2
Jinja2 version:        3.1.6
Pygments version:      2.19.1

Sphinx extensions

Additional context

As per #13661, the cause is that Sphinx translates 10% into 0.100\linewidth.

[gmilde]

The specification is a bit vague:

Percentage values are relative to other values, depending on the context in which they occur.

The behaviour is currently the same in HTML and LaTeX: a width value of 10% sets the element width to 10% of the parent element.

While the current behaviour may appear odd in the specific examples above, it works fine in use cases that set the width of an image or table to 100%:

Percentage values in quotes and lists
=====================================

.. image:: img.png
   :width: 100%
   :height: 1em

In Docutils, 100% wide images in text body, quote, and list 
match the width of the respective text block. 
This means that their size depends on the context they appear in.
This behaviour is not universally expected:

   .. image:: img.png
      :width: 100%
      :height: 1em

   I do not think it make sense in LaTeX that image sizes would
   mysteriously shrink while text font size is not modified.
   The HTML/CSS paradigm should not be followed too closely.

Problems with using ``\textwidth`` instead of ``\linewidth``:

* An image in a quote, list, table or similar using 100% of
  the document-wide ``\textwidth`` dimension will overflow.
  
  .. image:: img.png
     :width: 100%
     :height: 1em

* Smaller ratios will work but deviate from the result in HTML.
  Behaviour differences between HTML and LaTeX violate the 
  “Law of Least Astonishment”: 
       
      .. image:: img.png
         :width: 100%
         :height: 1em
   
      In short, this law states that every construct in the system should
      behave exactly as its syntax suggests. Widely accepted conventions
      should be followed whenever possible, and exceptions to previously
      established rules of the language should be minimal.

[jfbu]

Thanks @gmilde for comment. I will probably not push to deviate from \linewidth and this may get closed without (effective) change. Leaving open in case further opinions are expressed. I will postpone the milestone of #13661. The complexities of tabulary make me suspect I can find other counter-intuitive results. Tabulary tries to decide on the fly what the suitable "width" of the cell is, and it is a bit obscure how in the #13661 example with only one cell the image width ends up at about 10pt, i.e. the actual cell width is set to be at about 100pt.

[gmilde]

Can we agree that this is not a bug?

In this case I propose to either close the issue or change the type from "bug" to feature-request or similar.

[jfbu]

@gmilde I strongly believe this is definitely a "bug" in the sense that the when the code was first written it is 99% certain their author did not think about what \linewidth really means in LaTeX. When you visit a PDF on your computer, the PDF viewer will not automagically rescale the viewport to zoom in when you scroll down a list so that the percentage of \linewidth would keep some reasonable intuitive meaning. My only problem here is whether it is worthwile to change anything or if we should live with it. Besides I believe vast majority of our users don't care.

[gmilde]

I strongly believe this is definitely a "bug" in the sense that the when the code was first written it is 99% certain their author did not think about what \linewidth really means in LaTeX.

I tend to disagree: Already 2006-01-06 (at revision 4242) the Docutils LaTeX writer contained the lines

* width

  * linewidth - width of a line in the local environment
  * textwidth - the width of text on the page

This predates the addition of the method latex_image_length() that translates "%" into

    res = "%.3f\\linewidth" % (float(amount)/100.0)

to

Fix: image width 70% is converted 0.700\linewidth. bug #1457388` -- https://docutils.sourceforge.io/HISTORY.html#release-0-5-2008-06-25

(We may also just ask the author, he is still active on the Docutils mail lists.)

When you visit a PDF on your computer, the PDF viewer will not automagically rescale the viewport to zoom in when you scroll down a list so that the percentage of \linewidth would keep some reasonable intuitive meaning.

IMV, this does not differ from the behaviour in a web browser. You get the same experience when converting the original example to HTML and open in firefox or chromium.

My only problem here is whether it is worthwile to change anything or if we should live with it. Besides I believe vast majority of our users don't care.

I do care. Even if a "length unit" related to the initial text width were desired, it should be a new one, not abusing the well-defined CSS unit "%" (percent of containing elements size). So, I would call it a bug if LaTeX output translated 100% to 1.0\textwidth.

Mayb we can "agree to disagree".

[jfbu]

I strongly believe this is definitely a "bug" in the sense that the when the code was first written it is 99% certain their author did not think about what \linewidth really means in LaTeX.

I tend to disagree: Already 2006-01-06 (at revision 4242) the Docutils LaTeX writer contained the lines

But I am only referring here to Sphinx code base.

I doubt much a Sphinx user employing 10% for an image ending up in table cell anticipates that the \linewidth will be in l or r type columns the actual ambient line width (which, as previously discussed is smaller in lists and quoted environments), but in a p type column will be the target width. And I am convinced this was not either in the mind of the original committer of such choice to the Sphinx code base. Notice that l specifier appears to be Sphinx choice always when cells are merged in a table. In brief; \linewidth is not the width of the line on the page, but generally the width of paragraphs at that place, but there is not alaways a notion of a paragraph, and it is often impossible (especially with tabulary automatic widths specifier LCRJ) to have an idea of what this will turn out to be. When you say 10% you intend to say 10% of something well defined and that you can anticipate.

It will be very hard to convince me this is not a bug...

[jfbu]

Closing as wont-fix! (except I got fooled by sub-optimal interface so I had to re-open and re-close)

[jfbu]

The aim of produing a PDF is to produce a nice PDF not to be consistent with CSS rulings which have nothing whatsoever to do with the typographically oriented notion of PDF.

[jfbu]

the well-defined CSS unit "%" (percent of containing elements size)

The problem is that LaTeX at times have no well-defined notion of a "containing element". LaTeX has no document tree out of the box. I said already that if it had, the LaTeX team would not be working overtime since perhaps 5 years to try to add automatic tagging to LaTeX documents, which is not yet done, not even with the most basic documents using no packages, although there are closing in after years of work. LaTeX predates CSS.

[gmilde]

I assume an author of an rST document wants 2 images that are 50% wide to fit on a line. This should also hold in a quote, minipage, list, or table. Example:

.. |img-16x9| image:: /usr/share/texlive/texmf-dist/tex/latex/mwe/example-image-16x9.jpg
   :width: 50%

Lorem ipsum dolor sit amet, consectetuer adipiscing elit.  Etiam lobortis
facilisis sem. Nullam nec mi et neque pharetra sollicitudin.  Praesent
imperdiet mi nec ante.  Donec ullamcorper, felis non sodales commodo,
lectus velit ultrices augue, a dignissim nibh lectus placerat pede. 
  
  Pellentesque placerat. Nam rutrum augue a leo. Morbi sed elit sit amet
  ante lobortis sollicitudin. Praesent blandit blandit mauris. 

    |img-16x9|\ |img-16x9|   
  
  Praesent lectus tellus, aliquet aliquam, luctus a, egestas a, turpis.
  Mauris lacinia lorem sit amet ipsum. Nunc quis urna dictum turpis
  accumsan semper.

With the current interpretation of %, the result is a nice PDF:

Replacing \linewidth with \textwidth makes it ugly.