Re: [Docutils-develop] Waiting for feedback about issues with the Docutils Doctree [#489]

[Guenter M. <mi...@us...>]

Dear Alan, Karl, and Docutils developers,

On 2024-06-20, Karl O. Pinc wrote:
> On Thu, 20 Jun 2024 Alan <ala...@gm...> wrote:

Thanks for the feedback.

It seems there is an emerging consensus regarding footnotes and citations.

Changing the "document tree" description (docutils.dtd) will not prevent
the creation of footnotes/labels without label or content.
The only immediately visibly change for users would be that

   docutils --validate a-document-with-faulty-footnote.rst
   
would generate an "invalid element" warning. 
  Also, it would make clear that there is no longer a guarantee that these
constructs work with Docutils. (We may remove some test cases.)

Developers of writers or plug-ins would gain from a simpler and consistent
documentation. Their task becomes easier, as they do no longer have to make
sure the new component supports footnotes/citations without label or content.
(In the long term, this may also lead to missing support for these
constructs in the Docutils writers.)

>> - citations without content: I've never seen it
>> - footnotes without content or without "label": I've never seen it


Which leaves figures:

>> - figures without caption/legend: no "legend" is reasonably common,
>>   but no caption is extremely rare and is a need met by `image` (I
>>   believe)

> Figures with no caption would still show up in the TOCs list
> of figures.  (Or whereever that list shows up.) At least
> in docbook.  I think.  Although I don't know how useful that'd
> be since no description would be listed.  I suppose it'd have a figure
> number, which is not entirely useless.
...
> Anyway, the big difference between figures and images,
> in my mind, is that figures tend to appear in some sort
> of listing somewhere and images don't.

Also, figures tend to "flow" to a suitable position in page-based media.

Let's have a look at the current behaviour with various writers:

Input::

  .. image:: docs/user/images/default.png

  .. figure:: docs/user/images/default.png

HTML5 
  just uses a <figure> wrapper (like XML and pseudoXML)::

    <img alt="docs/user/images/default.png" src="docs/user/images/default.png" />
    <figure>
    <img alt="docs/user/images/default.png" src="docs/user/images/default.png" />
    </figure>

  The effect depends on CSS styling: a <figure> may float or get a figure
  number. With the default styles, a figure is set with wider margins on
  both sides. The figure number (cf. `numbered figures`__) is only shown
  if there is a caption but this is an CSS implementation detail.

  __ https://docutils.sourceforge.io/test/functional/expected/standalone_rst_html5.html#numbered-figures)
  
LaTeX
  wraps a figure in a figure float and centre-aligns it::
  
    \includegraphics{docs/user/images/default.png}

    \begin{figure}
    \noindent\makebox[\linewidth][c]{\includegraphics{docs/user/images/default.png}}\end{figure}

  As a result, a figure will usually move to a suitable place on the top of
  a page. 

  However, a figure without caption does not get a figure number and is not
  included in the List of Figures.¹
  
  ¹ A list of figures is not supported by Docutils but can be inserted
    with raw LaTeX. 
  
ODT
  uses a figure frame with empty caption field for the figure.

  However, a figure without caption will not get a figure number and not
  be listed in the List of Figures.¹
  
  ¹ A list of figures is not supported by Docutils but can be inserted
    in the LibreOfficeWriter.

A use case would be an illustration with the caption already included in
the image file, that should flow in LaTeX and/or use a consistent CSS
figure-layout in HTML.

It seems a rare case and support is patchy, so it is, IMO, 
be OK if validation issues a warning. 

* Should the rST user documentation 
  https://docutils.sourceforge.io/docs/ref/rst/directives.html#figure
  be updated/expanded to warn that missing both caption and legend results
  in an invalid <figure> element (suggestions on how to formulate this are
  welcome)?
  
* Should the rST parser report a warning or an error in addition to the
  warning with "--validate"?  

Günter