X-Original-To: pgsql-docs-postgresql.org@localhost.postgresql.org
Received: from localhost (unknown [200.46.204.2])
	by svr1.postgresql.org (Postfix) with ESMTP id 881EED1CD7E
	for <pgsql-docs-postgresql.org@localhost.postgresql.org>;
	Sun, 30 May 2004 22:19:02 -0300 (ADT)
Received: from svr1.postgresql.org ([200.46.204.71])
	by localhost (neptune.hub.org [200.46.204.2]) (amavisd-new, port 10024)
	with ESMTP id 83623-04
	for <pgsql-docs-postgresql.org@localhost.postgresql.org>;
	Sun, 30 May 2004 22:19:04 -0300 (ADT)
Received: from smtp-send.myrealbox.com (smtp-send.myrealbox.com
	[192.108.102.143])
	by svr1.postgresql.org (Postfix) with ESMTP id 566DFD1CCCC
	for <pgsql-docs@postgresql.org>; Sun, 30 May 2004 22:18:59 -0300 (ADT)
Received: from [172.16.1.104] glaesema [61.197.227.146]
	by smtp-send.myrealbox.com with NetMail SMTP Agent $Revision: 3.87 $ on
	Novell NetWare; Sun, 30 May 2004 19:19:10 -0600
Mime-Version: 1.0 (Apple Message framework v618)
Content-Transfer-Encoding: 7bit
Message-Id: <7ABFBBB1-B2A0-11D8-9821-000A95C88220@myrealbox.com>
Content-Type: text/plain; charset=US-ASCII; format=flowed
To: pgsql-docs@postgresql.org
From: Michael Glaesemann <grzm@myrealbox.com>
Subject: xref, link, and command
Date: Mon, 31 May 2004 10:18:53 +0900
X-Mailer: Apple Mail (2.618)
X-Virus-Scanned: by amavisd-new at postgresql.org
X-Spam-Status: No, hits=0.0 tagged_above=0.0 required=5.0 tests=
X-Spam-Level: 
X-Archive-Number: 200405/23
X-Sequence-Number: 2398

I've been working through the docs, looking for places to place cross 
references and add index entries. In doing so, I hope to connect some 
of the <command> references to their reference page.

Here's an example:

Throughout this chapter, it can be useful to look at the reference
page of the <command>CREATE FUNCTION</> command

I'd like to link CREATE FUNCTION to the CREATE FUNCTION reference page

As I understand it, we use <xref> or <link> tags. <xref> has the 
advantage of automatically generating the link text, which in the case 
of the reference pages is very useful: if the command changes, the link 
text changes as well. However, if I understand docbook correctly, we 
cannot nest <xref> within <command>.

However, we can nest <link> within <command> (and vice versa). This is 
only an issue if it's desirable to include the semantic meaning of 
<command>. I can see how this is useful.

One alternative would be to use use <link>  when the context refers to 
the command itself, and <xref> when it refers to the reference page, 
perhaps rewriting the phrase to refer the reference page. This has the 
advantage of moving towards more flexible documentation (not that the 
commands change all that often).

Does this sound reasonable?

Michael Glaesemann
grzm myrealbox com