Subject: Re: initdb - creating clusters
To: pgsql-docs@lists.postgresql.org
References: <159430831443.16535.11360317280100947016@wrigleys.postgresql.org>
 <20200721002503.GA4065@momjian.us>
 <508F1D03-F896-4436-92B0-B9EA633BD1AE@yesql.se>
 <20200722163437.GA14522@momjian.us>
 <FB84D258-CED8-46BB-B30E-2006953F61AA@yesql.se>
 <CA+hUKGLjvXWn_O1PxAKXFEneGHrOos-QOe3try+ZbqPWrNiNrg@mail.gmail.com>
 <3793995.1598800896@sss.pgh.pa.us>
From: =?UTF-8?Q?J=c3=bcrgen_Purtz?= <juergen@purtz.de>
Message-ID: <fa23a037-4211-9d1a-6271-bdcb9236e9fa@purtz.de>
Date: Mon, 31 Aug 2020 12:09:57 +0200
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101
 Thunderbird/68.10.0
MIME-Version: 1.0
In-Reply-To: <3793995.1598800896@sss.pgh.pa.us>
Content-Type: multipart/mixed;
 boundary="------------18B0EE281E374EF470BC13EE"
Content-Language: en-US
Precedence: bulk

This is a multi-part message in MIME format.
--------------18B0EE281E374EF470BC13EE
Content-Type: text/plain; charset=utf-8; format=flowed
Content-Transfer-Encoding: 7bit

On 30.08.20 17:21, Tom Lane wrote:
> Do you have a feeling one way or the other about whether to repeat
> some of this text in each of the relevant sub-sections?  I initially
> didn't want to do that, but thinking about how people consume the
> HTML docs, I'm afraid that anything not appearing on the same page
> won't get seen.

If we do so but avoid redundant text parts, we can use the entity 
mechanism or the more modern XInclude mechanism. The attached patch uses 
both techniques in an example file: brin.sgml includes lorem.sgml two times.

(In both cases we should avoid files with multiple root elements, eg. 
multiple <para> or <sect1> without a parent element, because this would 
violate the well-formed-ness of the included XML document.)

--

J. Purtz


--------------18B0EE281E374EF470BC13EE
Content-Type: text/x-patch; charset=UTF-8;
 name="0001-lorem.patch"
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment;
 filename="0001-lorem.patch"

diff --git a/doc/src/sgml/Makefile b/doc/src/sgml/Makefile
index 0401a515df..562f607190 100644
--- a/doc/src/sgml/Makefile
+++ b/doc/src/sgml/Makefile
@@ -132,8 +132,8 @@ endif
 html: html-stamp
 
 html-stamp: stylesheet.xsl postgres.sgml $(ALLSGML) $(ALL_IMAGES)
-	$(XMLLINT) $(XMLINCLUDE) --noout --valid $(word 2,$^)
-	$(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_FLAGS) $(wordlist 1,2,$^)
+	$(XMLLINT) $(XMLINCLUDE) --noout --xinclude --postvalid --noent $(word 2,$^)
+	$(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) --xinclude $(XSLTPROC_HTML_FLAGS) $(wordlist 1,2,$^)
 	cp $(ALL_IMAGES) html/
 	cp $(srcdir)/stylesheet.css html/
 	touch $@
@@ -167,12 +167,12 @@ postgres.pdf:
 XSLTPROC_FO_FLAGS += --stringparam img.src.path '$(srcdir)/'
 
 %-A4.fo: stylesheet-fo.xsl %.sgml $(ALLSGML)
-	$(XMLLINT) $(XMLINCLUDE) --noout --valid $(word 2,$^)
-	$(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(XSLTPROC_FO_FLAGS) --stringparam paper.type A4 -o $@ $(wordlist 1,2,$^)
+	$(XMLLINT) $(XMLINCLUDE) --noout --xinclude --postvalid --noent $(word 2,$^)
+	$(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) --xinclude $(XSLTPROC_FO_FLAGS) --stringparam paper.type A4 -o $@ $(wordlist 1,2,$^)
 
 %-US.fo: stylesheet-fo.xsl %.sgml $(ALLSGML)
-	$(XMLLINT) $(XMLINCLUDE) --noout --valid $(word 2,$^)
-	$(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(XSLTPROC_FO_FLAGS) --stringparam paper.type USletter -o $@ $(wordlist 1,2,$^)
+	$(XMLLINT) $(XMLINCLUDE) --noout --xinclude --postvalid --noent $(word 2,$^)
+	$(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) --xinclude $(XSLTPROC_FO_FLAGS) --stringparam paper.type USletter -o $@ $(wordlist 1,2,$^)
 
 %.pdf: %.fo $(ALL_IMAGES)
 	$(FOP) -fo $< -pdf $@
diff --git a/doc/src/sgml/brin.sgml b/doc/src/sgml/brin.sgml
index 4420794e5b..ac5ef96173 100644
--- a/doc/src/sgml/brin.sgml
+++ b/doc/src/sgml/brin.sgml
@@ -11,6 +11,13 @@
 <sect1 id="brin-intro">
  <title>Introduction</title>
 
+ <!-- entity mechanism  -->
+ <para>via entity mechanism:</para>
+ &lorem;
+ <!-- xinclude mechanism -->
+ <para>via xinclude mechanism:</para>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="lorem.sgml" />
+
  <para>
   <acronym>BRIN</acronym> stands for Block Range Index.
   <acronym>BRIN</acronym> is designed for handling very large tables
diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml
index 64b5da0070..2e42197844 100644
--- a/doc/src/sgml/filelist.sgml
+++ b/doc/src/sgml/filelist.sgml
@@ -182,3 +182,5 @@
 
 <!-- back matter -->
 <!ENTITY biblio     SYSTEM "biblio.sgml">
+
+<!ENTITY lorem      SYSTEM "lorem.sgml">
diff --git a/doc/src/sgml/lorem.sgml b/doc/src/sgml/lorem.sgml
new file mode 100644
index 0000000000..ffb557bf22
--- /dev/null
+++ b/doc/src/sgml/lorem.sgml
@@ -0,0 +1,5 @@
+  <para>
+   Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
+   do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+   An arbitrary xref-link: <xref linkend="app-pgbasebackup"/>
+  </para>

--------------18B0EE281E374EF470BC13EE--