Обсуждение: [DOCS] Questionable tag usage
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: <para> Specifies the configuration file for <xref linkend="auth-username-maps"> user name mapping (customarily called <filename>pg_ident.conf</>). This parameter can only be set at server start. </para> 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 diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml index 30dd54c..1707d40 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -532,10 +532,10 @@ include_dir 'conf.d' </term> <listitem> <para> - Specifies the configuration file for - <xref linkend="auth-username-maps"> user name mapping - (customarily called <filename>pg_ident.conf</>). - This parameter can only be set at server start. + Specifies the configuration file + for <link linkend="auth-username-maps">user name mapping</link> + (customarily called <filename>pg_ident.conf</>). This parameter can + only be set at server start. </para> </listitem> </varlistentry>
Some general notes to the discussion about <xref> vs. <link> rendering in the new toolchain:
(1) There is a general distinction in the meaning of the two elements: <xref> is an internal link with validation semantic whereas <link> is an external link to any URL. See: http://doccookbook.sourceforge.net/html/en/dbc.markup.xref-vs-link.html
(2) The rendering of <xref> 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
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: <para> Specifies the configuration file for <xref linkend="auth-username-maps"> user name mapping (customarily called <filename>pg_ident.conf</>). This parameter can only be set at server start. </para> 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
On Wed, Jan 11, 2017 at 3:46 AM, Jürgen Purtz <juergen@purtz.de> wrote: > (1) There is a general distinction in the meaning of the two elements: > <xref> is an internal link with validation semantic whereas <link> is an > external link to any URL. See: > http://doccookbook.sourceforge.net/html/en/dbc.markup.xref-vs-link.html Eh, we use both <link> and <xref> for internal links and surely want both to be validated. If that's no longer happening I don't think it will be long before it bites us. -- Robert Haas EnterpriseDB: http://www.enterprisedb.com The Enterprise PostgreSQL Company
Robert Haas <robertmhaas@gmail.com> writes: > On Wed, Jan 11, 2017 at 3:46 AM, Jürgen Purtz <juergen@purtz.de> wrote: >> (1) There is a general distinction in the meaning of the two elements: >> <xref> is an internal link with validation semantic whereas <link> is an >> external link to any URL. See: >> http://doccookbook.sourceforge.net/html/en/dbc.markup.xref-vs-link.html > Eh, we use both <link> and <xref> for internal links and surely want > both to be validated. If that's no longer happening I don't think it > will be long before it bites us. I think that is talking about something different, namely the difference between linkend and href properties. linkend points to a tag in the current document, and AFAIK it behaves the same in <link> or <xref>. href is used for external links. The author of the cited page may believe that <link linkend=...> is bad style, but he doesn't say that in so many words, and even if he did I'm not sure I would agree. regards, tom lane