Re: [DOCS] Questionable tag usage
Some general notes to the discussion about vs. rendering in the new toolchain: (1) There is a general distinction in the *meaning* of the two elements: is an internal link with validation semantic whereas is an external link to any URL. See: http://doccookbook.sourceforge.net/html/en/dbc.markup.xref-vs-link.html (2) The *rendering* of can be customized via its xrefstyle-attribute. It switches numbering, title, page number, ... on or off, see: http://doccookbook.sourceforge.net/html/en/dbc.markup.xref.html#sec.markup.xref.xrefstyle . This feature is available per element usage or as a default behaviour, which is defined in the language file of the xslt process (eg: en.xml). (3) The option to render the xref-output as described in (2) is available since docbook 4.3. Unfortunately we use docbook 4.2. To overcome this shortage we can use the following - more or less cumbersome - workaround: http://www.sagehill.net/docbookxsl/CustomXrefs.html#RoleNotXrefstyle and http://www.sagehill.net/docbookxsl/CustomGentext.html . Kind regards, Jürgen Purtz On 05.01.2017 00:40, Tatsuo Ishii wrote: In: https://www.postgresql.org/docs/devel/static/runtime-config-file-locations.html --- ident_file (string) Specifies the configuration file for Section 20.2, “User Name Maps” user name mapping (customarily called pg_ident.conf). This parameter can only be set at server start. --- "Specifies the configuration file for Section 20.2, “User Name Maps” user name mapping" looks pretty strange to me because a raw section name appears. This is due to the corresponding SGML coding: Specifies the configuration file for user name mapping (customarily called pg_ident.conf). This parameter can only be set at server start. Shouldn't we use a link tag instead of the xref tag here? Attached is a patch to fix this. Best regards, -- Tatsuo Ishii SRA OSS, Inc. Japan English: http://www.sraoss.co.jp/index_en.php Japanese:http://www.sraoss.co.jp
Re: [DOCS] [HACKERS] Questionable tag usage
On 1/4/17 11:50 PM, Tom Lane wrote: > Anyway, bottom line is I'm not terribly excited about fixing just this > one place. I think we need to decide whether we like the new more-verbose > output for links. If we don't, we need to fix the markup rules to not do > that. If we do, there are a lot of places that need adjustment to be less > duplicative, and we should try to be somewhat systematic about fixing > them. We can turn off the new link appearance and change it back to the old one. We had previously speculated that this change might be awkward in some cases, but without any concrete cases. If we have concrete cases, we can change it. -- Peter Eisentraut http://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services -- Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs
Re: [DOCS] [HACKERS] Questionable tag usage
On 1/6/17 8:56 AM, Magnus Hagander wrote: > You could argue that nobody reads the PG docs on dead trees anymore > and we should embrace the hyperlink style with enthusiasm. I wouldn't > be against that personally, but there are a lot of places to change if > we decide that parenthetical "(see Section M.N)" hotlinks are pass > ,Ai (B. > I don't think there are a lto of people who use dead tree editions > anymore, but they certainly do exist. A lot of people use the PDFs > though, particularly for offline reading or loading them in ebook > readers. So it still has to be workable there. And there are man pages as the canonical example of why environments without full hyperlinking are still useful. Also, I'm not fond of the style of writing where random words are hyperlinks, because then there is no context of what the link is for. Is it more information, is it the canonical definition, is a glossary entry, a link to Wikipedia, is it essential that I read the linked-to material to be able to understand the current material, etc. And for mostly technical reasons, the links sometimes point into the middle of a section, so it's hard to find what the link was supposed to help you with, even more so if the target section was rewritten since the link was placed. The xref style of linking makes the relationship between both ends of the link more explicit and keeps up with changes in either side of the link better. -- Peter Eisentraut http://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services -- Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs
