public inbox for [email protected]  

help / color / mirror / Atom feed

From: Michael Glaesemann <[email protected]>
To: [email protected]
Subject: xref, link, and command
Date: Mon, 31 May 2004 10:18:53 +0900
Message-ID: <[email protected]> (raw)

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

reply

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Reply to all the recipients using the --to and --cc options:
  reply via email

  To: [email protected]
  Cc: [email protected]
  Subject: Re: xref, link, and command
  In-Reply-To: <[email protected]>

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox