From: Jürgen Purtz <juergen@purtz.de>
To: pgsql-docs@lists.postgresql.org
Subject: Re: DocBook 5.2
Date: Mon, 5 Sep 2022 12:23:23 +0200
Message-ID: <ae14eca5-f57c-2db2-42ce-258bab3c6806@purtz.de> (raw)
In-Reply-To: <D44C94E6-CA9F-4437-AD7A-443963A1615E@yesql.se>
References: <20220904153904.cr47zyoh5dfuctev@alvherre.pgsql>
<e78443af-5fb2-bf58-b658-6d3605953c39@purtz.de>
<D44C94E6-CA9F-4437-AD7A-443963A1615E@yesql.se>
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.
inline patch 1: doc/src/sgml/xtypes.sgml (+17/-17 lines) download inline-1.patchdiff --git a/doc/src/sgml/xtypes.sgml b/doc/src/sgml/xtypes.sgmlindex 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
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-docs@postgresql.org
Cc: juergen@purtz.de, pgsql-docs@lists.postgresql.org
Subject: Re: DocBook 5.2
In-Reply-To: <ae14eca5-f57c-2db2-42ce-258bab3c6806@purtz.de>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox