Editing Cross-Reference Style Formats

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 that 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 master stylesheet (recommended), only that stylesheet is shown in this field. If you are not using a master stylesheet, the stylesheet that you select needs to be applied to the topic in which you are inserting the cross-reference. See Associating Master 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.