Date: Mon, 21 Jan 2019 11:12:22 -0300
From: Alvaro Herrera <alvherre@2ndquadrant.com>
To: Chapman Flack <chap@anastigmatix.net>
Cc: Pavel Stehule <pavel.stehule@gmail.com>,
	Markus Winand <markus.winand@winand.at>,
	Tom Lane <tgl@sss.pgh.pa.us>,
	PostgreSQL Hackers <pgsql-hackers@postgresql.org>
Subject: Re: House style for DocBook documentation?
Message-ID: <201901211412.64zmyrp6iith@alvherre.pgsql>
MIME-Version: 1.0
Content-Type: text/plain; charset=iso-8859-1
Content-Disposition: inline
Content-Transfer-Encoding: 8bit
In-Reply-To: <5C438776.9080103@anastigmatix.net>
User-Agent: NeoMutt/20180716-1013-2c1e88
Precedence: bulk

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