pg.ddx.io  pgsql-docs@postgresql.org mailing list archive  
help / color / mirror / Atom feed
Updates on Docbook information
9+ messages / 3 participants
[nested] [flat]

Commits from this thread:
  2026-10-24 0019a1ecf4  doc: Fix removal of FreeBSD mention in DocBook section
  2026-10-24 7c4098e6ba  doc: Remove mention of FreeBSD using DocBook
* Updates on Docbook information
@ 2026-10-23 20:40  Matemática A3K <matematica.a3k@gmail.com>
  0 siblings, 1 reply; 9+ messages in thread

From: Matemática A3K @ 2026-10-23 20:40 UTC (permalink / raw)
  To: pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>

In https://www.postgresql.org/docs/18/docguide-docbook.html it says:
"...
DocBook is maintained by the OASIS group. The [official DocBook site]
has good introductory and reference documentation and a complete
O'Reilly book for your online reading pleasure. The [FreeBSD
Documentation Project] also uses DocBook and has some good
information, including a number of style guidelines that might be
worth considering.
"
which caught my attention with:
- "DocBook is maintained by the OASIS group.": No longer true, see
https://docbook.org/
-  [official DocBook site] points to
https://www.oasis-open.org/docbook/, and "has good introductory and
reference documentation and a complete O'Reilly book for your online
reading pleasure" seems not appropriate for the page
- "The [FreeBSD Documentation Project] also uses DocBook and has some
good information, including a number of style guidelines that might be
worth considering.": No longer true, it currently use asciidoc and
there are no references to docbook in the current website

I think those sentences should be replaced with:
"...
The [DocBook site] has good introductory and reference documentation,
a complete O'Reilly book for your online reading pleasure, and an
archive with previously released versions.
"

Also, in https://www.postgresql.org/docs/18/docguide-toolsets.html says:
"...
[DocBook DTD]
This is the definition of DocBook itself. We currently use version
4.5; you cannot use later or earlier versions. You need the XML
variant of the DocBook DTD, not the SGML variant.
"
where [DocBook DTD] points to https://www.oasis-open.org/docbook/ and
it is not found there. It should point to
https://archive.docbook.org/schemas/ where you can find the 4.5 DTD.

I attach a patch with the proposed changes for review / further refinement.

Thanks!

Attachments:

0001_doc_docbook_fix.patch (text/x-patch, 1.6K) download diff --git a/doc/src/sgml/docguide.sgml b/doc/src/sgml/docguide.sgml index 7b61b4841aa..f1cdb0f7584 100644 --- a/doc/src/sgml/docguide.sgml +++ b/doc/src/sgml/docguide.sgml @@ -56,15 +56,11 @@ <productname>DocBook</productname> allows an author to specify the structure and content of a technical document without worrying about presentation details. A document style defines how that - content is rendered into one of several final forms. DocBook is - 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="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 - worth considering. + content is rendered into one of several final forms. + The <ulink url="https://docbook.org/"> DocBook site</ulink> has + good introductory and reference documentation, + a complete O'Reilly book for your online reading pleasure, + and an archive with previously released versions. </para> </sect1> @@ -78,7 +74,7 @@ <variablelist> <varlistentry id="docguide-toolsets-docbook-dtd"> - <term><ulink url="https://www.oasis-open.org/docbook/">DocBook DTD</ulink></term> + <term><ulink url="https://archive.docbook.org/schemas/">DocBook DTD</ulink></term> <listitem> <para> This is the definition of DocBook itself. We currently use version
^ permalink raw reply [nested|flat] 9+ messages in thread

* Re: Updates on Docbook information
@ 2026-10-24 20:38  Daniel Gustafsson <daniel@yesql.se>
  parent: Matemática A3K <matematica.a3k@gmail.com>
  0 siblings, 2 replies; 9+ messages in thread

From: Daniel Gustafsson @ 2026-10-24 20:38 UTC (permalink / raw)
  To: Matemática A3K <matematica.a3k@gmail.com>; +Cc: pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>

> On 23 Oct 2026, at 22:40, Matemática A3K <matematica.a3k@gmail.com> wrote:
> 
> In https://www.postgresql.org/docs/18/docguide-docbook.html it says:
> "...
> DocBook is maintained by the OASIS group. The [official DocBook site]
> has good introductory and reference documentation and a complete
> O'Reilly book for your online reading pleasure. The [FreeBSD
> Documentation Project] also uses DocBook and has some good
> information, including a number of style guidelines that might be
> worth considering.
> "
> which caught my attention with:
> - "DocBook is maintained by the OASIS group.": No longer true, see
> https://docbook.org/

