Table 9.46. UUID Extraction Functions

On Thu, 2026-10-08 at 04:21 +0000, PG Doc comments form wrote:

Page: https://www.postgresql.org/docs/18/functions-uuid.html

Examples not working; (zero-width space)

select uuid_extract_version('41db1265-8bc1-4ab3-992f-​885799a4af1d'::uuid);
ПОМИЛКА: неприпустимий синтаксис для типу uuid:
"41db1265-8bc1-4ab3-992f-​885799a4af1d"
LINE 1: select uuid_extract_version('41db1265-8bc1-4ab3-992f-​8857...

Right. That must have slipped in by mistake.

Here is a patch:

diff --git a/doc/src/sgml/func/func-uuid.sgml b/doc/src/sgml/func/func-uuid.sgml
index 7b6181b38e7..ac2ea91c9b6 100644
--- a/doc/src/sgml/func/func-uuid.sgml
+++ b/doc/src/sgml/func/func-uuid.sgml
@@ -161,11 +161,11 @@
         return 4.
        </para>
        <para>
-        <literal>uuid_extract_version('41db1265-8bc1-4ab3-992f-&zwsp;885799a4af1d'::uuid)</literal>
+        <literal>uuid_extract_version('41db1265-8bc1-4ab3-992f-885799a4af1d'::uuid)</literal>
         <returnvalue>4</returnvalue>
        </para>
        <para>
-        <literal>uuid_extract_version('019535d9-3df7-79fb-b466-&zwsp;fa907fa17f9e'::uuid)</literal>
+        <literal>uuid_extract_version('019535d9-3df7-79fb-b466-fa907fa17f9e'::uuid)</literal>
         <returnvalue>7</returnvalue>
        </para></entry>
      </row>

Yours,
Laurenz Albe

Laurenz Albe <laurenz.albe@cybertec.at> writes:

On Thu, 2026-10-08 at 04:21 +0000, PG Doc comments form wrote:

Page: https://www.postgresql.org/docs/18/functions-uuid.html

Examples not working; (zero-width space)

select uuid_extract_version('41db1265-8bc1-4ab3-992f-​885799a4af1d'::uuid);
ПОМИЛКА: неприпустимий синтаксис для типу uuid:
"41db1265-8bc1-4ab3-992f-​885799a4af1d"
LINE 1: select uuid_extract_version('41db1265-8bc1-4ab3-992f-​8857...

Right. That must have slipped in by mistake.

Not in the least. Those, and every other &zwsp; in the SGML docs,
are there so that the PDF version renders without complaints about
overlength lines. For cases like this, FOP is not bright enough
to break what looks to it like one huge word, so we have to help it
out by putting in fake whitespace.

If you know another way to accomplish that goal, I wouldn't mind
changing. But just removing these characters isn't OK.

I'm not personally of the opinion that copying-and-pasting our
examples is a useful thing to do, so I'm not particularly concerned
about this complaint.

regards, tom lane

On Thu, 2026-10-08 at 12:41 -0400, Tom Lane wrote:

Laurenz Albe <laurenz.albe@cybertec.at> writes:

On Thu, 2026-10-08 at 04:21 +0000, PG Doc comments form wrote:

Page: https://www.postgresql.org/docs/18/functions-uuid.html

Examples not working; (zero-width space)

select uuid_extract_version('41db1265-8bc1-4ab3-992f-​885799a4af1d'::uuid);
ПОМИЛКА: неприпустимий синтаксис для типу uuid:
"41db1265-8bc1-4ab3-992f-​885799a4af1d"
LINE 1: select uuid_extract_version('41db1265-8bc1-4ab3-992f-​8857...

Right. That must have slipped in by mistake.

Not in the least. Those, and every other &zwsp; in the SGML docs,
are there so that the PDF version renders without complaints about
overlength lines. For cases like this, FOP is not bright enough
to break what looks to it like one huge word, so we have to help it
out by putting in fake whitespace.

If you know another way to accomplish that goal, I wouldn't mind
changing. But just removing these characters isn't OK.

I'm not personally of the opinion that copying-and-pasting our
examples is a useful thing to do, so I'm not particularly concerned
about this complaint.

Ugh. I should have put some effort into research before claiming
it is a mistake.

But I doubt if is is smart to break copy and paste from the HTML
documentation to avoid warnings in the PDF build. I for one regularly
copy and paste stuff from the HTML documentation, and I have seen and
built the PDF documentation for the first time today (before writing
this). I doubt I am the only one. Are these warnings a big problem?

Yours,
Laurenz Albe

Laurenz Albe <laurenz.albe@cybertec.at> writes:

On Thu, 2026-10-08 at 12:41 -0400, Tom Lane wrote:

Not in the least. Those, and every other &zwsp; in the SGML docs,
are there so that the PDF version renders without complaints about
overlength lines.

Ugh. I should have put some effort into research before claiming
it is a mistake.

But I doubt if is is smart to break copy and paste from the HTML
documentation to avoid warnings in the PDF build. I for one regularly
copy and paste stuff from the HTML documentation, and I have seen and
built the PDF documentation for the first time today (before writing
this). I doubt I am the only one. Are these warnings a big problem?

Well, we could ignore those warnings if we chose, but that is not
without cost. In a lot of these places the line would run through
the right margin and completely off the visible page area, making
the text physically unreadable in PDF form. I judge that to be a
bigger problem for consumers of that documentation format than
"I can't cut and paste this example" is for users of the HTML
format.

Now there's certainly a discussion to be had about how many people
still use the PDF output and whether we should just dump it
entirely. But short of doing that, I don't think we can drop our
concern for line length in PDF output.

I still wonder whether there's another solution path though.
We settled on &zwsp; because it fixed the major issue here,
but that doesn't mean there isn't a better answer.

regards, tom lane

On Thu, 2026-10-08 at 23:32 -0400, Tom Lane wrote:

Laurenz Albe <laurenz.albe@cybertec.at> writes:

On Thu, 2026-10-08 at 12:41 -0400, Tom Lane wrote:

Not in the least. Those, and every other &zwsp; in the SGML docs,
are there so that the PDF version renders without complaints about
overlength lines.

I still wonder whether there's another solution path though.
We settled on &zwsp; because it fixed the major issue here,
but that doesn't mean there isn't a better answer.

The funny thing is that the line in question is not broken in the
PDF output that was generated here:

uuid_extract_version('41db1265-8bc1-4ab3-992f-885799a4af1d'::uuid)
→4
uuid_extract_version('019535d9-3df7-79fb-b466-fa907fa17f9e'::uuid)
→7

But elsewhere I see a break:

uuid_extract_timestamp('019535d9-3df7-79fb-b466-
fa907fa17f9e'::uuid) → 2025-02-23 21:46:24.503-05

I think that an improved version could look as follows:

uuid_extract_timestamp(
'019535d9-3df7-79fb-b466-fa907fa17f9e'::uuid
) → 2025-02-23 21:46:24.503-05

Also, not everything (query results etc.) are likely to be copied and
pasted by users. So I guess the way forward would be for me to spend
some time with this. But then - is it *that* important?

Yours,
Laurenz Albe

Laurenz Albe <laurenz.albe@cybertec.at> writes:

On Thu, 2026-10-08 at 23:32 -0400, Tom Lane wrote:

I still wonder whether there's another solution path though.
We settled on &zwsp; because it fixed the major issue here,
but that doesn't mean there isn't a better answer.

I think that an improved version could look as follows:

uuid_extract_timestamp(
'019535d9-3df7-79fb-b466-fa907fa17f9e'::uuid
) → 2025-02-23 21:46:24.503-05

Hmm, yeah, that could work so far as the PDF line-break problem
is concerned. Would it look too odd to HTML readers?

Also, not everything (query results etc.) are likely to be copied and
pasted by users. So I guess the way forward would be for me to spend
some time with this. But then - is it *that* important?

Yup, that. If you want to press forward, have at it; I'm willing
to push fixes in this area.

regards, tom lane

On Fri, 2026-10-09 at 01:35 -0400, Tom Lane wrote:

Laurenz Albe <laurenz.albe@cybertec.at> writes:

On Thu, 2026-10-08 at 23:32 -0400, Tom Lane wrote:

I still wonder whether there's another solution path though.
We settled on &zwsp; because it fixed the major issue here,
but that doesn't mean there isn't a better answer.

I think that an improved version could look as follows:

uuid_extract_timestamp(
'019535d9-3df7-79fb-b466-fa907fa17f9e'::uuid
) → 2025-02-23 21:46:24.503-05

Hmm, yeah, that could work so far as the PDF line-break problem
is concerned. Would it look too odd to HTML readers?

Also, not everything (query results etc.) are likely to be copied and
pasted by users. So I guess the way forward would be for me to spend
some time with this. But then - is it *that* important?

Yup, that. If you want to press forward, have at it; I'm willing
to push fixes in this area.

I felt inspired enough to take a look, and I found only three places
that looked like likely things that someone might copy and paste.

The first didn't actually need a line break in either the US letter
or A4 format, so I simply removed the &zwsp;. I wonder if some other
documentation format might need it though...

For the UUID functions that the complaint was about, I simply added
regular spaces inside the parentheses, which in HTML looks like

uuid_extract_version( '41db1265-8bc1-4ab3-992f-885799a4af1d'::uuid ) → 4

I'd say that that is acceptable.

Yours,
Laurenz Albe

Laurenz Albe <laurenz.albe@cybertec.at> writes:

I felt inspired enough to take a look, and I found only three places
that looked like likely things that someone might copy and paste.

Ah, excellent point. If we consider only fragments of SQL then yes,
the problem gets way smaller.

The first didn't actually need a line break in either the US letter
or A4 format, so I simply removed the &zwsp;. I wonder if some other
documentation format might need it though...

Dunno, I'm not seeing a warning there either. Perhaps that zwsp
dates from before one of the mass reformattings we've done over
the years? I didn't bother doing any archaeology though.

For the UUID functions that the complaint was about, I simply added
regular spaces inside the parentheses, which in HTML looks like
uuid_extract_version( '41db1265-8bc1-4ab3-992f-885799a4af1d'::uuid ) → 4
I'd say that that is acceptable.

Great idea, but when I looked at the rendered A4 PDF I saw why we'd
put in the zwsps: without them, FOP decides that the best way
to break these lines is like

uuid_extract_version('41db1265-8bc1-4ab3-992f-885799a4af1d'::u-
uid)

which of course is really horrid (cf first attached screenshot).
However, adapting your idea a bit, I tried putting spaces around
the "::", and that renders far better (cd second attachment).
So I'll run with that.

regards, tom lane

On Fri, 2026-10-09 at 20:25 -0400, Tom Lane wrote:

Laurenz Albe <laurenz.albe@cybertec.at> writes:

For the UUID functions that the complaint was about, I simply added
regular spaces inside the parentheses, which in HTML looks like
uuid_extract_version( '41db1265-8bc1-4ab3-992f-885799a4af1d'::uuid ) → 4
I'd say that that is acceptable.

Great idea, but when I looked at the rendered A4 PDF I saw why we'd
put in the zwsps: without them, FOP decides that the best way
to break these lines is like

uuid_extract_version('41db1265-8bc1-4ab3-992f-885799a4af1d'::u-
uid)

which of course is really horrid (cf first attached screenshot).
However, adapting your idea a bit, I tried putting spaces around
the "::", and that renders far better (cd second attachment).
So I'll run with that.

Thanks for taking care of that.

Strangely enough, I didn't see those horrid line breaks; for me,
the line broke at the arrow. It seems that there are some
variables unknown to me that influence the output.

Yours,
Laurenz Albe

Laurenz Albe <laurenz.albe@cybertec.at> writes:

Strangely enough, I didn't see those horrid line breaks; for me,
the line broke at the arrow. It seems that there are some
variables unknown to me that influence the output.

There are several different versions of FOP in the wild, and they
don't all act the same in this area. Checking the git history,
I see that I put in the &zwsp;s in question in a6524105d, which
noted that only newer versions of FOP were misbehaving. The one
I'm testing with here is 2.5, which I'm not sure about the age of.

regards, tom lane

On Sat, 2026-10-10 at 12:02 -0400, Tom Lane wrote:

Laurenz Albe <laurenz.albe@cybertec.at> writes:

Strangely enough, I didn't see those horrid line breaks; for me,
the line broke at the arrow. It seems that there are some
variables unknown to me that influence the output.

There are several different versions of FOP in the wild, and they
don't all act the same in this area. Checking the git history,
I see that I put in the &zwsp;s in question in a6524105d, which
noted that only newer versions of FOP were misbehaving. The one
I'm testing with here is 2.5, which I'm not sure about the age of.

Mine is 2.11, so that may explain the difference.

Yours,
Laurenz Albe