Обсуждение: tables on pgbench man page look garbled
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?
> 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 referencepage) look pretty garbled. Also, on macOS, man prints a warning that the page is invalidly formatted. But thegarbledness happens on Linux as well, for example. Apparently, our custom table layout doesn't map properly to the manformat. 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 referencepage) look pretty garbled. Also, on macOS, man prints a warning that the page is invalidly formatted. But thegarbledness happens on Linux as well, for example. Apparently, our custom table layout doesn't map properly to the manformat. 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