Subject: Re: House style for DocBook documentation?
To: Alvaro Herrera <alvherre@2ndquadrant.com>
References: <201901211412.64zmyrp6iith@alvherre.pgsql>
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>
From: Chapman Flack <chap@anastigmatix.net>
Message-ID: <5C45F74D.9040908@anastigmatix.net>
Date: Mon, 21 Jan 2019 11:46:05 -0500
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:38.0) Gecko/20100101
 Thunderbird/38.7.0
MIME-Version: 1.0
In-Reply-To: <201901211412.64zmyrp6iith@alvherre.pgsql>
Content-Type: text/plain; charset=windows-1252
Content-Transfer-Encoding: 7bit
Precedence: bulk

On 01/21/19 09:12, Alvaro Herrera wrote:

>> (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.

Well, "consistent" what I was half-thinking about, FSVO "consistent".

For me, if I'm looking at an online document, I would prefer to see
the descriptive text of the link, rather than a long jaggy URL. If I
want to see the URL, I can hover over it, and if I want to go there,
I can click it.

But the point's well taken that in /printed output/, that's of no use.
Which is, in a sense, an inconsistency: in one format, you can follow the
links, while in another, you're out of luck.

Maybe a simpler transform for printed output, rather than collecting
all URLs into one section at the back, would just be to follow any
<ulink> that has link text with a <footnote> containing the same ulink
without the link text, so it shows the URL, and that would be right at
the bottom of the same 'page'.

That'd be an introductory XSL exercise....

In practice, applying such a transform "for printed output" would
probably mean applying it when generating PDF output, which of course
can also be viewed online (and probably most often is, these days).

So preserving the original ulink run into the text is still of use,
in a PDF viewer that can follow links, but adding the footnote ensures
that an actual hard copy is still usable.

I wouldn't think it important to apply the same treatment when making HTML.
So maybe the right value of "consistent" is the one that comes from
listing out the various output formats and specifying the right
transformation to be applied to each one.

(Now wonders if there's a way to do the same transform into HTML while
styling the footnote and marker to hide behind @media print....)

Regards,
-Chap