pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedtables on pgbench man page look garbled
7+ messages / 3 participants
[nested] [flat]
* tables on pgbench man page look garbled
@ 2023-05-09 13:40 Peter Eisentraut <peter.eisentraut@enterprisedb.com>
2023-05-09 13:58 ` Re: tables on pgbench man page look garbled Daniel Gustafsson <daniel@yesql.se>
0 siblings, 1 reply; 7+ messages in thread
From: Peter Eisentraut @ 2023-05-09 13:40 UTC (permalink / raw)
To: pgsql-docs
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?
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: tables on pgbench man page look garbled
2023-05-09 13:40 tables on pgbench man page look garbled Peter Eisentraut <peter.eisentraut@enterprisedb.com>
@ 2023-05-09 13:58 ` Daniel Gustafsson <daniel@yesql.se>
2023-05-09 15:14 ` Re: tables on pgbench man page look garbled Peter Eisentraut <peter.eisentraut@enterprisedb.com>
0 siblings, 1 reply; 7+ messages in thread
From: Daniel Gustafsson @ 2023-05-09 13:58 UTC (permalink / raw)
To: Peter Eisentraut <peter.eisentraut@enterprisedb.com>; +Cc: pgsql-docs
> 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
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: tables on pgbench man page look garbled
2023-05-09 13:40 tables on pgbench man page look garbled Peter Eisentraut <peter.eisentraut@enterprisedb.com>
2023-05-09 13:58 ` Re: tables on pgbench man page look garbled Daniel Gustafsson <daniel@yesql.se>
@ 2023-05-09 15:14 ` Peter Eisentraut <peter.eisentraut@enterprisedb.com>
2023-05-10 13:19 ` Re: tables on pgbench man page look garbled Daniel Gustafsson <daniel@yesql.se>
0 siblings, 1 reply; 7+ messages in thread
From: Peter Eisentraut @ 2023-05-09 15:14 UTC (permalink / raw)
To: Daniel Gustafsson <daniel@yesql.se>; +Cc: pgsql-docs
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.
Attachments:
[image/png] Screenshot 2023-05-09 at 17.13.09.png (224.8K, ../../f574fa79-d56c-2c99-f623-8d965833eb5d@enterprisedb.com/2-Screenshot%202023-05-09%20at%2017.13.09.png)
download | view image
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: tables on pgbench man page look garbled
2023-05-09 13:40 tables on pgbench man page look garbled Peter Eisentraut <peter.eisentraut@enterprisedb.com>
2023-05-09 13:58 ` Re: tables on pgbench man page look garbled Daniel Gustafsson <daniel@yesql.se>
2023-05-09 15:14 ` Re: tables on pgbench man page look garbled Peter Eisentraut <peter.eisentraut@enterprisedb.com>
@ 2023-05-10 13:19 ` Daniel Gustafsson <daniel@yesql.se>
2023-05-10 15:35 ` Re: tables on pgbench man page look garbled Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 1 reply; 7+ messages in thread
From: Daniel Gustafsson @ 2023-05-10 13:19 UTC (permalink / raw)
To: Peter Eisentraut <peter.eisentraut@enterprisedb.com>; +Cc: pgsql-docs
> 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
Attachments:
[application/octet-stream] mandoc_para_tbl.diff (556B, ../../EABCE89B-3A6D-4D9D-B2A3-FCF7C801C74D@yesql.se/2-mandoc_para_tbl.diff)
download | inline diff:
diff --git a/doc/src/sgml/stylesheet-man.xsl b/doc/src/sgml/stylesheet-man.xsl
index fcb485c293..5ea72b32f5 100644
--- a/doc/src/sgml/stylesheet-man.xsl
+++ b/doc/src/sgml/stylesheet-man.xsl
@@ -42,6 +42,13 @@
</xsl:template>
+<!-- Remove paragraphs from table textblocks since mandoc doesn't support
+ macros in tables.
+-->
+<xsl:template match="row/entry/para">
+ <xsl:apply-templates/>
+</xsl:template>
+
<!-- Make superscripts visible in man pages (default is no decoration) -->
<xsl:template match="superscript">
<xsl:text>^</xsl:text>
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: tables on pgbench man page look garbled
2023-05-09 13:40 tables on pgbench man page look garbled Peter Eisentraut <peter.eisentraut@enterprisedb.com>
2023-05-09 13:58 ` Re: tables on pgbench man page look garbled Daniel Gustafsson <daniel@yesql.se>
2023-05-09 15:14 ` Re: tables on pgbench man page look garbled Peter Eisentraut <peter.eisentraut@enterprisedb.com>
2023-05-10 13:19 ` Re: tables on pgbench man page look garbled Daniel Gustafsson <daniel@yesql.se>
@ 2023-05-10 15:35 ` Tom Lane <tgl@sss.pgh.pa.us>
2023-05-10 20:08 ` Re: tables on pgbench man page look garbled Daniel Gustafsson <daniel@yesql.se>
0 siblings, 1 reply; 7+ messages in thread
From: Tom Lane @ 2023-05-10 15:35 UTC (permalink / raw)
To: Daniel Gustafsson <daniel@yesql.se>; +Cc: Peter Eisentraut <peter.eisentraut@enterprisedb.com>; pgsql-docs
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
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: tables on pgbench man page look garbled
2023-05-09 13:40 tables on pgbench man page look garbled Peter Eisentraut <peter.eisentraut@enterprisedb.com>
2023-05-09 13:58 ` Re: tables on pgbench man page look garbled Daniel Gustafsson <daniel@yesql.se>
2023-05-09 15:14 ` Re: tables on pgbench man page look garbled Peter Eisentraut <peter.eisentraut@enterprisedb.com>
2023-05-10 13:19 ` Re: tables on pgbench man page look garbled Daniel Gustafsson <daniel@yesql.se>
2023-05-10 15:35 ` Re: tables on pgbench man page look garbled Tom Lane <tgl@sss.pgh.pa.us>
@ 2023-05-10 20:08 ` Daniel Gustafsson <daniel@yesql.se>
2023-05-15 12:35 ` Re: tables on pgbench man page look garbled Daniel Gustafsson <daniel@yesql.se>
0 siblings, 1 reply; 7+ messages in thread
From: Daniel Gustafsson @ 2023-05-10 20:08 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: Peter Eisentraut <peter.eisentraut@enterprisedb.com>; pgsql-docs
> 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
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: tables on pgbench man page look garbled
2023-05-09 13:40 tables on pgbench man page look garbled Peter Eisentraut <peter.eisentraut@enterprisedb.com>
2023-05-09 13:58 ` Re: tables on pgbench man page look garbled Daniel Gustafsson <daniel@yesql.se>
2023-05-09 15:14 ` Re: tables on pgbench man page look garbled Peter Eisentraut <peter.eisentraut@enterprisedb.com>
2023-05-10 13:19 ` Re: tables on pgbench man page look garbled Daniel Gustafsson <daniel@yesql.se>
2023-05-10 15:35 ` Re: tables on pgbench man page look garbled Tom Lane <tgl@sss.pgh.pa.us>
2023-05-10 20:08 ` Re: tables on pgbench man page look garbled Daniel Gustafsson <daniel@yesql.se>
@ 2023-05-15 12:35 ` Daniel Gustafsson <daniel@yesql.se>
0 siblings, 0 replies; 7+ messages in thread
From: Daniel Gustafsson @ 2023-05-15 12:35 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: Peter Eisentraut <peter.eisentraut@enterprisedb.com>; pgsql-docs
> 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
^ permalink raw reply [nested|flat] 7+ messages in thread
end of thread, other threads:[~2023-05-15 12:35 UTC | newest]
Thread overview: 7+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2023-05-09 13:40 tables on pgbench man page look garbled Peter Eisentraut <peter.eisentraut@enterprisedb.com>
2023-05-09 13:58 ` Daniel Gustafsson <daniel@yesql.se>
2023-05-09 15:14 ` Peter Eisentraut <peter.eisentraut@enterprisedb.com>
2023-05-10 13:19 ` Daniel Gustafsson <daniel@yesql.se>
2023-05-10 15:35 ` Tom Lane <tgl@sss.pgh.pa.us>
2023-05-10 20:08 ` Daniel Gustafsson <daniel@yesql.se>
2023-05-15 12:35 ` Daniel Gustafsson <daniel@yesql.se>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox