From: | Chapman Flack <chap(at)anastigmatix(dot)net> |
---|---|
To: | Alvaro Herrera <alvherre(at)2ndquadrant(dot)com> |
Cc: | Pavel Stehule <pavel(dot)stehule(at)gmail(dot)com>, Markus Winand <markus(dot)winand(at)winand(dot)at>, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us>, PostgreSQL Hackers <pgsql-hackers(at)postgresql(dot)org> |
Subject: | Re: House style for DocBook documentation? |
Date: | 2019-01-19 20:24:22 |
Message-ID: | 5C438776.9080103@anastigmatix.net |
Views: | Raw Message | Whole Thread | Download mbox | Resend email |
Thread: | |
Lists: | pgsql-hackers |
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
From | Date | Subject | |
---|---|---|---|
Next Message | Tom Lane | 2019-01-19 20:25:41 | Re: Changing SQL Inlining Behaviour (or...?) |
Previous Message | Michael Meskes | 2019-01-19 19:15:37 | Re: Thread-unsafe coding in ecpg |