If the TC was truly shut down, I would think the OASIS would remove the content
or at least make some form of notice about that fact.  The statements on
docbook.org might be all true, but before redirecting links from authoritative
sources I'd prefer a bit more context than an unsubstantiated claim.

> - "The [FreeBSD Documentation Project] also uses DocBook and has some
> good information, including a number of style guidelines that might be
> worth considering.": No longer true, it currently use asciidoc and
> there are no references to docbook in the current website

This part I do agree with, and I have pushed a removal of this sentence.

--
Daniel Gustafsson







^ permalink  raw  reply  [nested|flat] 9+ messages in thread

* Re: Updates on Docbook information
@ 2026-10-24 20:42  Tom Lane <tgl@sss.pgh.pa.us>
  parent: Daniel Gustafsson <daniel@yesql.se>
  1 sibling, 1 reply; 9+ messages in thread

From: Tom Lane @ 2026-10-24 20:42 UTC (permalink / raw)
  To: Daniel Gustafsson <daniel@yesql.se>; +Cc: Matemática A3K <matematica.a3k@gmail.com>; pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>

Daniel Gustafsson <daniel@yesql.se> writes:
> This part I do agree with, and I have pushed a removal of this sentence.

Looks like you only got most of the sentence:

@@ -61,9 +61,6 @@
    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="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
    worth considering.
   </para>
  </sect1>

			regards, tom lane





^ permalink  raw  reply  [nested|flat] 9+ messages in thread

* Re: Updates on Docbook information
@ 2026-10-24 20:43  Daniel Gustafsson <daniel@yesql.se>
  parent: Tom Lane <tgl@sss.pgh.pa.us>
  0 siblings, 0 replies; 9+ messages in thread

From: Daniel Gustafsson @ 2026-10-24 20:43 UTC (permalink / raw)
  To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: Matemática A3K <matematica.a3k@gmail.com>; pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>

> On 24 Oct 2026, at 22:42, Tom Lane <tgl@sss.pgh.pa.us> wrote:
> 
> Daniel Gustafsson <daniel@yesql.se> writes:
>> This part I do agree with, and I have pushed a removal of this sentence.
> 
> Looks like you only got most of the sentence:

Ugh, fixing.

--
Daniel Gustafsson







^ permalink  raw  reply  [nested|flat] 9+ messages in thread

* Re: Updates on Docbook information
@ 2026-10-24 21:45  Matemática A3K <matematica.a3k@gmail.com>
  parent: Daniel Gustafsson <daniel@yesql.se>
  1 sibling, 1 reply; 9+ messages in thread

From: Matemática A3K @ 2026-10-24 21:45 UTC (permalink / raw)
  To: Daniel Gustafsson <daniel@yesql.se>; +Cc: pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>

On Sat, Oct 24, 2026 at 5:39 PM Daniel Gustafsson <daniel@yesql.se> wrote:
>
> > On 23 Oct 2026, at 22:40, Matemática A3K <matematica.a3k@gmail.com> wrote:
> >
> > In https://www.postgresql.org/docs/18/docguide-docbook.html it says:
> > "...
> > DocBook is maintained by the OASIS group. The [official DocBook site]
> > has good introductory and reference documentation and a complete
> > O'Reilly book for your online reading pleasure. The [FreeBSD
> > Documentation Project] also uses DocBook and has some good
> > information, including a number of style guidelines that might be
> > worth considering.
> > "
> > which caught my attention with:
> > - "DocBook is maintained by the OASIS group.": No longer true, see
> > https://docbook.org/
>
> If the TC was truly shut down, I would think the OASIS would remove the content
> or at least make some form of notice about that fact.  The statements on
> docbook.org might be all true, but before redirecting links from authoritative
> sources I'd prefer a bit more context than an unsubstantiated claim.

FYI: https://groups.oasis-open.org/discussion/docbook-technical-committee-meeting-minutes-13sep2024

> > - "The [FreeBSD Documentation Project] also uses DocBook and has some
> > good information, including a number of style guidelines that might be
> > worth considering.": No longer true, it currently use asciidoc and
> > there are no references to docbook in the current website
>
> This part I do agree with, and I have pushed a removal of this sentence.

