From: Alvaro Herrera <alvherre@2ndquadrant.com>
To: Chapman Flack <chap@anastigmatix.net>
Cc: Pavel Stehule <pavel.stehule@gmail.com>
Cc: Markus Winand <markus.winand@winand.at>
Cc: Tom Lane <tgl@sss.pgh.pa.us>
Cc: PostgreSQL Hackers <pgsql-hackers@postgresql.org>
Subject: Re: House style for DocBook documentation?
Date: Mon, 21 Jan 2019 11:12:22 -0300
Message-ID: <201901211412.64zmyrp6iith@alvherre.pgsql> (raw)
In-Reply-To: <5C438776.9080103@anastigmatix.net>
On 2019-Jan-19, Chapman Flack wrote:
> I have noticed a couple of things:
>
> - 'SQL' is often marked up as <acronym>SQL</acronym>, but far from always.
>
> - no such markup is applied to 'JSON' or 'XML' at all, at least
> not in func.sgml.
I think these inconsistencies just stem from lack of a strong reviewer
hand on the topic. Let's change that?
> - there is a README.links with this guideline:
>
> o Do not use text with <ulink> so the URL appears in printed output
>
> but a grep -r in doc/src/sgml turns up 112 uses that observe the
> guideline, and 147 that supply link text.
I think the README.links was written in the SGML times; now that we're
in XML it may need to be reconsidered.
> (thinks to self half-seriously about an XSL transform for generating
> printed output that could preserve link-texted links, add raised numbers,
> and produce a numbered URLs section at the back)
Well, if you have the time and inclination, and you think such changes
are improvements, feel free to propose them. Do keep in mind we have a
number of outputs that would be good to keep consistent.
Thanks,
--
Álvaro Herrera https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
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-hackers@postgresql.org
Cc: alvherre@2ndquadrant.com, chap@anastigmatix.net, pavel.stehule@gmail.com, markus.winand@winand.at, tgl@sss.pgh.pa.us
Subject: Re: House style for DocBook documentation?
In-Reply-To: <201901211412.64zmyrp6iith@alvherre.pgsql>
* 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