Skip site navigation (1) Skip section navigation (2)

xref, link, and command

From: Michael Glaesemann <grzm(at)myrealbox(dot)com>
To: pgsql-docs(at)postgresql(dot)org
Subject: xref, link, and command
Date: 2004-05-31 01:18:53
Message-ID: (view raw, whole thread or download thread mbox)
Lists: pgsql-docs
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

pgsql-docs by date

Next:From: Halley Pacheco de OliveiraDate: 2004-06-05 13:39:15
Subject: to_ascii function
Previous:From: Bruce MomjianDate: 2004-05-24 15:14:50
Subject: Re: Updated Russian translation of FAQ

Privacy Policy | About PostgreSQL
Copyright © 1996-2017 The PostgreSQL Global Development Group