Re: House style for DocBook documentation?
On 2019-03-08 15:38, Chapman Flack wrote: > Perhaps: > > o For an internal link, use if you will supply text, else > o For an external link, use 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
Re: House style for DocBook documentation?
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 , else >> +o If you want to supply text, use or , else > > The choice of vs is for internal links. For external > links you have to use . 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 if you will supply text, else o For an external link, use with or without link text -Chap
Re: House style for DocBook documentation?
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 , else > +o If you want to supply text, use or , else The choice of vs is for internal links. For external links you have to use . -- Peter Eisentraut http://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: House style for DocBook documentation?
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 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 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 , else +o If you want to supply text, use or , else Regards, -Chap
Re: House style for DocBook documentation?
Hi,
I have tested bug fixes provided by all the patches. They are working
great. I found one minor issue
select * from xmltable('*' PASSING 'predeeppost' COLUMNS x XML PATH '/');
The above query returns the xml. But there is an extra plus symbol at the
end
predeeppost+
Regards,
Ram
Re: House style for DocBook documentation?
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 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 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
Re: House style for DocBook documentation?
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 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 without > hesitation? I think it's obsolete, yes. -- Peter Eisentraut http://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: House style for DocBook documentation?
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 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 without hesitation? Regards, -Chap
Re: House style for DocBook documentation?
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
Re: House style for DocBook documentation?
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
Re: House style for DocBook documentation?
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 > > > that has link text with a 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 Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: House style for DocBook documentation?
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. ***
Re: House style for DocBook documentation?
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 that has link text with a 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. ***
Re: House style for DocBook documentation?
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).
Re: House style for DocBook documentation?
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 > that has link text with a 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 Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
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 that has link text with a 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. ***
Re: House style for DocBook documentation?
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 that has link text with a 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
Re: House style for DocBook documentation?
On 2019-Jan-19, Chapman Flack wrote: > I have noticed a couple of things: > > - 'SQL' is often marked up as SQL, 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 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 Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: House style for DocBook documentation?
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 SQL, 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 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
Re: House style for DocBook documentation?
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 Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
House style for DocBook documentation?
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