All the best,
Rodrigo

>
> --
> Daniel Gustafsson
>






^ permalink  raw  reply  [nested|flat] 9+ messages in thread

* Re: Updates on Docbook information
@ 2026-10-25 22:34  Daniel Gustafsson <daniel@yesql.se>
  parent: Matemática A3K <matematica.a3k@gmail.com>
  0 siblings, 1 reply; 9+ messages in thread

From: Daniel Gustafsson @ 2026-10-25 22:34 UTC (permalink / raw)
  To: Matemática A3K <matematica.a3k@gmail.com>; +Cc: pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>

> On 24 Oct 2026, at 23:45, Matemática A3K <matematica.a3k@gmail.com> wrote:
> On Sat, Oct 24, 2026 at 5:39 PM Daniel Gustafsson <daniel@yesql.se> wrote:

>> If the TC was truly shut down, I would think the OASIS would remove the content
>> or at least make some form of notice about that fact.  The statements on
>> docbook.org might be all true, but before redirecting links from authoritative
>> sources I'd prefer a bit more context than an unsubstantiated claim.
> 
> FYI: https://groups.oasis-open.org/discussion/docbook-technical-committee-meeting-minutes-13sep2024

That's a good data point, but it still doesn't explain why Oasis still publish
the TC and host the archives etc two years after that meeting.  I don't have
any reason to question the fine folks on the DocBook TC (or you) but before I
redirect where our users are expected to download stuff from I prefer
questionmarks to be removed.  For now the site we link to host the files and
the docs.

--
Daniel Gustafsson







^ permalink  raw  reply  [nested|flat] 9+ messages in thread

* Re: Updates on Docbook information
@ 2026-10-26 00:37  Matemática A3K <matematica.a3k@gmail.com>
  parent: Daniel Gustafsson <daniel@yesql.se>
  0 siblings, 1 reply; 9+ messages in thread

From: Matemática A3K @ 2026-10-26 00:37 UTC (permalink / raw)
  To: Daniel Gustafsson <daniel@yesql.se>; +Cc: pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>

On Sun, Oct 25, 2026 at 7:35 PM Daniel Gustafsson <daniel@yesql.se> wrote:
>
> > On 24 Oct 2026, at 23:45, Matemática A3K <matematica.a3k@gmail.com> wrote:
> > On Sat, Oct 24, 2026 at 5:39 PM Daniel Gustafsson <daniel@yesql.se> wrote:
>
> >> If the TC was truly shut down, I would think the OASIS would remove the content
> >> or at least make some form of notice about that fact.  The statements on
> >> docbook.org might be all true, but before redirecting links from authoritative
> >> sources I'd prefer a bit more context than an unsubstantiated claim.
> >
> > FYI: https://groups.oasis-open.org/discussion/docbook-technical-committee-meeting-minutes-13sep2024
>
> That's a good data point, but it still doesn't explain why Oasis still publish
> the TC and host the archives etc two years after that meeting.  I don't have
> any reason to question the fine folks on the DocBook TC (or you) but before I
> redirect where our users are expected to download stuff from I prefer
> questionmarks to be removed.  For now the site we link to host the files and
> the docs.

I'm not sure if I am understanding you, but did you notice that all
the links in the Repository section of the TC page are broken?

>
> --
> Daniel Gustafsson
>






^ permalink  raw  reply  [nested|flat] 9+ messages in thread

* Re: Updates on Docbook information
@ 2026-10-26 10:07  Daniel Gustafsson <daniel@yesql.se>
  parent: Matemática A3K <matematica.a3k@gmail.com>
  0 siblings, 1 reply; 9+ messages in thread

From: Daniel Gustafsson @ 2026-10-26 10:07 UTC (permalink / raw)
  To: Matemática A3K <matematica.a3k@gmail.com>; +Cc: pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>

