From: Chapman Flack <chap@anastigmatix.net>
To: Alvaro Herrera <alvherre@2ndquadrant.com>
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: Sat, 19 Jan 2019 15:24:22 -0500
Message-ID: <5C438776.9080103@anastigmatix.net> (raw)
In-Reply-To: <201901191335.kbjzsoefmkoa@alvherre.pgsql>
References: <201901191335.kbjzsoefmkoa@alvherre.pgsql>
Hi,
On 01/19/19 08:35, Alvaro Herrera wrote:
>> Is there, somewhere, a written-up "house style" for what DocBook 4.2
>> elements to use for which types of content in the manual?
>> ...
> I don't think we do. I'd suggest to come up with something and then see
> if it makes sense to patch the docs to apply it regularly.
I think my ambition at the moment is just to complete a particular
addition to func.sgml and do so as consistently as I can manage with
what's there now.
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.
- 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.
(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)
-Chap
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: chap@anastigmatix.net, alvherre@2ndquadrant.com, pavel.stehule@gmail.com, markus.winand@winand.at, tgl@sss.pgh.pa.us
Subject: Re: House style for DocBook documentation?
In-Reply-To: <5C438776.9080103@anastigmatix.net>
* 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