HTML br tags are inserted before each line within EX/EE man macros

[gokcehan]

We have a man page for lf that we maintain using man macros. We wrap code snippets and monospace verbatim contents within .EX and .EE macros. It seems that debiman inserts <br/> tags before each line when rendering these contents.

For example, we have the following in the man page:

.PP
The following commands/keybindings are provided by default:
.PP
.EX
    Unix                     Windows
    cmd open &$OPENER "$f"   cmd open &%OPENER% %f%
    map e $$EDITOR "$f"      map e $%EDITOR% %f%
    map i $$PAGER "$f"       map i !%PAGER% %f%
    map w $$SHELL            map w $%SHELL%
.EE

Output of this section is as follows:

<p class="Pp">The following commands/keybindings are provided by default:</p>
<p class="Pp"></p>
<pre><br/>
    Unix                     Windows
<br/>
    cmd open &amp;$OPENER &#34;$f&#34;   cmd open &amp;%OPENER% %f%
<br/>
    map e $$EDITOR &#34;$f&#34;      map e $%EDITOR% %f%
<br/>
    map i $$PAGER &#34;$f&#34;       map i !%PAGER% %f%
<br/>
    map w $$SHELL            map w $%SHELL%
</pre>

The rendered output currently shows up as follows:

When I tried mandoc myself on my machine, no such extra <br/> tags are inserted:

<div class="Pp"></div>
The following commands/keybindings are provided by default:
<div class="Pp"></div>
<pre>
    Unix                          Windows
    cmd open &amp;$OPENER &quot;$f&quot;        cmd open &amp;%OPENER% %f%
    map e $$EDITOR &quot;$f&quot;           map e $%EDITOR% %f%
    map i $$PAGER &quot;$f&quot;            map i !%PAGER% %f%
    map w $$SHELL                 map w $%SHELL%
    cmd doc $$lf -doc | $PAGER    cmd doc !%lf% -doc | %PAGER%
    map &lt;f-1&gt; doc                 map &lt;f-1&gt; doc
</pre>

Is there are reason debiman inserts those extra <br/> tags? If this is working as intended, then is there a workaround to avoid these <br/> tags?

I have looked at other man page hosts and it seems that the arch man page for lf also have these extra <br/> tags. It seems that this behavior is previously reported and it is currently marked as a bug. Arch linux also seems to use mandoc so maybe it could be related.

[stapelberg]

Can you test if you can reproduce this problem directly using mandoc?

If so, please report this issue upstream with mandoc.

I don’t currently have time to look into this in any capacity. Sorry.

[gokcehan]

@stapelberg Extra <br/> tags are not inserted when I run mandoc myself. You can see the output with regular mandoc in my original post. That is executed with mandoc -Ofragment -Thtml lf.1 which I think has the same arguments used in debiman.

It's no problem if you don't have time to look at this. I might take a look at this myself if I find some time.

[DakotaB75]

Thanks for the detailed reproduction, this is very helpful.

Given that:

• mandoc itself does not emit <br/> inside <pre> blocks
• and debiman invokes mandoc with -Thtml -Ofragment

this strongly suggests the extra <br/> tags are introduced during
debiman’s HTML post-processing phase rather than by mandoc itself.

In particular, <pre> should preserve newlines verbatim and should not
receive line-level <br/> injection, as this breaks monospace alignment
and semantic correctness.

A possible direction would be:

• detect <pre> nodes early in the conversion pipeline
• and explicitly skip any newline-to-<br/> normalization for their
  descendants

Before attempting a fix, it would be useful to pinpoint exactly where
the <br/> nodes are introduced in debiman/internal/convert.

Happy to help investigate or prototype a fix once we agree on the
expected behavior.

[stapelberg]

It looks like the lf manpages switched from using .EX and .EE macros to .nf and .fi macros, thereby working around the issue.

Arch Linux has decided to work around the issue https://gitlab.archlinux.org/archlinux/archmanweb/-/commit/18220cdfb60dfea3baff0baa9875d4f9dca92b4c

The bug was reported upstream in June 2022, with a similar workaround: https://inbox.vuxu.org/mandoc-discuss/4F394515-B0B2-45F9-87D6-994D86A16223@outlook.com/

I’ll send a patch to see what upstream says. I’d prefer fixing this in mandoc instead of working around the issue in debiman.

[stapelberg]

@stapelberg Extra <br/> tags are not inserted when I run mandoc myself. You can see the output with regular mandoc in my original post. That is executed with mandoc -Ofragment -Thtml lf.1 which I think has the same arguments used in debiman.

This is not my experience. For me, when I run mandoc 1.14.6 (from NixOS) on the (old) lf man page, I do see the <br/> tags.