Обсуждение: [PATCH] Fix a tiny typo in the documentation

Hello,

This is a patch (against the master branch) to fix a tiny typo in the
documentation.

Here is the only file changed:

* doc/src/sgml/ddl.sgml

(This is the first time I send a patch so sorry if I missed something.)

Have a nice day.
---
 doc/src/sgml/ddl.sgml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index dea04d64db..6f4f1733ca 100644
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -3339,7 +3339,7 @@ SET search_path TO myschema;
     and operator names as it does for table names.  Data type and function
     names can be qualified in exactly the same way as table names.  If you
     need to write a qualified operator name in an expression, there is a
-    special provision: you must write
+    special provision you must write:
 <synopsis>

<literal>OPERATOR(</literal><replaceable>schema</replaceable><literal>.</literal><replaceable>operator</replaceable><literal>)</literal>
 </synopsis>
--

> On 22 Jan 2025, at 09:27, Robin Dupret <robin.dupret@gmail.com> wrote:
>
> Hello,
>
> This is a patch (against the master branch) to fix a tiny typo in the
> documentation.
>
> Here is the only file changed:
>
> * doc/src/sgml/ddl.sgml
>
> (This is the first time I send a patch so sorry if I missed something.)

No worries, it was perfectly fine.  Thanks for your submission and welcome as a
PostgreSQL contributor.

> -    special provision: you must write
> +    special provision you must write:

Nice catch, will fix.

--
Daniel Gustafsson

> On 22 Jan 2025, at 11:23, Daniel Gustafsson <daniel@yesql.se> wrote:
>> On 22 Jan 2025, at 09:27, Robin Dupret <robin.dupret@gmail.com> wrote:

>> -    special provision: you must write
>> +    special provision you must write:
>
> Nice catch, will fix.

Re-reading it I think both placements of ':' are grammatically correct (not
being a native speaker might trick me).  The current one is, I'm sure,
intentional but I agree it looks a bit odd to continue the sentence into a
<programlisting> block and ending it without punctuation.  For now I'm inclined
to leave it though.

--
Daniel Gustafsson

> On 22 Jan 2025, at 11:23, Daniel Gustafsson <daniel@yesql.se> wrote:
>> On 22 Jan 2025, at 09:27, Robin Dupret <robin.dupret@gmail.com> wrote:

>> -    special provision: you must write
>> +    special provision you must write:
>
> Nice catch, will fix.

Re-reading it I think both placements of ':' are grammatically correct (not
being a native speaker might trick me).  The current one is, I'm sure,
intentional but I agree it looks a bit odd to continue the sentence into a
<programlisting> block and ending it without punctuation.  For now I'm inclined
to leave it though.

"David G. Johnston" <david.g.johnston@gmail.com> writes:
> On Wednesday, January 22, 2025, Daniel Gustafsson <daniel@yesql.se> wrote:
>> On 22 Jan 2025, at 11:23, Daniel Gustafsson <daniel@yesql.se> wrote:
>>> On 22 Jan 2025, at 09:27, Robin Dupret <robin.dupret@gmail.com> wrote:
>>>> -    special provision: you must write
>>>> +    special provision you must write:

>> Re-reading it I think both placements of ':' are grammatically correct (not
>> being a native speaker might trick me).

> The colon does belong after provision, not write.  If the colon is
> bothersome rewrite to avoid it altogether.  But the status quo works for me.

I agree: removing the colon from where it is is strictly worse.
There should be some kind of pause or separation there.
Conceivably we could do

-    special provision: you must write
+    special provision. You must write:

But like David, I don't feel a need to change anything here.  There
are many places in our docs where we flow into a <programlisting> or
similar block without punctuation, and most of them read just fine
to me.

            regards, tom lane

Le mer. 22 janv. 2025 à 16:34, Tom Lane <tgl@sss.pgh.pa.us> a écrit :
>
> "David G. Johnston" <david.g.johnston@gmail.com> writes:
> > On Wednesday, January 22, 2025, Daniel Gustafsson <daniel@yesql.se> wrote:
> >> On 22 Jan 2025, at 11:23, Daniel Gustafsson <daniel@yesql.se> wrote:
> >>> On 22 Jan 2025, at 09:27, Robin Dupret <robin.dupret@gmail.com> wrote:
> >>>> -    special provision: you must write
> >>>> +    special provision you must write:
>
> But like David, I don't feel a need to change anything here.  There
> are many places in our docs where we flow into a <programlisting> or
> similar block without punctuation, and most of them read just fine
> to me.
>
Yes, you're right. On the other hand, it is very common to see a colon
right before a block with code or error message so maybe changing it
for a semi-colon or period would make reading less "odd".

But anyway, I'm fine if you leave it as is. :-)
Thanks for your time.