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
