Editing Cross-Reference Style Formats

Outputs Supported

You can change the style format used for cross-references. For example, instead of "See My Topic," you might want cross-references to display "For more information see My Topic." You can edit cross-reference style formats at the point where a cross-reference is inserted, or from a stylesheet.

How to Edit a Cross-Reference Style Format at the Point of Insertion

1. Open the content file.
2. In the XML Editor, click inside the link.
3. At the top of the XML Editor, right-click the span bar representing the link. For example, hyperlink span bars have an "a" label, and cross-reference span bars have a "MadCap:xref" label. When you click on the link in the topic, the appropriate span bar at the top of the XML Editor will change color to indicate that it goes with the link. If your span bars are not turned on, click in the local toolbar of the XML Editor.
4. Select Edit Cross-Reference. The Insert Cross-Reference dialog opens.

5. In the Cross-Reference Properties section, select the MadCap:xref style you want to edit.

   MadCap:xref is the parent style and default selection, but in the Stylesheet Editor you can create classes under that style if you want a variety of looks for cross-references.

6. Click Edit. The Edit Cross-Reference Style Class dialog opens.
7. (Optional) In the Stylesheet to modify field, you can select the appropriate stylesheet (if different from the one shown). If you are using a primary stylesheet (recommended), only that stylesheet is shown in this field. If you are not using a primary stylesheet, the stylesheet that you select needs to be applied to the topic in which you are inserting the cross-reference. See Associating Primary Stylesheets With All Files and Associating Stylesheets Locally With Specific Files

8. In the Enter format field, provide the format for the class. 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.

   Command	Description
   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.

   Note For print-based and EPUB output you can create context-sensitive cross-references, which automatically change the text in the link based on the relationship of the cross-reference and the target location. See Creating Context-Sensitive Cross-References and Editing Text for Context-Sensitive Cross-References.

   Note The default format for the primary cross-reference style (MadCap|xref) is already set up to create context-sensitive cross-references. If you have been using the old default cross-reference formats and want to continue using them, you can edit the MadCap|xref style and replace the new formats with the older ones. The old cross-reference format for the default style medium is See "{paratext}". The old format for the print medium is See "{paratext}" on page {page}.

   If you have already edited the MadCap|xref style in a stylesheet before upgrading to a new version, your custom format will not be affected. You will only see a change if you have never changed the default format from older versions.

9. Click OK.
10. Click to save your work.
11. (Optional) To make sure other cross-references display the new format, you can update the cross-references in a topic (Tools > Update Cross-References). However, all of the cross-references will be updated automatically when you generate the output, so this is not a mandatory task.

How to Edit a Cross-Reference Style Format From a Stylesheet

1. From the Content Explorer, open the stylesheet that you want to modify.

2. Complete one of the following sets of steps, depending on whether you want to use the Simplified view or Advanced view in the Stylesheet Editor.

   • Simplified The Simplified view displays styles in a grid view and is often best for brand new users.

     This view provides an easy way to apply properties to styles, with format options available from a toolbar and dialogs (similar to the way one would use an interface such as Microsoft Word). In some cases, only the most common property options are available in the Simplified view (e.g., font, letter/word spacing, paragraph alignment/indentation, autonumbering format, borders, background). One advantage of the Simplified view is that you can apply a property to multiple styles at the same time. You can also click a check box to hide the properties in the editor, allowing you to see only the styles.

   • Advanced The Advanced view displays styles in a tree structure, and despite the name, is user friendly for authors of all levels.

     For the properties, you can toggle between a grouped display and an alphabetical display. The Advanced view of the Stylesheet Editor lets you edit more settings than are available in the Simplified view. In addition, the Advanced view lets you see and apply settings to multiple mediums and media queries at the same time.

   Warning Mediums can be used if you want to use one group of settings for online output types and another group of settings for print-based output types. For example, you might use the default medium for your online outputs and the print medium for your print outputs.  From the Medium drop-down in the Stylesheet Editor, make sure the proper medium is selected before you begin. In the Advanced view, you can open multiple mediums at once; you just need to look at the title at the top of the medium pane and make sure you are working in the correct one. If you are not using stylesheet mediums for your different outputs or if you want all mediums to have the same settings, just leave the medium set to default and continue. Please note that Flare remembers the last medium that you used when working in the stylesheet, so it may or may not be the one that you want to use the next time around. See Mediums and Media Queries.

   If Using Simplified View

   1. In the local toolbar, make sure the first button displays (which means that the Simplified view is currently shown in the editor). If the button displays instead, then click it.
   2. In the upper-left corner of the editor, click in the drop-down field and select .
   3. On the left side of the Stylesheet Editor, select the MadCap|xref tag (or a class of it) that you want to edit.
   4. In the local toolbar of the editor, click . The Properties dialog opens.
   5. Select the Format tab.
   6. Click the Edit button. The Cross-Reference Format dialog opens.

   7. In the Enter format field, provide the format for the class. 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.

      Command	Description
      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.

      Note For print-based and EPUB output you can create context-sensitive cross-references, which automatically change the text in the link based on the relationship of the cross-reference and the target location. See Creating Context-Sensitive Cross-References and Editing Text for Context-Sensitive Cross-References.

      Note The default format for the primary cross-reference style (MadCap|xref) is already set up to create context-sensitive cross-references. If you have been using the old default cross-reference formats and want to continue using them, you can edit the MadCap|xref style and replace the new formats with the older ones. The old cross-reference format for the default style medium is See "{paratext}". The old format for the print medium is See "{paratext}" on page {page}.

   8. Click OK.
   9. In the Properties dialog, click OK.

   If Using Advanced View

   1. In the local toolbar, make sure the first button displays . If the button displays instead, then click it.
   2. In the upper-left corner of the editor, click in the drop-down field and select .
   3. On the left side of the Stylesheet Editor, select the MadCap|xref tag (or a class of it) that you want to edit.
   4. From the Show drop-down list on the upper-right side of the editor, select . The most relevant properties for that style are shown on the right side of the editor.
   5. (Optional) You can use the toggle button in the local toolbar to show properties below in a group view or an alphabetical view .
   6. If you are using the group view, expand the Unclassified group.
   7. To the right of mc-format, click . The Cross-Reference Format dialog opens.

   8. In the Enter format field, provide the format for the class. 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.

      Command	Description
      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.

      Note For print-based and EPUB output you can create context-sensitive cross-references, which automatically change the text in the link based on the relationship of the cross-reference and the target location. See Creating Context-Sensitive Cross-References and Editing Text for Context-Sensitive Cross-References.

      Note The default format for the primary cross-reference style (MadCap|xref) is already set up to create context-sensitive cross-references. If you have been using the old default cross-reference formats and want to continue using them, you can edit the MadCap|xref style and replace the new formats with the older ones. The old cross-reference format for the default style medium is See "{paratext}". The old format for the print medium is See "{paratext}" on page {page}.

   9. Click OK.
3. Click to save your work.
4. (Optional) To make sure other cross-references display the new format, you can update the cross-references in a topic (Tools > Update Cross-References). However, all of the cross-references will be updated automatically when you generate the output, so this is not a mandatory task.