Re: House style for DocBook documentation?

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