Cross Referencing Other Documentation
In many circumstances you may want to create a link from one document to another. This can be done using GNOME's virtual filesystem layer. You use a specific Uniform Resource Identifier (URI) scheme to identify the type of documentation. There are different schemas which tell Yelp what type of document the you are referencing.
- 7.1. Uniform Resource Identifier
- 7.2. GNOME Documentation
- 7.3. Man and Info Pages
- 7.4. Web Pages
7.1. Uniform Resource Identifier
The Uniform Resource Identifier (URI) is made up of three parts: the schema, the document and the id. The schema declares the type of document. Some of the well known schemas are: http://, ftp://, file://. There are three specific schemas identifying documentation in GNOME 2. The schema ghelp: identifies GNOME documentation. The schema man: is used to reference man pages and the schema info: identifies info pages. Yelp only uses the schemas ghelp:, man: and info: to cross reference documentation you must use one of those three schemas.
The second part of the URI is the document. This is really the path to the document and identifying the document itself. You can either give the full path to the document on the computer, give the filename of the document, or just give the appid. It is not recommended to use the full path of the document to reference documentation. This will lead to broken links and heartaches. You should always either use the name of the document (e.g. gedit.xml) or use the appid to reference the main documentation (e.g. gedit).
The appid is the way the GNOME build system identifies applications. The appid is unique, but sometimes it is hard to deduce the appid. The appid is typically the name of the module in SVN. An example is the appid for the GNOME Terminal is gnome-terminal and its module name in SVN is also gnome-terminal. For some applications this rule of thumb does not hold. An example is the appid for the Stock Ticker is gtik2_applet2, but its module name in SVN is gtik. If you are having trouble figuring out the appid of an application ask the maintainer of the program.
The third part of the URI is the id. The id is the unique DocBook id made for every section. For more information on section ids see Section 5.2 ― Section IDs. The id is optional, but will let you choose where in the document the reader will look instead of placing the reader at the table of contents. It is recommended to use ids in the URI to accurately direct the reader to a specific portion of the document.
The three parts of the URI are put together to cross reference documentation in GNOME. The URI is formed by placing the schema first, followed by the appid or filename of the document. A question mark is placed after the appid, but before the section id. Then the section id is put after the question mark. The complete URI looks like:
ghelp:gedit?intro
7.2. GNOME Documentation
Adding a link to a different GNOME help document is not hard. This is done using the “ghelp:” URI scheme. This works for documents which are shipped as XML. To cross reference another GNOME document, use:
<ulink type="help" url="ghelp:user-guide?gosbasic-2">text</ulink>
To link within the current document, you need only specify the section id you wish to link to, but the DocBook syntax is different. To create a link that displays the section number and name, use:
<xref linkend="intro" />
<link linkend="intro">text</link>
7.3. Man and Info Pages
Adding a link to a manpage in a GNOME document is done using the “man:” URI scheme. To cross reference a manpage, use:
<ulink type="help" url="man:foo">text</ulink>
Adding a link to an infopage in a GNOME document is done using the “info:” URI scheme. To cross reference a manpage, use:
<ulink type="help" url="info:foo">text</ulink>