SGML doc file references
Hi,
I'm reading the docs (I'm trying to figure out some replication
things) and I was wondering why the file references [1]https://github.com/jsoref/postgres/commit/sgml-doc-file-refs don't match
the file names.
Most of the inconsistent items are for `obsolete-*` where the filename
is actually `appendix-obsolete-*`. But, oddly, afaict, they were
introduced with these inconsistent names.
In one of those cases, the base of the file is also wrong (pgxlogdump
[2]: https://www.postgresql.org/docs/9.3/pgxlogdump.html
9.3 and 9.4. I know that there are `id=` tags designed to catch old
references, but the comments don't seem to serve that purpose, if they
are, I was wondering if an additional comment explaining their
discrepancies would be warranted.
In one case, it's just a missing `-` (`backupmanifest.sgml` vs
`backup-manifest.sgml`) which feels accidental.
(I do have more technical questions about the docs, but I think I may
try a different venue to ask them.)
Thanks,
[1]: https://github.com/jsoref/postgres/commit/sgml-doc-file-refs
[2]: https://www.postgresql.org/docs/9.3/pgxlogdump.html
[3]: https://www.postgresql.org/docs/9.4/app-pgreceivexlog.html
Attachments:
sgml-doc-file-refs.patchapplication/octet-stream; name=sgml-doc-file-refs.patchDownload
commit 7b3d27a2ef075b05d150a6523574a28097bfda8d
Author: Josh Soref <jsoref@gmail.com>
Date: Thu Jun 16 13:27:50 2022 -0400
Make file references match file names
diff --git a/doc/src/sgml/appendix-obsolete-default-roles.sgml b/doc/src/sgml/appendix-obsolete-default-roles.sgml
index bf828b3..f5133f9 100644
--- a/doc/src/sgml/appendix-obsolete-default-roles.sgml
+++ b/doc/src/sgml/appendix-obsolete-default-roles.sgml
@@ -1,6 +1,6 @@
-<!-- doc/src/sgml/obsolete-default-roles.sgml -->
+<!-- doc/src/sgml/appendix-obsolete-default-roles.sgml -->
<!--
- See doc/src/sgml/obsolete.sgml for why this file exists. Do not change the id attribute.
+ See doc/src/sgml/appendix-obsolete.sgml for why this file exists. Do not change the id attribute.
-->
<sect1 id="default-roles" xreflabel="default-roles">
diff --git a/doc/src/sgml/appendix-obsolete-pgreceivexlog.sgml b/doc/src/sgml/appendix-obsolete-pgreceivexlog.sgml
index f74d0ae..d84412d 100644
--- a/doc/src/sgml/appendix-obsolete-pgreceivexlog.sgml
+++ b/doc/src/sgml/appendix-obsolete-pgreceivexlog.sgml
@@ -1,6 +1,6 @@
-<!-- doc/src/sgml/obsolete-pgxlogdump.sgml -->
+<!-- doc/src/sgml/appendix-obsolete-pgreceivexlog.sgml -->
<!--
- See doc/src/sgml/obsolete.sgml for why this file exists. Do not change the id attribute.
+ See doc/src/sgml/appendix-obsolete.sgml for why this file exists. Do not change the id attribute.
-->
<sect1 id="app-pgreceivexlog" xreflabel="pg_receivexlog">
diff --git a/doc/src/sgml/appendix-obsolete-pgresetxlog.sgml b/doc/src/sgml/appendix-obsolete-pgresetxlog.sgml
index 7d99930..3300861 100644
--- a/doc/src/sgml/appendix-obsolete-pgresetxlog.sgml
+++ b/doc/src/sgml/appendix-obsolete-pgresetxlog.sgml
@@ -1,6 +1,6 @@
-<!-- doc/src/sgml/obsolete-pgresetxlog.sgml -->
+<!-- doc/src/sgml/appendix-obsolete-pgresetxlog.sgml -->
<!--
- See doc/src/sgml/obsolete.sgml for why this file exists. Do not change the id attribute.
+ See doc/src/sgml/appendix-obsolete.sgml for why this file exists. Do not change the id attribute.
-->
<sect1 id="app-pgresetxlog" xreflabel="pg_resetxlog">
diff --git a/doc/src/sgml/appendix-obsolete-pgxlogdump.sgml b/doc/src/sgml/appendix-obsolete-pgxlogdump.sgml
index 4173fee..76f2a8f 100644
--- a/doc/src/sgml/appendix-obsolete-pgxlogdump.sgml
+++ b/doc/src/sgml/appendix-obsolete-pgxlogdump.sgml
@@ -1,6 +1,6 @@
-<!-- doc/src/sgml/obsolete-pgxlogdump.sgml -->
+<!-- doc/src/sgml/appendix-obsolete-pgxlogdump.sgml -->
<!--
- See doc/src/sgml/obsolete.sgml for why this file exists. Do not change the id attribute.
+ See doc/src/sgml/appendix-obsolete.sgml for why this file exists. Do not change the id attribute.
-->
<sect1 id="pgxlogdump" xreflabel="pg_xlogdump">
diff --git a/doc/src/sgml/appendix-obsolete-recovery-config.sgml b/doc/src/sgml/appendix-obsolete-recovery-config.sgml
index 77c4289..1cf4913 100644
--- a/doc/src/sgml/appendix-obsolete-recovery-config.sgml
+++ b/doc/src/sgml/appendix-obsolete-recovery-config.sgml
@@ -1,6 +1,6 @@
-<!-- doc/src/sgml/obsolete-recovery-config.sgml -->
+<!-- doc/src/sgml/appendix-obsolete-recovery-config.sgml -->
<!--
- See doc/src/sgml/obsolete.sgml for why this file exists. Do not change the id attribute.
+ See doc/src/sgml/appendix-obsolete.sgml for why this file exists. Do not change the id attribute.
-->
<sect1 id="recovery-config" xreflabel="recovery.conf">
diff --git a/doc/src/sgml/appendix-obsolete.sgml b/doc/src/sgml/appendix-obsolete.sgml
index d218de6..b1a00c8 100644
--- a/doc/src/sgml/appendix-obsolete.sgml
+++ b/doc/src/sgml/appendix-obsolete.sgml
@@ -1,4 +1,4 @@
-<!-- doc/src/sgml/obsolete.sgml -->
+<!-- doc/src/sgml/appendix-obsolete.sgml -->
<appendix id="appendix-obsolete">
<title>Obsolete or Renamed Features</title>
diff --git a/doc/src/sgml/backup-manifest.sgml b/doc/src/sgml/backup-manifest.sgml
index 6ecf997..771be13 100644
--- a/doc/src/sgml/backup-manifest.sgml
+++ b/doc/src/sgml/backup-manifest.sgml
@@ -1,4 +1,4 @@
-<!-- doc/src/sgml/backupmanifest.sgml -->
+<!-- doc/src/sgml/backup-manifest.sgml -->
<chapter id="backup-manifest-format">
<title>Backup Manifest Format</title>
On 16.06.22 19:30, Josh Soref wrote:
I'm reading the docs (I'm trying to figure out some replication
things) and I was wondering why the file references [1] don't match
the file names.
I think it was never a goal to absolutely make them match all the time,
so a lot of the differences might be accidental. There are also some
tooling restrictions for what characters can be in the output file names.
Peter Eisentraut <peter.eisentraut@enterprisedb.com> wrote:
I think it was never a goal to absolutely make them match all the time,
so a lot of the differences might be accidental.
ok, are they worth fixing? It seems like it'd make sense for files to
properly reference other files so that humans don't have to go looking
for files that don't exist...
There are also some tooling restrictions for what characters can be in the output file names.
I don't think that this applies to the changes I suggested in the
patch I attached in my initial email.
On 17.06.22 19:52, Josh Soref wrote:
Peter Eisentraut <peter.eisentraut@enterprisedb.com> wrote:
I think it was never a goal to absolutely make them match all the time,
so a lot of the differences might be accidental.ok, are they worth fixing?
That would require renaming either the output files or the input files,
and people would really not like either one.
Peter Eisentraut <peter.eisentraut@enterprisedb.com> writes:
On 17.06.22 19:52, Josh Soref wrote:
ok, are they worth fixing?
That would require renaming either the output files or the input files,
and people would really not like either one.
Agreed that renaming those files is not desirable, but the presented
patch was only fixing erroneous/obsolete comments.
regards, tom lane
On 17.06.22 21:33, Tom Lane wrote:
Peter Eisentraut <peter.eisentraut@enterprisedb.com> writes:
On 17.06.22 19:52, Josh Soref wrote:
ok, are they worth fixing?
That would require renaming either the output files or the input files,
and people would really not like either one.Agreed that renaming those files is not desirable, but the presented
patch was only fixing erroneous/obsolete comments.
Yeah, I had totally misinterpreted what was being proposed. Of course,
the patch is most sensible. Committed.