Inserting Cross-References

Cross-references let you create automated links that are based on commands you provide. This lets you keep links consistent and change them in just one place by using the MadCap:xref style (or a class of it that you have created). Cross-references can also be used to convert online links to page number references when you are producing printed output. You can insert cross-references into content files.

In Contributor, cross-references can be added as links to other places in the same document. They cannot be added to other topics in a review package.

How to Insert a Cross-Reference

1. Open the content file.
2. In the XML Editor place your cursor where you want to insert the cross-reference.

3. Do one of the following, depending on the part of the user interface you are using:

   • Ribbon Select the Insert > Cross-Reference.
   • Keyboard Shortcut Press CTRL+SHIFT+R.
   • Local Toolbar In the local toolbar of the XML Editor, click .
   • Right-Click Right-click in the editor and select Insert > Cross-Reference. This context menu option is available only when your cursor is located in certain places in the editor (e.g., not in a drop-down effect).

   The Insert Cross-Reference dialog opens.

4. The Link to field displays bookmarks, headings, and other elements in the current file. Expand the appropriate section and select the element to which you want to link. If you select anything other than an existing bookmark, Contributor will insert a new bookmark at that destination in the file.

5. In the Cross-Reference Properties section, select the MadCap|xref style that you want to use for the cross-reference.

   Initially, you may see only the parent MadCap|xref style in the list. In the XRef Format area to the right, you can see the current format associated with that tag. Initially this format is as follows for the different mediums:

   • Default Medium {paratext}
   • Print Medium "{paratext}" {pageref}

   The command {paratext} means that the text of the paragraphed bookmark—or the text of the first paragraph found in the topic—will be displayed at that spot. The {pageref} command in the print medium format allows for context-sensitivity (see Creating Context-Sensitive Cross-References).

   You can: (1) use the parent MadCap|xref style with its current format, (2) use the parent MadCap|xref style and change the format to something else, (3) create a new class of the MadCap|xref style and provide a custom format for it, or (4) use a class that you have already created previously.

   It is a good idea to create classes because you may eventually want to use multiple kinds of cross-references. Each class that you create can be used to display cross-references in a different format. For more information see Creating Selectors and Styles and Stylesheets.

6. If you want to use the parent MadCap|xref style with its current format, or a class that you have created previously, click MadCap:xref or the name of the class, respectively.
7. If you want to use the parent MadCap|xref style but change the format, click MadCap:xref and then Edit. The Edit Cross-Reference Style Class dialog opens.
8. In the Stylesheet to modify field, select the appropriate stylesheet (if different from the one shown).
9. In the Enter format field, provide the format for the style. This format can be a combination of text that you type and automated commands that you select. You can select commands from the list by double-clicking them. They are then added to the "Enter format" field.

   b	Start bold text
   /b	End bold text
   bg	Start new background color
   /bg	End background color
   color	Start new text color
   /color	End text color
   default	Reset all font changes
   ext	File extension
   family	Start new font family
   /family	End font family
   file	File name, including extension
   filename	File name, without extension
   h1	Text of first heading 1 paragraph
   h2	Text of first heading 2 paragraph
   h3	Text of first heading 3 paragraph
   h4	Text of first heading 4 paragraph
   h5	Text of first heading 5 paragraph
   h6	Text of first heading 6 paragraph
   i	Start italic text
   /i	End italic text
   page	Page number
   pagecount	Page count
   pageref	Context-sensitive page reference
   paranum	The autonumber text of bookmarked paragraph.
   paranumonly	The autonumber only of bookmarked paragraph
   paratext	Text of bookmarked paragraph
   paraxml	Text and markup of bookmarked paragraph
   path	File path
   size	Start new font size
   /size	End font size
   sub	Start subscript text
   /sub	End subscript text
   sup	Start superscript text
   /sup	End superscript text
   title	Title of document
   u	Start underlined text
   /u	End underlined text
   url	File path, URL syntax
   [variable]	Available variables can be entered in the cross-reference format.

   Example If you want the cross-reference to include text (such as "For more information see"), simply type it in this field. You can also double-click any of the commands to add them to this field. For example, you might want to add the text of the first paragraph in the destination file to the cross-reference format. The command for this is {paratext}. Descriptions for each command are displayed in the list.

   Some commands include a start tag and an end tag. For example, if you want a portion of the cross-reference to be displayed in bold, you would place your cursor in the "Enter format" field where want to start the bold font and double-click b in the list below. Then place your cursor where you want the bold font to end and double-click /b from the list.

   So in the end, your cross-reference format might include a combination of text and multiple commands, such as:

   For more information see {b}{paratext}{/b}

   A format such as this one might display a link in the output like this:

   For more information see My Destination Topic

   For additional information and examples, see Cross-References.

10. Click OK.

11. (Optional) In the Target Frame field of the Insert Cross-Reference dialog, click the drop-down arrow to select the way the linked destination will open.

    • Page Default The destination file opens in the same window as the output window.
    • Parent Frame The destination file opens in the parent frame of the current topic while hiding that topic.
    • New Window The destination file opens in a new browser window.
    • Same Frame The destination file opens in the same window frame as the current topic.
    • Top Frame The destination file opens in the same output window, removing all other framesets. You might use this option, for example, if the destination topic has its own frameset.
    • Popup Window The destination file opens in a popup box on top of the current topic.

12. (Optional) In the Screen Tip field, you can type a phrase that will appear when the end user hovers over the cross-reference in the output. When you enter a screen tip, it is added as a <title> tag in the markup.

13. (Optional) In the Alternate Text field, type a phrase that describes what the element is about. This option should be used to increase accessibility for users who are unable to view an element. See Alt Text and Title Attributes.
14. Click OK. The cross-reference is added to the topic. You can change the appearance of the link (e.g., color, underline) by modifying the style (e.g., MadCap|xref or MadCap|xref.MyStyle) in the Stylesheet Editor.
15. Click to save your work.