Missing visual space in nested lists

[Julien-Elie]

The following POD source results in a different rendering between the roff and text outputs:

=head1 test

=over 4

=item A

Line

=over 4

=item 1

=item 2

=back

=item B

Line

=item C

Line

=back

pod2text result:

    A   Line

        1
        2

    B   Line

    C   Line

pod2man result:

       A   Line

           1.
           2.
       B   Line

       C   Line

Shouldn't a visual space be added before B?

I had to add Z<> to force that visual space in the POD source but I believe it should have been there from the start, like in the text output.

Incidentally, I see that the HTML output with pod2html is also wrong, and even does not honour Z<>... https://www.eyrie.org/~eagle/software/inn/docs/INN-ovsqlite_client.html (for instance before tag :response_codes and add_article). Looks like I should also open a bug report for Pod::Html.

[rra]

Thanks, this was a very subtle state tracking problem that should now be fixed.

My web site doesn't use pod2html. It uses Pod::Thread and App::DocKnot instead. I'm not currently seeing the problem with the generated HTML, but maybe you found a workaround?

[Julien-Elie]

Thanks for the fix in pod2man!

I've just checked again the display in https://www.eyrie.org/~eagle/software/inn/docs/INN-ovsqlite_client.html It seems to depend on the browser. It indeed looks fine in Chrome and Edge, which both insert a vertical space between search_col_overview and tag :response_codes. But current versions of Firefox or Safari do not. (I've not tested with other browsers.)

Generated HTML is:

<dl>
<dt>tag :search_cols</dt>
<dd><p>
Flags to select what optional information the <code>search_group</code> method should
return.
</p>

<dl>
<dt>search_col_arrived</dt>
<dd></dd>

<dt>search_col_expires</dt>
<dd></dd>

<dt>search_col_token</dt>
<dd></dd>

<dt>search_col_overview</dt>
<dd></dd>

</dl></dd>

<dt>tag :response_codes</dt>
</dl>

from:

=over 4

=item tag :search_cols

Flags to select what optional information the C<search_group> method should
return.

=over 8

=item search_col_arrived

=item search_col_expires

=item search_col_token

=item search_col_overview

=back

Z<>

=item tag :response_codes

=back

As far as I see, Z<> is not taken into account in the HTML page of your web site. Would it be a bug in Pod::Thread and App::DocKnot in fact? Using pod2html, <p></p> is correctly output with that Z<>.

But about the initial reported bug, I'm wondering whether the HTML output without Z<> shouldn't surround the nested <dl>...</dl> with <p><dl>...</dl></p>. For pod2html too.

By the way, it also leads to another question about the workaround I did for the pod2man output: with the additional Z<> I forced, the output will now show two line breaks. (It is what I see if I use pod2text.). So I should remove it I bet, right now. The output will eventually be fine for users or packagers who generate the manual pages when their system has the fix.

[rra]

Z<> should probably have created an empty paragraph. That's a bug in https://github.com/rra/pod-thread, I think, although I've not looked at it in detail.

<dl> is not phrasing content and therefore is not allowed inside <p>, I believe. It is a structural element at the same level of the structure hierarchy as <p>, which makes sense since it can contain <p> elements.

Interesting that there are now two line breaks if you have Z<> in there. That also feels like a bug; I'll take a look.

[rra]

I took a closer look at the Z<> case, and I think I've convinced myself that the extra blank lines are correct. This in essence creates a paragraph under :search_cols but outside the =over list, so pod2man should render that paragraph. The paragraph happens to be empty, but the point of Z<> is to be able to force empty text to look non-empty when you know better than the formatter.

If you want a workaround that will work with older versions of pod2man, use:

=over 4

=item tag :search_cols

Flags to select what optional information the C<search_group> method should
return.

=over 8

=item search_col_arrived

=item search_col_expires

=item search_col_token

=item search_col_overview

S< >

=back

=item tag :response_codes

=back

That's a single space inside S< >. Note the placement within the last nested item, rather than under the top-level item where you had Z<>. This unfortunately does change the formatting, though, with both old and new versions of pod2man, adding another blank line.

[Julien-Elie]

OK, thanks for your comments. Indeed, <dl> is not allowed inside <p>, and I agree with your analysis. Issue closed then :)

The behaviour of pod2man is now good, and there's nothing else to change (except perhaps for Pod::Thread where Z<> does not create an empty paragraph with the above sample).