Re: tables on pgbench man page look garbled

> On 9 May 2023, at 17:14, Peter Eisentraut <peter(dot)eisentraut(at)enterprisedb(dot)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