Prev Next xref

Specifying a General Cross Reference With in Web Site

Syntax
See Also
Deprecated 2006-07-07
Description
Tag
Heading
Linkingtext
Frame
Subheading
     Deprecated
Example
     Linking Text
     Headings
     Frames
     Subheadings
Reference

Syntax
$xref%tag%$$
 $xref%tag%heading%$$
 $xref%tag%heading%linkingtext%$$
 $xref%tag%heading%linkingtext%frame%$$
 $xref%tag%heading%subheading%linkingtext%frame%$$
See Also
href , mref , tref

Deprecated 2006-07-07
With the advent of the -noframe command line argument, the use of frames is being discouraged. For this reason, the entire xref command has been deprecated and it is suggested that you use the cref command instead.

Description
This command is used to specify a general cross reference link to another location with in the web site being generated by OMhelp.
     %tag%heading%subheading%linkingtext%frame%
 is a delimiter sequence and % can be any character that is not a letter. Leading and trailing white space in tag , heading , subheading , linkingtext , and frame is ignored. Thus is useful when the argument list the xref is long.

Tag
The value of tag specifies the destination cross reference tag for the link.

Heading
The value of heading specifies the destination heading for the link (within the section specified by tag ). If this heading is empty (or not present), the link is to the corresponding entire section specified by tag .

Linkingtext
The value of linkingtext specifies the text that the user selects for the link. If linkingtext is empty (or not present), tag is used for the linking text.

Frame
The value of frame specifies the frame number that is replaced by the corresponding to the link.
  1. If frame is present, it must be a valid frame number for the current section. In this case, heading must not be empty and the linking text is displayed in italic font.
  2. If frame is not present and the heading is empty, the entire window is replaced by the link.
  3. If frame is not present and the heading is not empty, frame number 1 is replaced by the link. In this case, the linking text is displayed in italic font.


Subheading
The value of subheading specifies the destination subheading for the link (within the section specified by tag and the heading specified by heading ). If subheading is present, heading must not be empty.

Deprecated
Previous versions of OMhelp specified subheadings as part of the heading argument. If subheading is not present, this still works for backward compatibility. To use this option, the value heading in the xref command must be the corresponding destination heading followed by a single period ('.') followed by the destination subheading.

Example
For the following input 
 
     $xref/head/$$
tag is equal to head, heading is not present, subheading is not present, linkingtext is not present, and frame is not present. Thus the linking text is head and the entire window is replaced by the link. You can see the effect by selecting the following link: head .

Linking Text
For the following input 
 
     $xref/head//OMhelp headings/$$
tag is equal to head, heading is empty, subheading is not present, linkingtext is equal to OMhelp headings, and frame is not present. You can see the effect by selecting the following link: OMhelp headings .

Headings
For the following input 
 
     $xref/head/Example Heading/example heading/$$
tag is equal to head, heading is equal to Example Heading, subheading is not present, linkingtext is equal to example heading, and frame is not present. Thus frame number 1 is replaced by the link and the linking text is in italic. You can see the effect by selecting the following link: example heading

Frames
For the following input 
 
     $xref/head/Example Heading/example heading/2/$$
tag is equal to head, heading is equal to Example Heading, subheading is not present, linkingtext is equal to example heading, and frame is equal to 2. Thus frame number 2 corresponds to the link and the linking text is in italic. You can see the effect of the xref command above by selecting the following link: example heading

For information about frames see Dividing A Section Into Frames.

Subheadings
The command below makes use of the fact that leading and trailing white space is ignored. For the following input 
 
     $xref/
          head/
          Example Subheading/
          Topic/
          the Topic example subheading/
          1
     /$$
tag is equal to head, heading is equal to Example Subheading subheading is equal to Topic, linkingtext is equal to the Topic example subheading, and frame is equal to one. You can see the effect of the xref command above by selecting the following link: the Topic example subheading

Reference
It is possible that there is no section with the specified cross reference tag and heading. A list of such cross reference tags is printed on stdout when omhelp is run. In this case, no linkage is attempted and the linking text is displayed in red.

White space characters in the heading and subheading are just delimiters between tokens when searching for the matching link. Thus you can split long headings and subheadings into multiple lines.
Input File: omh/xref.omh