pg.ddx.io pgsql-hackers@postgresql.org mailing list archive
help / color / mirror / Atom feedHouse style for DocBook documentation?
21+ messages / 5 participants
[nested] [flat]
* House style for DocBook documentation?
@ 2019-01-19 01:20 Chapman Flack <chap@anastigmatix.net>
0 siblings, 1 reply; 21+ messages in thread
From: Chapman Flack @ 2019-01-19 01:20 UTC (permalink / raw)
To: Pavel Stehule <pavel.stehule@gmail.com>; +Cc: Markus Winand <markus.winand@winand.at>; Alvaro Herrera <alvherre@2ndquadrant.com>; Tom Lane <tgl@sss.pgh.pa.us>; pgsql-hackers
Hi,
Is there, somewhere, a written-up "house style" for what DocBook 4.2
elements to use for which types of content in the manual?
In func.sgml I'm seeing what looks like a variety of examples, and
I'm not sure which ones to try to follow.
Thanks,
-Chap
^ permalink raw reply [nested|flat] 21+ messages in thread
* Re: House style for DocBook documentation?
@ 2019-01-19 13:35 Alvaro Herrera <alvherre@2ndquadrant.com>
parent: Chapman Flack <chap@anastigmatix.net>
0 siblings, 1 reply; 21+ messages in thread
From: Alvaro Herrera @ 2019-01-19 13:35 UTC (permalink / raw)
To: Chapman Flack <chap@anastigmatix.net>; +Cc: Pavel Stehule <pavel.stehule@gmail.com>; Markus Winand <markus.winand@winand.at>; Tom Lane <tgl@sss.pgh.pa.us>; pgsql-hackers
Hi
On 2019-Jan-18, Chapman Flack 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?
>
> In func.sgml I'm seeing what looks like a variety of examples, and
> I'm not sure which ones to try to follow.
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.
--
Álvaro Herrera https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
^ permalink raw reply [nested|flat] 21+ messages in thread
* Re: House style for DocBook documentation?
@ 2019-01-19 20:24 Chapman Flack <chap@anastigmatix.net>
parent: Alvaro Herrera <alvherre@2ndquadrant.com>
0 siblings, 2 replies; 21+ messages in thread
From: Chapman Flack @ 2019-01-19 20:24 UTC (permalink / raw)
To: 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>; 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
^ permalink raw reply [nested|flat] 21+ messages in thread
* Re: House style for DocBook documentation?
@ 2019-01-21 14:12 Alvaro Herrera <alvherre@2ndquadrant.com>
parent: Chapman Flack <chap@anastigmatix.net>
1 sibling, 1 reply; 21+ messages in thread
From: Alvaro Herrera @ 2019-01-21 14:12 UTC (permalink / raw)
To: Chapman Flack <chap@anastigmatix.net>; +Cc: Pavel Stehule <pavel.stehule@gmail.com>; Markus Winand <markus.winand@winand.at>; Tom Lane <tgl@sss.pgh.pa.us>; pgsql-hackers
On 2019-Jan-19, Chapman Flack wrote:
> 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.
I think these inconsistencies just stem from lack of a strong reviewer
hand on the topic. Let's change that?
> - 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.
I think the README.links was written in the SGML times; now that we're
in XML it may need to be reconsidered.
> (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.
Thanks,
--
Álvaro Herrera https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
^ permalink raw reply [nested|flat] 21+ messages in thread
* Re: House style for DocBook documentation?
@ 2019-01-21 16:46 Chapman Flack <chap@anastigmatix.net>
parent: Alvaro Herrera <alvherre@2ndquadrant.com>
0 siblings, 2 replies; 21+ messages in thread
From: Chapman Flack @ 2019-01-21 16:46 UTC (permalink / raw)
To: 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>; pgsql-hackers
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
^ permalink raw reply [nested|flat] 21+ messages in thread
* Re: House style for DocBook documentation?
@ 2019-01-21 17:07 Joshua D. Drake <jd@commandprompt.com>
parent: Chapman Flack <chap@anastigmatix.net>
1 sibling, 1 reply; 21+ messages in thread
From: Joshua D. Drake @ 2019-01-21 17:07 UTC (permalink / raw)
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>; pgsql-hackers
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. ***
^ permalink raw reply [nested|flat] 21+ messages in thread
* Re: House style for DocBook documentation?
@ 2019-01-21 18:01 Alvaro Herrera <alvherre@2ndquadrant.com>
parent: Chapman Flack <chap@anastigmatix.net>
1 sibling, 1 reply; 21+ messages in thread
From: Alvaro Herrera @ 2019-01-21 18:01 UTC (permalink / raw)
To: Chapman Flack <chap@anastigmatix.net>; +Cc: Pavel Stehule <pavel.stehule@gmail.com>; Markus Winand <markus.winand@winand.at>; Tom Lane <tgl@sss.pgh.pa.us>; pgsql-hackers
On 2019-Jan-21, Chapman Flack wrote:
> 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'.
Of course, the text would also be clickable, right? I think putting the
URL in a footnote is good in that case; it works both on screen and on
paper, which should alleviate JD's concerns.
> I wouldn't think it important to apply the same treatment when making HTML.
Right, only PDF.
--
Álvaro Herrera https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
^ permalink raw reply [nested|flat] 21+ messages in thread
* Re: House style for DocBook documentation?
@ 2019-01-21 18:11 Chapman Flack <chap@anastigmatix.net>
parent: Joshua D. Drake <jd@commandprompt.com>
0 siblings, 1 reply; 21+ messages in thread
From: Chapman Flack @ 2019-01-21 18:11 UTC (permalink / raw)
To: Joshua D. Drake <jd@commandprompt.com>; 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>; pgsql-hackers
On 01/21/19 12:07, Joshua D. Drake wrote:
> 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.
QR code in footnote (ducks and runs).
^ permalink raw reply [nested|flat] 21+ messages in thread
* Re: House style for DocBook documentation?
@ 2019-01-21 18:14 Joshua D. Drake <jd@commandprompt.com>
parent: Alvaro Herrera <alvherre@2ndquadrant.com>
0 siblings, 2 replies; 21+ messages in thread
From: Joshua D. Drake @ 2019-01-21 18:14 UTC (permalink / raw)
To: Alvaro Herrera <alvherre@2ndquadrant.com>; Chapman Flack <chap@anastigmatix.net>; +Cc: Pavel Stehule <pavel.stehule@gmail.com>; Markus Winand <markus.winand@winand.at>; Tom Lane <tgl@sss.pgh.pa.us>; pgsql-hackers
On 1/21/19 10:01 AM, Alvaro Herrera wrote:
> On 2019-Jan-21, Chapman Flack wrote:
>
>> 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'.
> Of course, the text would also be clickable, right? I think putting the
> URL in a footnote is good in that case; it works both on screen and on
> paper, which should alleviate JD's concerns.
Yeah I could see that. I thought about that but was wondering if it was
possible to auto cite?
JD
>
>> I wouldn't think it important to apply the same treatment when making HTML.
> Right, only PDF.
>
--
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. ***
^ permalink raw reply [nested|flat] 21+ messages in thread
* Re: House style for DocBook documentation?
@ 2019-01-21 18:15 Joshua D. Drake <jd@commandprompt.com>
parent: Chapman Flack <chap@anastigmatix.net>
0 siblings, 0 replies; 21+ messages in thread
From: Joshua D. Drake @ 2019-01-21 18:15 UTC (permalink / raw)
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>; pgsql-hackers
On 1/21/19 10:11 AM, Chapman Flack wrote:
> On 01/21/19 12:07, Joshua D. Drake wrote:
>> 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.
> QR code in footnote (ducks and runs).
Funny, although I know why you said that. I don't think it is that bad
of an idea. Everyone uses QR Codes now. Have a QR code that
automatically opens a page that lists all the expanded links based on
the page it is placed?
That is pretty cool but I am not sure if that is something that would
happen in this round.
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. ***
^ permalink raw reply [nested|flat] 21+ messages in thread
* Re: House style for DocBook documentation?
@ 2019-01-21 18:18 Alvaro Herrera <alvherre@2ndquadrant.com>
parent: Joshua D. Drake <jd@commandprompt.com>
1 sibling, 0 replies; 21+ messages in thread
From: Alvaro Herrera @ 2019-01-21 18:18 UTC (permalink / raw)
To: Joshua D. Drake <jd@commandprompt.com>; +Cc: Chapman Flack <chap@anastigmatix.net>; Pavel Stehule <pavel.stehule@gmail.com>; Markus Winand <markus.winand@winand.at>; Tom Lane <tgl@sss.pgh.pa.us>; pgsql-hackers
On 2019-Jan-21, Joshua D. Drake wrote:
> On 1/21/19 10:01 AM, Alvaro Herrera wrote:
> > On 2019-Jan-21, Chapman Flack wrote:
> >
> > > 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'.
> > Of course, the text would also be clickable, right? I think putting the
> > URL in a footnote is good in that case; it works both on screen and on
> > paper, which should alleviate JD's concerns.
>
> Yeah I could see that. I thought about that but was wondering if it was
> possible to auto cite?
Sorry, what do you mean with auto cite? Put all links at the end of the
section/chapter/book? That seems less usable to me (you have to find
out the page where the links appear, and make sure to print the right
pages)
--
Álvaro Herrera https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
^ permalink raw reply [nested|flat] 21+ messages in thread
* Re: House style for DocBook documentation?
@ 2019-01-21 19:19 Chapman Flack <chap@anastigmatix.net>
parent: Joshua D. Drake <jd@commandprompt.com>
1 sibling, 0 replies; 21+ messages in thread
From: Chapman Flack @ 2019-01-21 19:19 UTC (permalink / raw)
To: Joshua D. Drake <jd@commandprompt.com>; 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>; pgsql-hackers
On 01/21/19 13:14, Joshua D. Drake wrote:
>> Of course, the text would also be clickable, right? I think putting the
>> URL in a footnote is good in that case; it works both on screen and on
>> paper, which should alleviate JD's concerns.
>
> Yeah I could see that. I thought about that but was wondering if it was
It looks like the easiest way to integrate such a behavior into the
current Makefile would be not as a separate DocBook->DocBook transform
in advance, but simply by editing the existing stylesheet-fo.xsl that
produces the FO input for generating the PDF.
That would mean learning some FO, which I've wanted to do for a while,
but haven't yet, so it stops looking like something I might experiment
with this afternoon. OTOH, it could mean more flexibility in how the
presentation should look.
I note in passing that the google result [1] is nonempty....
-Chap
[1] https://www.google.com/search?q=xsl-fo+qr+code
^ permalink raw reply [nested|flat] 21+ messages in thread
* Re: House style for DocBook documentation?
@ 2019-01-25 14:01 Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
parent: Chapman Flack <chap@anastigmatix.net>
1 sibling, 1 reply; 21+ messages in thread
From: Peter Eisentraut @ 2019-01-25 14:01 UTC (permalink / raw)
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>; pgsql-hackers
On 19/01/2019 21:24, Chapman Flack 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)
External links already create footnotes in the PDF output. Is that
different from what you are saying?
--
Peter Eisentraut http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
^ permalink raw reply [nested|flat] 21+ messages in thread
* Re: House style for DocBook documentation?
@ 2019-01-25 14:37 Chapman Flack <chap@anastigmatix.net>
parent: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
0 siblings, 1 reply; 21+ messages in thread
From: Chapman Flack @ 2019-01-25 14:37 UTC (permalink / raw)
To: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>; 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>; pgsql-hackers
On 01/25/19 09:01, Peter Eisentraut wrote:
> On 19/01/2019 21:24, Chapman Flack 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)
>
> External links already create footnotes in the PDF output. Is that
> different from what you are saying?
That might, only, indicate that I was just thinking aloud in email and
had not gone and checked in PDF output to see how the links were handled.
Yes, it could very possibly indicate that.
If they are already processed that way, does that mean the
o Do not use text with <ulink> so the URL appears in printed output
in README.links should be considered obsolete, and removed even, and
doc authors should feel free to put link text in <ulink> without
hesitation?
Regards,
-Chap
^ permalink raw reply [nested|flat] 21+ messages in thread
* Re: House style for DocBook documentation?
@ 2019-01-26 08:31 Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
parent: Chapman Flack <chap@anastigmatix.net>
0 siblings, 1 reply; 21+ messages in thread
From: Peter Eisentraut @ 2019-01-26 08:31 UTC (permalink / raw)
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>; pgsql-hackers
On 25/01/2019 15:37, Chapman Flack wrote:
>> External links already create footnotes in the PDF output. Is that
>> different from what you are saying?
> That might, only, indicate that I was just thinking aloud in email and
> had not gone and checked in PDF output to see how the links were handled.
>
> Yes, it could very possibly indicate that.
>
> If they are already processed that way, does that mean the
>
> o Do not use text with <ulink> so the URL appears in printed output
>
> in README.links should be considered obsolete, and removed even, and
> doc authors should feel free to put link text in <ulink> without
> hesitation?
I think it's obsolete, yes.
--
Peter Eisentraut http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
^ permalink raw reply [nested|flat] 21+ messages in thread
* Re: House style for DocBook documentation?
@ 2019-02-15 16:31 Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
parent: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
0 siblings, 2 replies; 21+ messages in thread
From: Peter Eisentraut @ 2019-02-15 16:31 UTC (permalink / raw)
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>; pgsql-hackers
On 2019-01-26 09:31, Peter Eisentraut wrote:
> On 25/01/2019 15:37, Chapman Flack wrote:
>>> External links already create footnotes in the PDF output. Is that
>>> different from what you are saying?
>> That might, only, indicate that I was just thinking aloud in email and
>> had not gone and checked in PDF output to see how the links were handled.
>>
>> Yes, it could very possibly indicate that.
>>
>> If they are already processed that way, does that mean the
>>
>> o Do not use text with <ulink> so the URL appears in printed output
>>
>> in README.links should be considered obsolete, and removed even, and
>> doc authors should feel free to put link text in <ulink> without
>> hesitation?
>
> I think it's obsolete, yes.
Committed that change.
--
Peter Eisentraut http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
^ permalink raw reply [nested|flat] 21+ messages in thread
* Re: House style for DocBook documentation?
@ 2019-03-01 12:15 Ramanarayana <raam.soft@gmail.com>
parent: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
1 sibling, 0 replies; 21+ messages in thread
From: Ramanarayana @ 2019-03-01 12:15 UTC (permalink / raw)
To: Pavel Stehule <pavel.stehule@gmail.com>; +Cc: Chapman Flack <chap@anastigmatix.net>; Alvaro Herrera <alvherre@2ndquadrant.com>; Markus Winand <markus.winand@winand.at>; Tom Lane <tgl@sss.pgh.pa.us>; pgsql-hackers; Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
Hi,
I have tested bug fixes provided by all the patches. They are working
great. I found one minor issue
select * from xmltable('*' PASSING '<e>pre<!--c1--><?pi
arg?><![CDATA[&ent1]]><n2>&deep</n2>post</e>' COLUMNS x XML PATH '/');
The above query returns the xml. But there is an extra plus symbol at the
end
<e>pre<!--c1--><?pi arg?><![CDATA[&ent1]]><n2>&deep</n2>post</e>+
Regards,
Ram
^ permalink raw reply [nested|flat] 21+ messages in thread
* Re: House style for DocBook documentation?
@ 2019-03-08 04:04 Chapman Flack <chap@anastigmatix.net>
parent: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
1 sibling, 1 reply; 21+ messages in thread
From: Chapman Flack @ 2019-03-08 04:04 UTC (permalink / raw)
To: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>; 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>; pgsql-hackers
On 02/15/19 11:31, Peter Eisentraut wrote:
>> On 25/01/2019 15:37, Chapman Flack wrote:
>>> If they are already processed that way, does that mean the
>>>
>>> o Do not use text with <ulink> so the URL appears in printed output
>>>
>>> in README.links should be considered obsolete, and removed even, and
>>> doc authors should feel free to put link text in <ulink> without
>>> hesitation?
>
> Committed that change.
I only now noticed that probably this should also have been changed:
-o If you want to supply text, use <link>, else <xref>
+o If you want to supply text, use <link> or <ulink>, else <xref>
Regards,
-Chap
^ permalink raw reply [nested|flat] 21+ messages in thread
* Re: House style for DocBook documentation?
@ 2019-03-08 12:38 Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
parent: Chapman Flack <chap@anastigmatix.net>
0 siblings, 1 reply; 21+ messages in thread
From: Peter Eisentraut @ 2019-03-08 12:38 UTC (permalink / raw)
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>; pgsql-hackers
On 2019-03-08 05:04, Chapman Flack wrote:
> I only now noticed that probably this should also have been changed:
>
> -o If you want to supply text, use <link>, else <xref>
> +o If you want to supply text, use <link> or <ulink>, else <xref>
The choice of <link> vs <xref> is for internal links. For external
links you have to use <ulink>.
--
Peter Eisentraut http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
^ permalink raw reply [nested|flat] 21+ messages in thread
* Re: House style for DocBook documentation?
@ 2019-03-08 14:38 Chapman Flack <chap@anastigmatix.net>
parent: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
0 siblings, 1 reply; 21+ messages in thread
From: Chapman Flack @ 2019-03-08 14:38 UTC (permalink / raw)
To: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>; 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>; pgsql-hackers
On 3/8/19 7:38 AM, Peter Eisentraut wrote:
> On 2019-03-08 05:04, Chapman Flack wrote:
>> -o If you want to supply text, use <link>, else <xref>
>> +o If you want to supply text, use <link> or <ulink>, else <xref>
>
> The choice of <link> vs <xref> is for internal links. For external
> links you have to use <ulink>.
Understood, but I was thinking of the unintended message possibly
taken by a fast reader who wants to create an external link but also
wants to supply text. "I want to supply text! Is ulink not an option?"
Perhaps:
o For an internal link, use <link> if you will supply text, else <xref>
o For an external link, use <ulink> with or without link text
-Chap
^ permalink raw reply [nested|flat] 21+ messages in thread
* Re: House style for DocBook documentation?
@ 2019-03-29 12:37 Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
parent: Chapman Flack <chap@anastigmatix.net>
0 siblings, 0 replies; 21+ messages in thread
From: Peter Eisentraut @ 2019-03-29 12:37 UTC (permalink / raw)
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>; pgsql-hackers
On 2019-03-08 15:38, Chapman Flack wrote:
> Perhaps:
>
> o For an internal link, use <link> if you will supply text, else <xref>
> o For an external link, use <ulink> with or without link text
I have pushed an update to this effect.
--
Peter Eisentraut http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
^ permalink raw reply [nested|flat] 21+ messages in thread
end of thread, other threads:[~2019-03-29 12:37 UTC | newest]
Thread overview: 21+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2019-01-19 01:20 House style for DocBook documentation? Chapman Flack <chap@anastigmatix.net>
2019-01-19 13:35 ` Alvaro Herrera <alvherre@2ndquadrant.com>
2019-01-19 20:24 ` Chapman Flack <chap@anastigmatix.net>
2019-01-21 14:12 ` Alvaro Herrera <alvherre@2ndquadrant.com>
2019-01-21 16:46 ` Chapman Flack <chap@anastigmatix.net>
2019-01-21 17:07 ` Joshua D. Drake <jd@commandprompt.com>
2019-01-21 18:11 ` Chapman Flack <chap@anastigmatix.net>
2019-01-21 18:15 ` Joshua D. Drake <jd@commandprompt.com>
2019-01-21 18:01 ` Alvaro Herrera <alvherre@2ndquadrant.com>
2019-01-21 18:14 ` Joshua D. Drake <jd@commandprompt.com>
2019-01-21 18:18 ` Alvaro Herrera <alvherre@2ndquadrant.com>
2019-01-21 19:19 ` Chapman Flack <chap@anastigmatix.net>
2019-01-25 14:01 ` Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
2019-01-25 14:37 ` Chapman Flack <chap@anastigmatix.net>
2019-01-26 08:31 ` Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
2019-02-15 16:31 ` Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
2019-03-01 12:15 ` Ramanarayana <raam.soft@gmail.com>
2019-03-08 04:04 ` Chapman Flack <chap@anastigmatix.net>
2019-03-08 12:38 ` Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
2019-03-08 14:38 ` Chapman Flack <chap@anastigmatix.net>
2019-03-29 12:37 ` Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
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