Re: DocBook 5.2 - Mailing list pgsql-docs

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 )", &x, &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->x = x;
+    result->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->x, complex->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->x = pq_getmsgfloat8(buf);
+    result->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(&buf);
+    pq_sendfloat8(&buf, complex->x);
+    pq_sendfloat8(&buf, complex->y);
+    PG_RETURN_BYTEA_P(pq_endtypsend(&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