tables on pgbench man page look garbled

On 9 May 2023, at 15:40, Peter Eisentraut <peter.eisentraut@enterprisedb.com> wrote:

The tables "pgbench Operators" and "pgbench Functions" on the pgbench man page (the actual man page, not the HTML reference page) look pretty garbled. Also, on macOS, man prints a warning that the page is invalidly formatted. But the garbledness happens on Linux as well, for example. Apparently, our custom table layout doesn't map properly to the man format. But for example, the earlier table "pgbench Automatic Variables", which doesn't use the custom table layout, looks fine. Anyone feel like looking into this further?

Can you post a screenshot of what it looks like? I just built the manpages
from HEAD on macOS and while they report the UNSUPP error the table itself
looks like I would expect it to.

--
Daniel Gustafsson

On 09.05.23 15:58, Daniel Gustafsson wrote:

On 9 May 2023, at 15:40, Peter Eisentraut <peter.eisentraut@enterprisedb.com> wrote:

The tables "pgbench Operators" and "pgbench Functions" on the pgbench man page (the actual man page, not the HTML reference page) look pretty garbled. Also, on macOS, man prints a warning that the page is invalidly formatted. But the garbledness happens on Linux as well, for example. Apparently, our custom table layout doesn't map properly to the man format. But for example, the earlier table "pgbench Automatic Variables", which doesn't use the custom table layout, looks fine. Anyone feel like looking into this further?

Can you post a screenshot of what it looks like? I just built the manpages
from HEAD on macOS and while they report the UNSUPP error the table itself
looks like I would expect it to.

Here.

Note that formatting instructions (".PP") show in the output.

On 9 May 2023, at 17:14, Peter Eisentraut <peter.eisentraut@enterprisedb.com> wrote:

Note that formatting instructions (".PP") show in the output.

I took a look at this using macOS as the initial testbed; the TLDR is that
mandoc doesn't support macros in tables, and our single-column function
signature tables rely on that. macOS switched to mandoc in v11 I think, but I
don't have an older box handy to doublecheck.

Each row in the table is currently emitted like this:

T{
.PP
\fIboolean\fR
IS [NOT] (NULL|TRUE|FALSE)
→ \fIboolean\fR

.PP
Boolean value tests

.PP
1 is null
→ FALSE
T}

The .PP rendered in the output comes from the macro being indented from column
zero in the man page, the .PP macro on column zero is removed during rendering
and cause the UNSUPP warning.

Adding a rule in stylesheet-man.xsl to remove row/entry/para makes the manpages
render without warning, and the tables are no longer garbled. The attached PoC
diff is what I used for this.

That being said, the output is still not very good since T{T} text blocks are
not rendered with implicit newlines, all content is rendered on a single line
with whitespace intact but newlines stripped. This is mainly a problem for our
new-style function tables which use vertical whitespace for separation rather
than columns, but it also affects regular tables like the backslash sequence on
COPY(7) which is rendered like this:

"Backslash x followed by one or two hex digits specifies the byte
with that numeric code"

The whitespace gap in the output comes from a linebreak and indentation in the
source file.

The amount of whitespace can to some degree be controlled to some degree by
refactoring the indentation in pgbench.sgml file, but that seems like quite the
nightmare to maintain.

Not sure what the best path going forward is, relying on in-column formatting
for tables seems problematic when mandoc is used.

--
Daniel Gustafsson

Daniel Gustafsson <daniel@yesql.se> writes:

I took a look at this using macOS as the initial testbed; the TLDR is that
mandoc doesn't support macros in tables, and our single-column function
signature tables rely on that. macOS switched to mandoc in v11 I think, but I
don't have an older box handy to doublecheck.

Hmm, any chance of addressing this by expanding out the relevant macros?

regards, tom lane

On 10 May 2023, at 17:35, Tom Lane <tgl@sss.pgh.pa.us> wrote:

Daniel Gustafsson <daniel@yesql.se> writes:

I took a look at this using macOS as the initial testbed; the TLDR is that
mandoc doesn't support macros in tables, and our single-column function
signature tables rely on that. macOS switched to mandoc in v11 I think, but I
don't have an older box handy to doublecheck.

Hmm, any chance of addressing this by expanding out the relevant macros?

Maybe, but I'm not too optimistic about that since I was unable to coerce
mandoc into accepting any form of explicit linebreaks in T{T} text blocks.

--
Daniel Gustafsson

On 10 May 2023, at 22:08, Daniel Gustafsson <daniel@yesql.se> wrote:

On 10 May 2023, at 17:35, Tom Lane <tgl@sss.pgh.pa.us> wrote:

Daniel Gustafsson <daniel@yesql.se> writes:

I took a look at this using macOS as the initial testbed; the TLDR is that
mandoc doesn't support macros in tables, and our single-column function
signature tables rely on that. macOS switched to mandoc in v11 I think, but I
don't have an older box handy to doublecheck.

Hmm, any chance of addressing this by expanding out the relevant macros?

Maybe, but I'm not too optimistic about that since I was unable to coerce
mandoc into accepting any form of explicit linebreaks in T{T} text blocks.

Having spent some more time on this I've been unsuccessful in getting anything
to look better than the originally proposed diff upthread; which is far from
good but a) better than the current garbled output and b) fixes the warnings
from mandoc. Not sure how to make progress on this.

--
Daniel Gustafsson