> On 26 Oct 2026, at 01:37, Matemática A3K <matematica.a3k@gmail.com> wrote:
> 
> On Sun, Oct 25, 2026 at 7:35 PM Daniel Gustafsson <daniel@yesql.se> wrote:
>> 
>>> On 24 Oct 2026, at 23:45, Matemática A3K <matematica.a3k@gmail.com> wrote:
>>> On Sat, Oct 24, 2026 at 5:39 PM Daniel Gustafsson <daniel@yesql.se> wrote:
>> 
>>>> If the TC was truly shut down, I would think the OASIS would remove the content
>>>> or at least make some form of notice about that fact.  The statements on
>>>> docbook.org might be all true, but before redirecting links from authoritative
>>>> sources I'd prefer a bit more context than an unsubstantiated claim.
>>> 
>>> FYI: https://groups.oasis-open.org/discussion/docbook-technical-committee-meeting-minutes-13sep2024
>> 
>> That's a good data point, but it still doesn't explain why Oasis still publish
>> the TC and host the archives etc two years after that meeting.  I don't have
>> any reason to question the fine folks on the DocBook TC (or you) but before I
>> redirect where our users are expected to download stuff from I prefer
>> questionmarks to be removed.  For now the site we link to host the files and
>> the docs.
> 
> I'm not sure if I am understanding you, but did you notice that all
> the links in the Repository section of the TC page are broken?

I know, and I don't disagree with improving this, it's just not entirely clear
what the exact status is given the mixed messaging from the TC and docbook.org.

--
Daniel Gustafsson







^ permalink  raw  reply  [nested|flat] 9+ messages in thread

* Re: Updates on Docbook information
@ 2026-10-26 21:07  Matemática A3K <matematica.a3k@gmail.com>
  parent: Daniel Gustafsson <daniel@yesql.se>
  0 siblings, 0 replies; 9+ messages in thread

From: Matemática A3K @ 2026-10-26 21:07 UTC (permalink / raw)
  To: Daniel Gustafsson <daniel@yesql.se>; +Cc: pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>

On Mon, Oct 26, 2026 at 7:07 AM Daniel Gustafsson <daniel@yesql.se> wrote:
>
> > On 26 Oct 2026, at 01:37, Matemática A3K <matematica.a3k@gmail.com> wrote:
> >
> > On Sun, Oct 25, 2026 at 7:35 PM Daniel Gustafsson <daniel@yesql.se> wrote:
> >>
> >>> On 24 Oct 2026, at 23:45, Matemática A3K <matematica.a3k@gmail.com> wrote:
> >>> On Sat, Oct 24, 2026 at 5:39 PM Daniel Gustafsson <daniel@yesql.se> wrote:
> >>
> >>>> If the TC was truly shut down, I would think the OASIS would remove the content
> >>>> or at least make some form of notice about that fact.  The statements on
> >>>> docbook.org might be all true, but before redirecting links from authoritative
> >>>> sources I'd prefer a bit more context than an unsubstantiated claim.
> >>>
> >>> FYI: https://groups.oasis-open.org/discussion/docbook-technical-committee-meeting-minutes-13sep2024
> >>
> >> That's a good data point, but it still doesn't explain why Oasis still publish
> >> the TC and host the archives etc two years after that meeting.  I don't have
> >> any reason to question the fine folks on the DocBook TC (or you) but before I
> >> redirect where our users are expected to download stuff from I prefer
> >> questionmarks to be removed.  For now the site we link to host the files and
> >> the docs.
> >
> > I'm not sure if I am understanding you, but did you notice that all
> > the links in the Repository section of the TC page are broken?
>
> I know, and I don't disagree with improving this, it's just not entirely clear
> what the exact status is given the mixed messaging from the TC and docbook.org.

Perhaps if you state what seems contradictory to you we can help to resolve it.

>
> --
> Daniel Gustafsson
>






^ permalink  raw  reply  [nested|flat] 9+ messages in thread


end of thread, other threads:[~2026-10-26 21:07 UTC | newest]

Thread overview: 9+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2026-10-23 20:40 Updates on Docbook information Matemática A3K <matematica.a3k@gmail.com>
2026-10-24 20:38 ` Daniel Gustafsson <daniel@yesql.se>
2026-10-24 20:42   ` Tom Lane <tgl@sss.pgh.pa.us>
2026-10-24 20:43     ` Daniel Gustafsson <daniel@yesql.se>
2026-10-24 21:45   ` Matemática A3K <matematica.a3k@gmail.com>
2026-10-25 22:34     ` Daniel Gustafsson <daniel@yesql.se>
2026-10-26 00:37       ` Matemática A3K <matematica.a3k@gmail.com>
2026-10-26 10:07         ` Daniel Gustafsson <daniel@yesql.se>
2026-10-26 21:07           ` Matemática A3K <matematica.a3k@gmail.com>

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