agora inbox for pgsql-docs@postgresql.org
help / color / mirror / Atom feedDuplicate paragraph
12+ messages / 8 participants
[nested] [flat]
* Duplicate paragraph
@ 2021-05-25 03:06 PG Doc comments form <noreply@postgresql.org>
0 siblings, 1 reply; 12+ messages in thread
From: PG Doc comments form @ 2021-05-25 03:06 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org; +Cc: raspreet800@gmail.com
The following documentation comment has been logged on the website:
Page: https://www.postgresql.org/docs/13/sql-syntax-lexical.html
Description:
Greetings
I was going through the documentation of the SQL Language that you have
provided and there is a possible duplicate paragraph that I noticed in
section 4.1 - Lexical Syntax
(https://www.postgresql.org/docs/current/sql-syntax-lexical.html).
In section 4.1.1 (Identifiers and Key Words), there is a paragraph
explaining a variant of quoted identifier that allows Unicode characters.
All content in the paragraph, right up to the end of section 4.1.1, is
almost copied word-by-word in section 4.1.2.3 - String Constants With
Unicode Escapes.
I wasn't able to judge if this was intentional or not, so I ended up writing
this.
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: Duplicate paragraph
@ 2021-05-25 04:35 David G. Johnston <david.g.johnston@gmail.com>
parent: PG Doc comments form <noreply@postgresql.org>
0 siblings, 1 reply; 12+ messages in thread
From: David G. Johnston @ 2021-05-25 04:35 UTC (permalink / raw)
To: raspreet800@gmail.com <raspreet800@gmail.com>; pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>
On Monday, May 24, 2021, PG Doc comments form <noreply@postgresql.org>
wrote:
> Right up to the end of section 4.1.1, is
> almost copied word-by-word in section 4.1.2.3 - String Constants With
> Unicode Escapes.
>
>
They are two different things, as evidenced by there being two different
sections with different section headings, that use the same fundamental
writing rules.
David J.
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: Duplicate paragraph
@ 2021-05-25 13:12 Bruce Momjian <bruce@momjian.us>
parent: David G. Johnston <david.g.johnston@gmail.com>
0 siblings, 2 replies; 12+ messages in thread
From: Bruce Momjian @ 2021-05-25 13:12 UTC (permalink / raw)
To: David G. Johnston <david.g.johnston@gmail.com>; +Cc: raspreet800@gmail.com <raspreet800@gmail.com>; pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>
On Mon, May 24, 2021 at 09:35:49PM -0700, David G. Johnston wrote:
> On Monday, May 24, 2021, PG Doc comments form <noreply@postgresql.org> wrote:
>
> Right up to the end of section 4.1.1, is
> almost copied word-by-word in section 4.1.2.3 - String Constants With
> Unicode Escapes.
>
>
>
> They are two different things, as evidenced by there being two different
> sections with different section headings, that use the same fundamental writing
> rules.
We have gotten reports about this perceived duplication before --- not
sure how we can improve things.
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com
If only the physical world exists, free will is an illusion.
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: Duplicate paragraph
@ 2021-05-25 13:47 David G. Johnston <david.g.johnston@gmail.com>
parent: Bruce Momjian <bruce@momjian.us>
1 sibling, 0 replies; 12+ messages in thread
From: David G. Johnston @ 2021-05-25 13:47 UTC (permalink / raw)
To: Bruce Momjian <bruce@momjian.us>; +Cc: raspreet800@gmail.com <raspreet800@gmail.com>; pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>
On Tuesday, May 25, 2021, Bruce Momjian <bruce@momjian.us> wrote:
> On Mon, May 24, 2021 at 09:35:49PM -0700, David G. Johnston wrote:
> > On Monday, May 24, 2021, PG Doc comments form <noreply@postgresql.org>
> wrote:
> >
> > Right up to the end of section 4.1.1, is
> > almost copied word-by-word in section 4.1.2.3 - String Constants With
> > Unicode Escapes.
> >
> >
> >
> > They are two different things, as evidenced by there being two different
> > sections with different section headings, that use the same fundamental
> writing
> > rules.
>
> We have gotten reports about this perceived duplication before --- not
> sure how we can improve things.
>
Two this year but none the previous 4 sound about right? I’m up to the
challenge of fixing it if avoiding this type of report is the goal.
David J.
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: Duplicate paragraph
@ 2021-05-25 13:55 Tom Lane <tgl@sss.pgh.pa.us>
parent: Bruce Momjian <bruce@momjian.us>
1 sibling, 1 reply; 12+ messages in thread
From: Tom Lane @ 2021-05-25 13:55 UTC (permalink / raw)
To: Bruce Momjian <bruce@momjian.us>; +Cc: David G. Johnston <david.g.johnston@gmail.com>; raspreet800@gmail.com <raspreet800@gmail.com>; pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>
Bruce Momjian <bruce@momjian.us> writes:
> On Mon, May 24, 2021 at 09:35:49PM -0700, David G. Johnston wrote:
>> They are two different things, as evidenced by there being two different
>> sections with different section headings, that use the same fundamental writing
>> rules.
> We have gotten reports about this perceived duplication before --- not
> sure how we can improve things.
Yeah, I was just thinking the same. The rules *are* largely the same,
by design, so the text is necessarily going to be pretty similar.
But merging these sections doesn't sound like an improvement.
One thing we could easily do is not use isomorphic examples in the two
sections. For example, instead of illustrating how to spell "data" in
both forms, use "name" as the example for the identifier case.
regards, tom lane
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: Duplicate paragraph
@ 2021-05-25 14:13 David G. Johnston <david.g.johnston@gmail.com>
parent: Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 0 replies; 12+ messages in thread
From: David G. Johnston @ 2021-05-25 14:13 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: Bruce Momjian <bruce@momjian.us>; raspreet800@gmail.com <raspreet800@gmail.com>; pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>
On Tuesday, May 25, 2021, Tom Lane <tgl@sss.pgh.pa.us> wrote:
> Bruce Momjian <bruce@momjian.us> writes:
> > On Mon, May 24, 2021 at 09:35:49PM -0700, David G. Johnston wrote:
> >> They are two different things, as evidenced by there being two different
> >> sections with different section headings, that use the same fundamental
> writing
> >> rules.
>
> > We have gotten reports about this perceived duplication before --- not
> > sure how we can improve things.
>
> Yeah, I was just thinking the same. The rules *are* largely the same,
> by design, so the text is necessarily going to be pretty similar.
> But merging these sections doesn't sound like an improvement.
Agrreed.
>
> One thing we could easily do is not use isomorphic examples in the two
> sections. For example, instead of illustrating how to spell "data" in
> both forms, use "name" as the example for the identifier case.
>
>
+1. This is the kind change I expected to find once I started looking for
specifics.
David J.
^ permalink raw reply [nested|flat] 12+ messages in thread
* "NewbieDoc Docbook Guide" link broken
@ 2025-06-24 04:17 jian he <jian.universality@gmail.com>
0 siblings, 1 reply; 12+ messages in thread
From: jian he @ 2025-06-24 04:17 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org
hi.
in https://www.postgresql.org/docs/current/docguide-docbook.html
the link (https://newbiedoc.sourceforge.net/metadoc/docbook-guide.html)
for (NewbieDoc Docbook Guide) is broken.
google around I found this [2]
[2]: https://ftp.sun.ac.za/ftp/pub/documentation/newbiedoc/newbiedoc-html/docbook-guide.en/index-docbook-...
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: "NewbieDoc Docbook Guide" link broken
@ 2025-06-24 05:04 Michael Paquier <michael@paquier.xyz>
parent: jian he <jian.universality@gmail.com>
0 siblings, 1 reply; 12+ messages in thread
From: Michael Paquier @ 2025-06-24 05:04 UTC (permalink / raw)
To: jian he <jian.universality@gmail.com>; +Cc: pgsql-docs@lists.postgresql.org
On Tue, Jun 24, 2025 at 12:17:46PM +0800, jian he wrote:
> in https://www.postgresql.org/docs/current/docguide-docbook.html
> the link (https://newbiedoc.sourceforge.net/metadoc/docbook-guide.html)
> for (NewbieDoc Docbook Guide) is broken.
>
> google around I found this [2]
> [2]: https://ftp.sun.ac.za/ftp/pub/documentation/newbiedoc/newbiedoc-html/docbook-guide.en/index-docbook-...
Not sure that it is a good idea to point to an external site while the
original site of the project is still around:
https://sourceforge.net/projects/newbiedoc/.
At the same time, perhaps there are better resources than a project
that had no updates since 2011, or we could consider removing this
reference. I have never used it, but perhaps some find it useful.
--
Michael
Attachments:
[application/pgp-signature] signature.asc (832B, ../../aFox51TyCwudikdN@paquier.xyz/2-signature.asc)
download
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: "NewbieDoc Docbook Guide" link broken
@ 2025-06-24 07:19 Daniel Gustafsson <daniel@yesql.se>
parent: Michael Paquier <michael@paquier.xyz>
0 siblings, 1 reply; 12+ messages in thread
From: Daniel Gustafsson @ 2025-06-24 07:19 UTC (permalink / raw)
To: Michael Paquier <michael@paquier.xyz>; +Cc: jian he <jian.universality@gmail.com>; pgsql-docs@lists.postgresql.org
> On 24 Jun 2025, at 07:04, Michael Paquier <michael@paquier.xyz> wrote:
>
> On Tue, Jun 24, 2025 at 12:17:46PM +0800, jian he wrote:
>> in https://www.postgresql.org/docs/current/docguide-docbook.html
>> the link (https://newbiedoc.sourceforge.net/metadoc/docbook-guide.html)
>> for (NewbieDoc Docbook Guide) is broken.
>>
>> google around I found this [2]
>> [2]: https://ftp.sun.ac.za/ftp/pub/documentation/newbiedoc/newbiedoc-html/docbook-guide.en/index-docbook-...
>
> Not sure that it is a good idea to point to an external site while the
> original site of the project is still around:
> https://sourceforge.net/projects/newbiedoc/.
>
> At the same time, perhaps there are better resources than a project
> that had no updates since 2011, or we could consider removing this
> reference. I have never used it, but perhaps some find it useful.
Downloading what newbiedoc still ships shows no trace of docbook introdoctions,
so whatever we decided valuable back in the 8.1 days when this was added seems
gone now. I propose to apply the below and simply remove it.
--- a/doc/src/sgml/docguide.sgml
+++ b/doc/src/sgml/docguide.sgml
@@ -60,9 +60,7 @@
maintained by the <ulink url="https://www.oasis-open.org";
OASIS group</ulink>. The <ulink url="https://www.oasis-open.org/docbook/";
official DocBook site</ulink> has good introductory and reference documentation and
- a complete O'Reilly book for your online reading pleasure. The
- <ulink url="http://newbiedoc.sourceforge.net/metadoc/docbook-guide.html";
- NewbieDoc Docbook Guide</ulink> is very helpful for beginners.
+ a complete O'Reilly book for your online reading pleasure.
The <ulink url="https://www.freebsd.org/docproj/";
FreeBSD Documentation Project</ulink> also uses DocBook and has some good
information, including a number of style guidelines that might be
--
Daniel Gustafsson
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: "NewbieDoc Docbook Guide" link broken
@ 2025-06-24 07:36 Magnus Hagander <magnus@hagander.net>
parent: Daniel Gustafsson <daniel@yesql.se>
0 siblings, 1 reply; 12+ messages in thread
From: Magnus Hagander @ 2025-06-24 07:36 UTC (permalink / raw)
To: Daniel Gustafsson <daniel@yesql.se>; +Cc: Michael Paquier <michael@paquier.xyz>; jian he <jian.universality@gmail.com>; pgsql-docs@lists.postgresql.org
On Tue, Jun 24, 2025 at 9:20 AM Daniel Gustafsson <daniel@yesql.se> wrote:
> > On 24 Jun 2025, at 07:04, Michael Paquier <michael@paquier.xyz> wrote:
> >
> > On Tue, Jun 24, 2025 at 12:17:46PM +0800, jian he wrote:
> >> in https://www.postgresql.org/docs/current/docguide-docbook.html
> >> the link (https://newbiedoc.sourceforge.net/metadoc/docbook-guide.html)
> >> for (NewbieDoc Docbook Guide) is broken.
> >>
> >> google around I found this [2]
> >> [2]:
> https://ftp.sun.ac.za/ftp/pub/documentation/newbiedoc/newbiedoc-html/docbook-guide.en/index-docbook-...
> >
> > Not sure that it is a good idea to point to an external site while the
> > original site of the project is still around:
> > https://sourceforge.net/projects/newbiedoc/.
> >
> > At the same time, perhaps there are better resources than a project
> > that had no updates since 2011, or we could consider removing this
> > reference. I have never used it, but perhaps some find it useful.
>
> Downloading what newbiedoc still ships shows no trace of docbook
> introdoctions,
> so whatever we decided valuable back in the 8.1 days when this was added
> seems
> gone now. I propose to apply the below and simply remove it.
>
> --- a/doc/src/sgml/docguide.sgml
> +++ b/doc/src/sgml/docguide.sgml
> @@ -60,9 +60,7 @@
> maintained by the <ulink url="https://www.oasis-open.org";
> OASIS group</ulink>. The <ulink url="
> https://www.oasis-open.org/docbook/";
> official DocBook site</ulink> has good introductory and reference
> documentation and
> - a complete O'Reilly book for your online reading pleasure. The
> - <ulink url="
> http://newbiedoc.sourceforge.net/metadoc/docbook-guide.html";
> - NewbieDoc Docbook Guide</ulink> is very helpful for beginners.
> + a complete O'Reilly book for your online reading pleasure.
> The <ulink url="https://www.freebsd.org/docproj/";
> FreeBSD Documentation Project</ulink> also uses DocBook and has some
> good
> information, including a number of style guidelines that might be
>
+1.
--
Magnus Hagander
Me: https://www.hagander.net/ <http://www.hagander.net/;
Work: https://www.redpill-linpro.com/ <http://www.redpill-linpro.com/;
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: "NewbieDoc Docbook Guide" link broken
@ 2025-06-24 07:44 Michael Paquier <michael@paquier.xyz>
parent: Magnus Hagander <magnus@hagander.net>
0 siblings, 1 reply; 12+ messages in thread
From: Michael Paquier @ 2025-06-24 07:44 UTC (permalink / raw)
To: Magnus Hagander <magnus@hagander.net>; +Cc: Daniel Gustafsson <daniel@yesql.se>; jian he <jian.universality@gmail.com>; pgsql-docs@lists.postgresql.org
On Tue, Jun 24, 2025 at 09:36:20AM +0200, Magnus Hagander wrote:
> On Tue, Jun 24, 2025 at 9:20 AM Daniel Gustafsson <daniel@yesql.se> wrote:
>> Downloading what newbiedoc still ships shows no trace of docbook
>> introdoctions,
>> so whatever we decided valuable back in the 8.1 days when this was added
>> seems
>> gone now. I propose to apply the below and simply remove it.
>
> +1.
+1.
--
Michael
Attachments:
[application/pgp-signature] signature.asc (832B, ../../aFpXSCPpQkoFk_mb@paquier.xyz/2-signature.asc)
download
^ permalink raw reply [nested|flat] 12+ messages in thread
* Re: "NewbieDoc Docbook Guide" link broken
@ 2025-06-24 10:03 Daniel Gustafsson <daniel@yesql.se>
parent: Michael Paquier <michael@paquier.xyz>
0 siblings, 0 replies; 12+ messages in thread
From: Daniel Gustafsson @ 2025-06-24 10:03 UTC (permalink / raw)
To: Michael Paquier <michael@paquier.xyz>; +Cc: Magnus Hagander <magnus@hagander.net>; jian he <jian.universality@gmail.com>; pgsql-docs@lists.postgresql.org
> On 24 Jun 2025, at 09:44, Michael Paquier <michael@paquier.xyz> wrote:
>
> On Tue, Jun 24, 2025 at 09:36:20AM +0200, Magnus Hagander wrote:
>> On Tue, Jun 24, 2025 at 9:20 AM Daniel Gustafsson <daniel@yesql.se> wrote:
>>> Downloading what newbiedoc still ships shows no trace of docbook
>>> introdoctions,
>>> so whatever we decided valuable back in the 8.1 days when this was added
>>> seems
>>> gone now. I propose to apply the below and simply remove it.
>>
>> +1.
>
> +1.
Done, backpatched down to 13.
--
Daniel Gustafsson
^ permalink raw reply [nested|flat] 12+ messages in thread
end of thread, other threads:[~2025-06-24 10:03 UTC | newest]
Thread overview: 12+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2021-05-25 03:06 Duplicate paragraph PG Doc comments form <noreply@postgresql.org>
2021-05-25 04:35 ` David G. Johnston <david.g.johnston@gmail.com>
2021-05-25 13:12 ` Bruce Momjian <bruce@momjian.us>
2021-05-25 13:47 ` David G. Johnston <david.g.johnston@gmail.com>
2021-05-25 13:55 ` Tom Lane <tgl@sss.pgh.pa.us>
2021-05-25 14:13 ` David G. Johnston <david.g.johnston@gmail.com>
2025-06-24 04:17 "NewbieDoc Docbook Guide" link broken jian he <jian.universality@gmail.com>
2025-06-24 05:04 ` Re: "NewbieDoc Docbook Guide" link broken Michael Paquier <michael@paquier.xyz>
2025-06-24 07:19 ` Re: "NewbieDoc Docbook Guide" link broken Daniel Gustafsson <daniel@yesql.se>
2025-06-24 07:36 ` Re: "NewbieDoc Docbook Guide" link broken Magnus Hagander <magnus@hagander.net>
2025-06-24 07:44 ` Re: "NewbieDoc Docbook Guide" link broken Michael Paquier <michael@paquier.xyz>
2025-06-24 10:03 ` Re: "NewbieDoc Docbook Guide" link broken Daniel Gustafsson <daniel@yesql.se>
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox