Subject: Re: House style for DocBook documentation?
To: Chapman Flack <chap@anastigmatix.net>,
 Alvaro Herrera <alvherre@2ndquadrant.com>
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>
References: <201901211412.64zmyrp6iith@alvherre.pgsql>
 <5C45F74D.9040908@anastigmatix.net>
From: "Joshua D. Drake" <jd@commandprompt.com>
Organization: Command Prompt, Inc.
Message-ID: <9aac3a5d-3268-a247-513a-8291a1a44541@commandprompt.com>
Date: Mon, 21 Jan 2019 09:07:56 -0800
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101
 Thunderbird/60.2.1
MIME-Version: 1.0
In-Reply-To: <5C45F74D.9040908@anastigmatix.net>
Content-Type: text/plain; charset=windows-1252; format=flowed
Content-Transfer-Encoding: 7bit
Content-Language: en-US
Precedence: bulk

On 1/21/19 8:46 AM, Chapman Flack wrote:
> 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).

I don't think that is a good idea. PDFs have had the ability to embed 
hyperlinks under descriptive text for years. If we are going to expand 
links for printed output, we should have a specific build / modification 
to the make file for printed output. I also wonder if we are trying to 
solve the 1% problem here. Who is really going to "print" our docs? If 
they do print the docs, they are likely not going to "type in" a long 
URL. They are going to go online (or to the PDF) and click the link that 
they saw within the printed page.

JD

-- 
Command Prompt, Inc. || http://the.postgres.company/ || @cmdpromptinc
PostgreSQL centered full stack support, consulting and development.
Advocate: @amplifypostgres || Learn and Network: https://postgresconf.org
***  A fault and talent of mine is to tell it exactly how it is.  ***