6.2. Link tool
Prev | 6. Tools | Next

### 6.2. Link tool

### Note

The Link tool is hidden by default. You need to enable it by checking "Enable the Link Tool" in Options → Preferences, Features section.

The Link tool allows the user to pick a link target after she/he has selected menu item Edit → Add or Change Link.

Figure 15. The Link tool

When the Link tool is used to create a link (that is, not to change the target of a link), the combobox found at the right of the button allows to change the type of the link. For example, in the case of DITA topics, this combobox has two entries: xref and link.

The following procedure is typically what you'll do when you'll want to create a link using the Link tool. DocBook example:

1. Select some text.

2. Press Ctrl+Shift+X (shortcut of Edit → Add or Change Link). The keyboard focus is moved to the Link tool which is activated and now displays the list of all possible targets, given the selected link context (more about link contexts below).

3. Type the first few characters of the chosen link target. Press SPACE to auto-complete the link target it if needed to.

4. Press ENTER when the desired link target is unambiguously selected. Doing this creates a new `link` element wrapping the selected text.

#### 6.2.1. The link context

Initially, just after a document is opened in XXE, the Link tool displays the list of all the link targets found in the document being edited. In such case, the combobox found below "Link context" displays "(current document)".

However, you may at any time specify a larger set of link targets using the "Add link context to list" button of the Link tool. This set of link targets is specified by the means of another XML document. See the examples below.

Example 3. Specifying a DITA map as a link context

You are editing topic `introduction.dita`, which is part of the document specified by map `doc.ditamap`. Specify map `doc.ditamap` as the link context of the Link tool and you'll be able to quickly and easily create in topic `introduction.dita` `xref` and `link` elements pointing inside other topics which are part of the same document.

Example 4. Specifying a modular DocBook book as a link context

You are editing chapter `introduction.xml`, which is included (i.e. using Copy As Reference/Paste) in modular book `primer.xml`. Specify book `primer.xml` as the link context of the Link tool and you'll be able to quickly and easily create in chapter `introduction.xml` `xref` and `link` elements pointing to other parts of the same book.

Example 5. Specifying a set of olink-ed DocBook documents as a link context

You are editing chapter `introduction.xml`, which is included in modular book `primer.xml`. Book `primer.xml` is itself part of a set of olink-ed documents. This document set is specified to the Link tool as follows:

    <documents xmlns="http://www.xmlmind.com/xmleditor/schema/olinked_docs">
      <document name="ref" location="reference/reference.xml"/>
      <document name="primer" location="primer/primer.xml"/>
    </documents>

Let's suppose the above specification is found in `docset.xml`.

Specify document set `docset.xml` as the link context of the Link tool and you'll be able to quickly and easily create in chapter `introduction.xml` `olink` elements pointing to other parts of the same document set[10].

The entries of the "Link context" combobox are common to all the documents opened in XXE.

The "Link context" combobox allows to switch between link contexts at any time.

The "Remove link context from list" button allows to remove a link context from the "Link context" combobox.

#### 6.2.2. Additional functions provided by the Link tool

Reload link context

  Clicking the "Reload link context" button reloads the XML file used to specify the link context, and by doing this, refreshes the list of link targets.

  Reloading a large link context, such as a set of olink-ed documents, may take several seconds even if you have a fast hard disk and a fast CPU.

  The ‘‘local link context'', displayed as "(current document)" by the "Link context" combobox, is always up-to-date and never needs to be reloaded. This is not the case of any other link context, which may become very quickly out-of-date.

  Note that the link targets which are local to the document being edited (e.g. chapter `introduction.xml` in the above DocBook example) are always merged with those found in the selected link context (e.g. book `primer.xml` in the above DocBook example). In other words, a link context does not become out-of-date simply because you are modifying the document being edited.

  ### Tip

  There is no need to click the "Reload link context" button each time you create a new link. Most of the time, a link context, even out-of-date, already has the link target you need.

View link context

  Display all the link targets of the current link context in the dialog box described below, and optionally reach the selected link target by opening the corresponding XML file in XXE.

Check links

  Check all the links found in the document being edited against the current link context. Clicking this button temporarily updates the Validity state and also, possibly displays warning messages in the Validity tool.

  ### Important

  Do no forget to always check the links against an up-to-date link context otherwise you may get false warning messages. If you are not sure whether the selected link context is up-to-date, then do not hesitate to click the "Reload link context" button.

#### 6.2.3. The "View link context" dialog box

The "View link context" dialog box is displayed by the "View link context" button. This dialog box is useful when a link context contains many link targets and when you want to browse them more comfortably than using the list of the Link tool.

Figure 16. The "View link context" dialog box

Find

  Find and select the link target which contains the text typed in the Find field. Both the label[11] and the description[12], if any, of the link targets are searched for the typed text. Document filenames[13] are ignored. The search operation is case-insensitive.

  If the Find text field is empty or becomes empty, the search operation starts at the top of the dialog box. Otherwise the search starts at current selection.

Previous

  Find and select the link target matching the search criterion which precedes the current selection.

  Alternate keyboard shortcut: press Enter in the Find text field.

Next

  Find and select the link target matching the search criterion which follows the current selection.

  Alternate keyboard shortcut: press Shift+Enter in the Find text field.

Visit

  Open the selected XML file in XXE. If the selected file is already opened in XXE, switch to the corresponding document. If a link target has been selected, scroll to show the element which corresponds to this target.

  ### Tip

  Shift-clicking the Visit button allows to open the selected XML file in read-only mode (of course, unless the selected file is already opened in XXE).

Copy

  Copy the selection, URL or link target, to the clipboard.

  Copying a link target this way may be useful to paste it in the "Link target" text field of the Link tool.

Copy menu

  Let's suppose the link target "`map_menu/convert_to_rtf`" found in XML file `/home/hussein/src/4xxe/docsrc/dita/map_reference.dita` (as shown in the above screen shot) has been selected. The document being edited is `/home/hussein/src/4xxe/docsrc/dita/about.dita`.

  Copy Absolute URL

    This menu item copies "`file:/home/hussein/src/4xxe/docsrc/dita/map_reference.dita#map_menu/convert_to_rtf`" to the clipboard.

  Copy Relative URL

    This menu item copies "`map_reference.dita#map_menu/convert_to_rtf`" to the clipboard.

  Copy fragment

    This menu item copies "`#map_menu/convert_to_rtf`" to the clipboard.

[10] In addition to `xref` and `link` elements pointing to other parts of book `primer.xml`!

[11] Example: `map_menu/convert_to_rtf` in the above screenshot.

[12] Example: "`Convert to RTF (Word 2000+) C`" in the above screenshot.

[13] Example: `/home/hussein/src/4xxe/docsrc/dita/map_reference.dita` in the above screenshot.

Prev | Up | Next
6.1. Edit tool | Home | 6.3. Include tool