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
---------------------------(end of broadcast)--------------------------- TIP 6: Have you searched our list archives?
http://archives.postgresql.org
