Re: DocBook 5.2

On 05.09.22 11:59, Daniel Gustafsson wrote:
> Will the markup be similar enough to not carry a significant risk of
> introducing pain for backpatching doc patches?

There are many changes. Most of them are systematically and others are
individual, which is more painful. To give you an impression what
typically changes, here is the diff of an arbitrary file. The
HTML-output looks quite good - as far as I have seen.

diff --git a/doc/src/sgml/xtypes.sgml b/doc/src/sgml/xtypes.sgml
index e67e5bdf4c..6b6e6eb059 100644
--- a/doc/src/sgml/xtypes.sgml
+++ b/doc/src/sgml/xtypes.sgml
@@ -1,6 +1,6 @@
 <!-- doc/src/sgml/xtypes.sgml -->

- <sect1 id="xtypes">
+ <sect1 xml:id="xtypes">
   <title>User-Defined Types</title>

   <indexterm zone="xtypes">
@@ -72,7 +72,7 @@ typedef struct Complex {
   write a complete and robust parser for that representation as your
   input function.  For instance:

-<programlisting><![CDATA[
+<programlisting>
 PG_FUNCTION_INFO_V1(complex_in);

 Datum
@@ -83,23 +83,23 @@ complex_in(PG_FUNCTION_ARGS)
                 y;
     Complex    *result;

-    if (sscanf(str, " ( %lf , %lf )", &x, &y) != 2)
+    if (sscanf(str, " ( %lf , %lf )", &amp;x, &amp;y) != 2)
         ereport(ERROR,
                 (errcode(ERRCODE_INVALID_TEXT_REPRESENTATION),
                  errmsg("invalid input syntax for type %s: \"%s\"",
                         "complex", str)));

     result = (Complex *) palloc(sizeof(Complex));
-    result->x = x;
-    result->y = y;
+    result-&gt;x = x;
+    result-&gt;y = y;
     PG_RETURN_POINTER(result);
 }
-]]>
+
 </programlisting>

   The output function can simply be:

-<programlisting><![CDATA[
+<programlisting>
 PG_FUNCTION_INFO_V1(complex_out);

 Datum
@@ -108,10 +108,10 @@ complex_out(PG_FUNCTION_ARGS)
     Complex    *complex = (Complex *) PG_GETARG_POINTER(0);
     char       *result;

-    result = psprintf("(%g,%g)", complex->x, complex->y);
+    result = psprintf("(%g,%g)", complex-&gt;x, complex-&gt;y);
     PG_RETURN_CSTRING(result);
 }
-]]>
+
 </programlisting>
  </para>

@@ -132,7 +132,7 @@ complex_out(PG_FUNCTION_ARGS)
   <type>complex</type>, we will piggy-back on the binary I/O converters
   for type <type>float8</type>:

-<programlisting><![CDATA[
+<programlisting>
 PG_FUNCTION_INFO_V1(complex_recv);

 Datum
@@ -142,8 +142,8 @@ complex_recv(PG_FUNCTION_ARGS)
     Complex    *result;

     result = (Complex *) palloc(sizeof(Complex));
-    result->x = pq_getmsgfloat8(buf);
-    result->y = pq_getmsgfloat8(buf);
+    result-&gt;x = pq_getmsgfloat8(buf);
+    result-&gt;y = pq_getmsgfloat8(buf);
     PG_RETURN_POINTER(result);
 }

@@ -155,12 +155,12 @@ complex_send(PG_FUNCTION_ARGS)
     Complex    *complex = (Complex *) PG_GETARG_POINTER(0);
     StringInfoData buf;

-    pq_begintypsend(&buf);
-    pq_sendfloat8(&buf, complex->x);
-    pq_sendfloat8(&buf, complex->y);
-    PG_RETURN_BYTEA_P(pq_endtypsend(&buf));
+    pq_begintypsend(&amp;buf);
+    pq_sendfloat8(&amp;buf, complex-&gt;x);
+    pq_sendfloat8(&amp;buf, complex-&gt;y);
+    PG_RETURN_BYTEA_P(pq_endtypsend(&amp;buf));
 }
-]]>
+
 </programlisting>
  </para>

@@ -237,7 +237,7 @@ CREATE TYPE complex (
   If the internal representation of the data type is variable-length, the
   internal representation must follow the standard layout for
variable-length
   data: the first four bytes must be a <type>char[4]</type> field
which is
-  never accessed directly (customarily named
<structfield>vl_len_</structfield>). You
+  never accessed directly (customarily named <varname
remap="structfield">vl_len_</varname>). You
   must use the <function>SET_VARSIZE()</function> macro to store the
total
   size of the datum (including the length field itself) in this field
   and <function>VARSIZE()</function> to retrieve it. (These macros exist
@@ -249,7 +249,7 @@ CREATE TYPE complex (
   <xref linkend="sql-createtype"/> command.
  </para>

- <sect2 id="xtypes-toast">
+ <sect2 xml:id="xtypes-toast">
   <title>TOAST Considerations</title>
    <indexterm>
     <primary>TOAST</primary>
@@ -258,8 +258,7 @@ CREATE TYPE complex (

  <para>
   If the values of your data type vary in size (in internal form), it's
-  usually desirable to make the data type <acronym>TOAST</acronym>-able
(see <xref
-  linkend="storage-toast"/>). You should do this even if the values are
always
+  usually desirable to make the data type <acronym>TOAST</acronym>-able
(see <xref linkend="storage-toast"/>). You should do this even if the
values are always
   too small to be compressed or stored externally, because
   <acronym>TOAST</acronym> can save space on small data too, by
reducing header
   overhead.
@@ -290,7 +289,7 @@ CREATE TYPE complex (

  <note>
   <para>
-   Older code frequently declares <structfield>vl_len_</structfield> as an
+   Older code frequently declares <varname
remap="structfield">vl_len_</varname> as an
    <type>int32</type> field instead of <type>char[4]</type>.  This is
OK as long as
    the struct definition has other fields that have at least
<type>int32</type>
    alignment.  But it is dangerous to use such a struct definition when