Horton

Re: House style for DocBook documentation?

Alvaro Herrera <alvherre@2ndquadrant.com>

View thread View on postgr.es
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>
Date: 2019-01-21T14:12:22Z
Lists: pgsql-hackers 
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

Commits

  1. Improve documentation about our XML functionality

  2. Improve documentation about our XML functionality.

  3. Add volatile qualifier missed in commit 2e616dee9.

  4. Fix crash with old libxml2

  5. Fix minor deficiencies in XMLTABLE, xpath(), xmlexists()

  6. Fix the BY {REF,VALUE} clause of XMLEXISTS/XMLTABLE

  7. doc: Update README.links

  8. XPath fixes: