Обсуждение: strange para/programlisting pattern in sgml docs

Hi,

while working on a patch I noticed we do this in the SGML docs (for
example in indexam.sgml and a bunch of other files):

  <para>
    ... some text ...
  </para>

  <para>
<programlisting>
some code
</programlisting>
   ... description of the code.
  </para>

That is, the program listing is in a paragraph that starts immediately
before it. I just noticed this ends up like this in the HTML:

  <p>... some text ...</p>

  <p></p>

  <pre>some code</pre>

  <p>... description of the code.</p>

That is, there's an empty <p></p> before <pre>, which seems a bit weird,
but it seems to render fine (at least in Firefox), so maybe it looks
weird but is not a problem in practice ...

I did search for what (X)HTML says about this, and the only thing I
found is HTML5 flow control section [1], which says

    ... elements whose content model allows any flow content should
    have either at least one descendant text node ...

Ofc, we're rendering into XHTML, not HTML5. However, W3 advises against
this in the HTML4.0 document too [2]:

    We discourage authors from using empty P elements. User agents
    should ignore empty P elements.

So it might be "OK" because browsers ignore those elements, but maybe we
should stop doing that anyway?


regards


[1]
https://www.w3.org/TR/2011/WD-html5-20110525/content-models.html#flow-content-0

[2] https://www.w3.org/TR/1998/REC-html40-19980424/struct/text.html#h-9.3.1

-- 
Tomas Vondra
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

On 25.11.23 21:44, Tomas Vondra wrote:
> while working on a patch I noticed we do this in the SGML docs (for
> example in indexam.sgml and a bunch of other files):
> 
>    <para>
>      ... some text ...
>    </para>
> 
>    <para>
> <programlisting>
> some code
> </programlisting>
>     ... description of the code.
>    </para>
> 
> That is, the program listing is in a paragraph that starts immediately
> before it. I just noticed this ends up like this in the HTML:
> 
>    <p>... some text ...</p>
> 
>    <p></p>
> 
>    <pre>some code</pre>
> 
>    <p>... description of the code.</p>
> 
> That is, there's an empty <p></p> before <pre>, which seems a bit weird,
> but it seems to render fine (at least in Firefox), so maybe it looks
> weird but is not a problem in practice ...

This is because in HTML you can't have <pre> inside <p> but in DocBook 
you can have <programlisting> inside <para> (and other similar cases). 
So the DocBook XSLT stylesheets fix that up by splitting the <p> into 
separate <p> elements before and after the <pre>.  It's just a 
coincidence that one of them is empty in this case.