Doc: Fixup misplaced filelist.sgml entities and add some commentary
Started by David G. Johnston10 months ago4 messages
Hi.
Having been in filelist.sgml a bit recently I've noticed that the original
alphabetical ordering of the entities therein hasn't been adhered to.
Partly, I suspect, because there is no guidance about these files and how
they are organized. The attached puts things back into alphabetical order
(by section) and adds some commentary to this and related files, and the
manual.
I made the choice to move the special %allfiles; reference to the top since
placement doesn't matter and burying the one unique thing in the middle of
the file didn't seem helpful. Now both its immediate presence and the
comment point out the existence and purpose of ref/allfiles.sgml.
David J.
Attachments:
doc-reorder-entities-and-comment.difftext/x-patch; charset=US-ASCII; name=doc-reorder-entities-and-comment.diffDownload
diff --git a/doc/src/sgml/docguide.sgml b/doc/src/sgml/docguide.sgml
index db4bcce56e..dc53c88b80 100644
--- a/doc/src/sgml/docguide.sgml
+++ b/doc/src/sgml/docguide.sgml
@@ -70,6 +70,25 @@
</para>
</sect1>
+ <sect1 id="docguide-structure">
+ <title>Documentation Structure</title>
+
+ <para>
+ The root of the XML document that is the manual, the <literal>book</literal>
+ element, is found in <filename>/doc/src/sgml/postgres.sgml</filename>.
+ Within the book are parts, mostly defined within the same file, expect for the
+ Reference part, which is found in <filename>/doc/src/sgml/reference.sgml</filename>.
+ </para>
+
+ <para>
+ Modularization is done by using entities. These are defined in two places as
+ well (corresponding to <filename>postgres.sgml</filename> and
+ <filename>reference.sgml</filename>),
+ <filename>/doc/src/sgml/filelist.sgml</filename> and
+ <filename>/doc/src/sgml/ref/allfiles.sgml</filename>. See comments in those
+ files for more information.
+ </para>
+ </sect1>
<sect1 id="docguide-toolsets">
<title>Tool Sets</title>
diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml
index 25fb99cee6..4f92942964 100644
--- a/doc/src/sgml/filelist.sgml
+++ b/doc/src/sgml/filelist.sgml
@@ -1,5 +1,30 @@
<!-- doc/src/sgml/filelist.sgml -->
+<!--
+ To make organization of the documentation easier, chatpers and sect1 elements
+ are split into separate files. postgres.sgml then references the entities
+ containing chapters to populate the manual's parts while chapters reference
+ the entities containing sect1 elements. Files intended for the Appendix part
+ use a top-level appendix element instead of chapter.
+ The comments pertaining to the parts of the manual herein just provide a bit of
+ context as to the material and location where each entity is referenced.
+
+ Within each grouping below entity references are listed in alphabetical order.
+
+ The "ref" subdirectory contains those pages of the manual that also need to
+ be converted into "man" pages. They use refentry elements as the top-level
+ element. The allfiles.sgml file contains the entity definitions for all of
+ those files which then are made available to the manual via the %allfiles;
+ entity reference below. The entities are then referenced in reference.sgml
+ which itself has a part top-level element suitable for inclusion in
+ postgres.sgml.
+-->
+
+<!-- reference pages -->
+<!ENTITY % allfiles SYSTEM "ref/allfiles.sgml">
+%allfiles;
+
+<!-- introductory material -->
<!ENTITY history SYSTEM "history.sgml">
<!ENTITY info SYSTEM "info.sgml">
<!ENTITY intro SYSTEM "intro.sgml">
@@ -34,96 +59,93 @@
<!ENTITY backup SYSTEM "backup.sgml">
<!ENTITY charset SYSTEM "charset.sgml">
<!ENTITY client-auth SYSTEM "client-auth.sgml">
+<!ENTITY config SYSTEM "config.sgml">
<!ENTITY high-availability SYSTEM "high-availability.sgml">
<!ENTITY installbin SYSTEM "install-binaries.sgml">
<!ENTITY installation SYSTEM "installation.sgml">
-<!ENTITY targets-meson SYSTEM "targets-meson.sgml">
+<!ENTITY jit SYSTEM "jit.sgml">
+<!ENTITY logical-replication SYSTEM "logical-replication.sgml">
<!ENTITY maintenance SYSTEM "maintenance.sgml">
<!ENTITY manage-ag SYSTEM "manage-ag.sgml">
<!ENTITY monitoring SYSTEM "monitoring.sgml">
-<!ENTITY wait_event_types SYSTEM "wait_event_types.sgml">
<!ENTITY regress SYSTEM "regress.sgml">
<!ENTITY runtime SYSTEM "runtime.sgml">
-<!ENTITY config SYSTEM "config.sgml">
+<!ENTITY targets-meson SYSTEM "targets-meson.sgml">
<!ENTITY user-manag SYSTEM "user-manag.sgml">
+<!ENTITY wait_event_types SYSTEM "wait_event_types.sgml">
<!ENTITY wal SYSTEM "wal.sgml">
-<!ENTITY logical-replication SYSTEM "logical-replication.sgml">
-<!ENTITY jit SYSTEM "jit.sgml">
<!-- programmer's guide -->
<!ENTITY bgworker SYSTEM "bgworker.sgml">
<!ENTITY dfunc SYSTEM "dfunc.sgml">
<!ENTITY ecpg SYSTEM "ecpg.sgml">
+<!ENTITY event-trigger SYSTEM "event-trigger.sgml">
<!ENTITY extend SYSTEM "extend.sgml">
<!ENTITY external-projects SYSTEM "external-projects.sgml">
<!ENTITY func-ref SYSTEM "func-ref.sgml">
<!ENTITY infoschema SYSTEM "information_schema.sgml">
<!ENTITY libpq SYSTEM "libpq.sgml">
<!ENTITY lobj SYSTEM "lobj.sgml">
+<!ENTITY plperl SYSTEM "plperl.sgml">
+<!ENTITY plpython SYSTEM "plpython.sgml">
+<!ENTITY plsql SYSTEM "plpgsql.sgml">
+<!ENTITY pltcl SYSTEM "pltcl.sgml">
<!ENTITY rules SYSTEM "rules.sgml">
<!ENTITY spi SYSTEM "spi.sgml">
<!ENTITY trigger SYSTEM "trigger.sgml">
-<!ENTITY event-trigger SYSTEM "event-trigger.sgml">
<!ENTITY xaggr SYSTEM "xaggr.sgml">
<!ENTITY xfunc SYSTEM "xfunc.sgml">
<!ENTITY xindex SYSTEM "xindex.sgml">
<!ENTITY xplang SYSTEM "xplang.sgml">
<!ENTITY xoper SYSTEM "xoper.sgml">
<!ENTITY xtypes SYSTEM "xtypes.sgml">
-<!ENTITY plperl SYSTEM "plperl.sgml">
-<!ENTITY plpython SYSTEM "plpython.sgml">
-<!ENTITY plsql SYSTEM "plpgsql.sgml">
-<!ENTITY pltcl SYSTEM "pltcl.sgml">
-
-<!-- reference pages -->
-<!ENTITY % allfiles SYSTEM "ref/allfiles.sgml">
-%allfiles;
<!-- developer's guide -->
<!ENTITY arch-dev SYSTEM "arch-dev.sgml">
+<!ENTITY archive-modules SYSTEM "archive-modules.sgml">
+<!ENTITY backup-manifest SYSTEM "backup-manifest.sgml">
<!ENTITY bki SYSTEM "bki.sgml">
+<!ENTITY brin SYSTEM "brin.sgml">
+<!ENTITY btree SYSTEM "btree.sgml">
<!ENTITY catalogs SYSTEM "catalogs.sgml">
-<!ENTITY system-views SYSTEM "system-views.sgml">
+<!ENTITY custom-rmgr SYSTEM "custom-rmgr.sgml">
+<!ENTITY custom-scan SYSTEM "custom-scan.sgml">
+<!ENTITY fdwhandler SYSTEM "fdwhandler.sgml">
+<!ENTITY generic-wal SYSTEM "generic-wal.sgml">
<!ENTITY geqo SYSTEM "geqo.sgml">
-<!ENTITY indextypes SYSTEM "indextypes.sgml">
-<!ENTITY btree SYSTEM "btree.sgml">
-<!ENTITY gist SYSTEM "gist.sgml">
-<!ENTITY spgist SYSTEM "spgist.sgml">
<!ENTITY gin SYSTEM "gin.sgml">
-<!ENTITY brin SYSTEM "brin.sgml">
+<!ENTITY gist SYSTEM "gist.sgml">
<!ENTITY hash SYSTEM "hash.sgml">
-<!ENTITY planstats SYSTEM "planstats.sgml">
-<!ENTITY tableam SYSTEM "tableam.sgml">
<!ENTITY indexam SYSTEM "indexam.sgml">
+<!ENTITY indextypes SYSTEM "indextypes.sgml">
+<!ENTITY logicaldecoding SYSTEM "logicaldecoding.sgml">
<!ENTITY nls SYSTEM "nls.sgml">
+<!ENTITY oauth-validators SYSTEM "oauth-validators.sgml">
+<!ENTITY planstats SYSTEM "planstats.sgml">
<!ENTITY plhandler SYSTEM "plhandler.sgml">
-<!ENTITY fdwhandler SYSTEM "fdwhandler.sgml">
-<!ENTITY custom-scan SYSTEM "custom-scan.sgml">
-<!ENTITY logicaldecoding SYSTEM "logicaldecoding.sgml">
-<!ENTITY replication-origins SYSTEM "replication-origins.sgml">
-<!ENTITY archive-modules SYSTEM "archive-modules.sgml">
<!ENTITY protocol SYSTEM "protocol.sgml">
+<!ENTITY replication-origins SYSTEM "replication-origins.sgml">
<!ENTITY sources SYSTEM "sources.sgml">
+<!ENTITY spgist SYSTEM "spgist.sgml">
<!ENTITY storage SYSTEM "storage.sgml">
-<!ENTITY transaction SYSTEM "xact.sgml">
+<!ENTITY system-views SYSTEM "system-views.sgml">
+<!ENTITY tableam SYSTEM "tableam.sgml">
<!ENTITY tablesample-method SYSTEM "tablesample-method.sgml">
+<!ENTITY transaction SYSTEM "xact.sgml">
<!ENTITY wal-for-extensions SYSTEM "wal-for-extensions.sgml">
-<!ENTITY generic-wal SYSTEM "generic-wal.sgml">
-<!ENTITY custom-rmgr SYSTEM "custom-rmgr.sgml">
-<!ENTITY backup-manifest SYSTEM "backup-manifest.sgml">
-<!ENTITY oauth-validators SYSTEM "oauth-validators.sgml">
<!-- contrib information -->
-<!ENTITY contrib SYSTEM "contrib.sgml">
<!ENTITY amcheck SYSTEM "amcheck.sgml">
<!ENTITY auth-delay SYSTEM "auth-delay.sgml">
<!ENTITY auto-explain SYSTEM "auto-explain.sgml">
-<!ENTITY basic-archive SYSTEM "basic-archive.sgml">
<!ENTITY basebackup-to-shell SYSTEM "basebackup-to-shell.sgml">
+<!ENTITY basic-archive SYSTEM "basic-archive.sgml">
<!ENTITY bloom SYSTEM "bloom.sgml">
<!ENTITY btree-gin SYSTEM "btree-gin.sgml">
<!ENTITY btree-gist SYSTEM "btree-gist.sgml">
<!ENTITY citext SYSTEM "citext.sgml">
+<!ENTITY contrib SYSTEM "contrib.sgml">
+<!ENTITY contrib-spi SYSTEM "contrib-spi.sgml">
<!ENTITY cube SYSTEM "cube.sgml">
<!ENTITY dblink SYSTEM "dblink.sgml">
<!ENTITY dict-int SYSTEM "dict-int.sgml">
@@ -144,7 +166,7 @@
<!ENTITY pgbuffercache SYSTEM "pgbuffercache.sgml">
<!ENTITY pgcrypto SYSTEM "pgcrypto.sgml">
<!ENTITY pgfreespacemap SYSTEM "pgfreespacemap.sgml">
-<!ENTITY pglogicalinspect SYSTEM "pglogicalinspect.sgml">
+<!ENTITY pglogicalinspect SYSTEM "pglogicalinspect.sgml">
<!ENTITY pgprewarm SYSTEM "pgprewarm.sgml">
<!ENTITY pgrowlocks SYSTEM "pgrowlocks.sgml">
<!ENTITY pgstatstatements SYSTEM "pgstatstatements.sgml">
@@ -155,7 +177,6 @@
<!ENTITY pgwalinspect SYSTEM "pgwalinspect.sgml">
<!ENTITY postgres-fdw SYSTEM "postgres-fdw.sgml">
<!ENTITY seg SYSTEM "seg.sgml">
-<!ENTITY contrib-spi SYSTEM "contrib-spi.sgml">
<!ENTITY sepgsql SYSTEM "sepgsql.sgml">
<!ENTITY sslinfo SYSTEM "sslinfo.sgml">
<!ENTITY tablefunc SYSTEM "tablefunc.sgml">
@@ -165,40 +186,38 @@
<!ENTITY test-shm-mq SYSTEM "test-shm-mq.sgml">
<!ENTITY tsm-system-rows SYSTEM "tsm-system-rows.sgml">
<!ENTITY tsm-system-time SYSTEM "tsm-system-time.sgml">
-<!ENTITY unaccent SYSTEM "unaccent.sgml">
+<!ENTITY unaccent SYSTEM "unaccent.sgml">
<!ENTITY uuid-ossp SYSTEM "uuid-ossp.sgml">
<!ENTITY vacuumlo SYSTEM "vacuumlo.sgml">
<!ENTITY xml2 SYSTEM "xml2.sgml">
<!-- appendixes -->
+<!ENTITY acronyms SYSTEM "acronyms.sgml">
+<!ENTITY color SYSTEM "color.sgml">
<!ENTITY datetime SYSTEM "datetime.sgml">
<!ENTITY docguide SYSTEM "docguide.sgml">
<!ENTITY errcodes SYSTEM "errcodes.sgml">
+<!ENTITY errcodes-table SYSTEM "errcodes-table.sgml">
<!ENTITY features SYSTEM "features.sgml">
+<!ENTITY features-supported SYSTEM "features-supported.sgml">
+<!ENTITY features-unsupported SYSTEM "features-unsupported.sgml">
+<!ENTITY glossary SYSTEM "glossary.sgml">
<!ENTITY keywords SYSTEM "keywords.sgml">
+<!ENTITY keywords-table SYSTEM "keywords-table.sgml">
+<!ENTITY limits SYSTEM "limits.sgml">
<!ENTITY sourcerepo SYSTEM "sourcerepo.sgml">
+<!-- release notes -->
<!ENTITY release SYSTEM "release.sgml">
<!ENTITY release-18 SYSTEM "release-18.sgml">
-<!ENTITY limits SYSTEM "limits.sgml">
-<!ENTITY acronyms SYSTEM "acronyms.sgml">
-<!ENTITY glossary SYSTEM "glossary.sgml">
-<!ENTITY color SYSTEM "color.sgml">
-
-<!ENTITY features-supported SYSTEM "features-supported.sgml">
-<!ENTITY features-unsupported SYSTEM "features-unsupported.sgml">
-
-<!ENTITY errcodes-table SYSTEM "errcodes-table.sgml">
-<!ENTITY keywords-table SYSTEM "keywords-table.sgml">
-
<!-- back matter -->
<!ENTITY biblio SYSTEM "biblio.sgml">
<!-- Stubs for removed entries to preserve public links -->
<!ENTITY obsolete SYSTEM "appendix-obsolete.sgml">
-<!ENTITY obsolete-recovery-config SYSTEM "appendix-obsolete-recovery-config.sgml">
<!ENTITY obsolete-default-roles SYSTEM "appendix-obsolete-default-roles.sgml">
-<!ENTITY obsolete-pgxlogdump SYSTEM "appendix-obsolete-pgxlogdump.sgml">
<!ENTITY obsolete-pgresetxlog SYSTEM "appendix-obsolete-pgresetxlog.sgml">
<!ENTITY obsolete-pgreceivexlog SYSTEM "appendix-obsolete-pgreceivexlog.sgml">
+<!ENTITY obsolete-pgxlogdump SYSTEM "appendix-obsolete-pgxlogdump.sgml">
+<!ENTITY obsolete-recovery-config SYSTEM "appendix-obsolete-recovery-config.sgml">
diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml
index af476c82fc..22a9bc9870 100644
--- a/doc/src/sgml/postgres.sgml
+++ b/doc/src/sgml/postgres.sgml
@@ -233,6 +233,11 @@ break is not needed in a wider output rendering.
</part>
+ <!--
+ In this section most of the parts have been defined in this file.
+ The Reference Part, however, contains many entity references which would
+ clutter up this file, so it has its own file and entity.
+ -->
&reference;
<part id="internals">
diff --git a/doc/src/sgml/ref/allfiles.sgml b/doc/src/sgml/ref/allfiles.sgml
index f5be638867..7a7b876fbe 100644
--- a/doc/src/sgml/ref/allfiles.sgml
+++ b/doc/src/sgml/ref/allfiles.sgml
@@ -2,6 +2,14 @@
doc/src/sgml/ref/allfiles.sgml
PostgreSQL documentation
Complete list of usable sgml source files in this directory.
+
+See ../filelist.sgml for how this is incorporated into the manual.
+These pages are also used to generate the "man" build outputs.
+
+Pages are listed in alphabetical order. They use refentry top-level
+elements instead of chapters or sections.
+
+Entities defined here are referenced in ../reference.sgml
-->
<!-- SQL commands -->
diff --git a/doc/src/sgml/reference.sgml b/doc/src/sgml/reference.sgml
index ff85ace83f..1c53b396e3 100644
--- a/doc/src/sgml/reference.sgml
+++ b/doc/src/sgml/reference.sgml
@@ -1,5 +1,13 @@
<!-- doc/src/sgml/reference.sgml -->
+<!--
+ Referenced by postgres.sgml, instead of being written inline, because
+ of the large number of entities that are referenced here. This markup
+ of this part is also unique compared to the rest of the manual, using
+ reference elements instead of chapters and sectN elements.
+ The entities referenced herein are defined in ref/allfiles.sgml. See
+ that file for additional structural commentary.
+-->
<part id="reference">
<title>Reference</title>
Re: Doc: Fixup misplaced filelist.sgml entities and add some commentary
Em qua., 19 de mar. de 2025 às 18:14, David G. Johnston <
david.g.johnston@gmail.com> escreveu:
Having been in filelist.sgml a bit recently I've noticed that the original
alphabetical ordering of the entities therein hasn't been adhered to.
Partly, I suspect, because there is no guidance about these files and how
they are organized. The attached puts things back into alphabetical order
(by section) and adds some commentary to this and related files, and the
manual.
Liked that.
Just one typo: chatpers should be chapters.
regards
Marcos
Re: Doc: Fixup misplaced filelist.sgml entities and add some commentary
On Wed, Mar 19, 2025 at 2:31 PM Marcos Pegoraro <marcos@f10.com.br> wrote:
Em qua., 19 de mar. de 2025 às 18:14, David G. Johnston <
david.g.johnston@gmail.com> escreveu:Having been in filelist.sgml a bit recently I've noticed that the
original alphabetical ordering of the entities therein hasn't been adhered
to. Partly, I suspect, because there is no guidance about these files and
how they are organized. The attached puts things back into alphabetical
order (by section) and adds some commentary to this and related files, and
the manual.Liked that.
Just one typo: chatpers should be chapters.
Thanks.
I've got some additional thoughts for the next version; though I figure
this, and the others like it out there right now, won't get much attention
until mid-April.
Be better to do larger refactorings like this after feature freeze anyway.
We've tended to not consider the documentation part of what is frozen so
looking at it post-deadline makes sense.
David J.
Re: Doc: Fixup misplaced filelist.sgml entities and add some commentary
Hi, David,
In the file docguide.sgml, there is a typo.
"Within the book are parts, mostly defined within the same file, expect
for the", the "expect" here should be "except".
Thanks,
Steven
在 2025/3/20 5:13, David G. Johnston 写道:
Show quoted text
Hi.
Having been in filelist.sgml a bit recently I've noticed that the
original alphabetical ordering of the entities therein hasn't been
adhered to. Partly, I suspect, because there is no guidance about these
files and how they are organized. The attached puts things back into
alphabetical order (by section) and adds some commentary to this and
related files, and the manual.I made the choice to move the special %allfiles; reference to the top
since placement doesn't matter and burying the one unique thing in the
middle of the file didn't seem helpful. Now both its immediate presence
and the comment point out the existence and purpose of ref/allfiles.sgml.David J.