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
Attachments:
config.difftext/x-patch; charset=us-asciiDownload+4-4
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
Show quoted text
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:<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
--
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs
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
--
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs