| # XMLmind XML Editor - Online Help |

### 3.3. Reference menu

### About the Include tool feature

Some menu items are by default absent in this menu. You need to enable them by checking "Enable the Include Tool" in Options → Preferences, General|Features section.

Copy as Reference

  Copies to the clipboard a reference to the selected nodes (i.e. a pointer to selected nodes). This reference can be later pasted into another document[10], using any of the normal paste commands — Edit → Paste Before (Ctrl+U), Edit → Paste (Ctrl+V), Edit → Paste After (Ctrl+W) — in places where the grammar constraining the target document allows to do so.

  This command is enabled only for documents associated to a configuration declaring a inclusion scheme (see Section 14, “inclusionScheme” in XMLmind XML Editor - Configuration and Deployment). DITA documents use the `conref` inclusion scheme. DocBook and XHTML documents use the XInclude inclusion scheme.

  By default, it is possible to copy as a reference only an element having an ID attribute or the root element of a document. However, for documents using the XInclude inclusion scheme, this restriction may be relaxed by using Options → Preferences, Edit section, Allow advanced use of XInclude checkbox. When this option is turned on, it becomes possible to copy as a reference any range of sibling nodes.

  It is not possible to copy as reference the text selection, a reference, descendant nodes of a reference or any node selection directly containing one or more references. If you want to do so, simply use the normal Edit → Copy command, as this command preserves[11] existing references.

  ### Note

  The pasted reference cannot be edited in place. It is displayed with a light gray background to clearly indicate this. Use menu item Edit → Document Reference → Edit Referenced Document (Ctrl+Shift+E) to open a new window allowing to edit the document containing the referenced nodes.

Replace by Reference

  Replace by an element reference

  - text selection

  - OR explicitly selected node or node range.

  The element reference to be inserted in the document is specified using the Include tool.

Insert Reference Before

  Insert an element reference before

  - explicitly selected node or node range

  - OR implicitly selected element.

  The element reference to be inserted in the document is specified using the Include tool.

Insert Reference

  Insert an element reference

  - replacing text selection if any,

  - OR, if there is no text selection, insert an element reference in element containing caret, at caret position.

  The element reference to be inserted in the document is specified using the Include tool.

Insert Reference After

  Insert an element reference after

  - explicitly selected node or node range

  - OR implicitly selected element.

  The element reference to be inserted in the document is specified using the Include tool.

Include Text

  Displays a file chooser dialog box allowing to choose a text file (of any kind: XML, HTML, `.bat`, C/C++, etc). The content of this text file is then included in the document being edited at caret position.

  This kind of inclusion is implemented by the means of an `<xi:include parse="text">` element. Therefore, this command is disabled unless the document being edited supports the XInclude inclusion scheme.

Untransclude Reference

  Replaces included nodes by the inclusion directive (e.g. `xi:include` element).

  Any kind of selection inside the included nodes suffices to specify the subject of this command.

Untransclude All

  Replaces all the included nodes found in the document being edited by the corresponding inclusion directives.

Retransclude Reference

  Inverse action of Untransclude Reference: replaces inclusion directive (e.g. `xi:include` element) by up-to-date included nodes.

  The inclusion directive must be explicitly or implicitly selected.

  Using untransclude allows to edit the inclusion directive by hand before retranscluding it. This is useful in the two following cases:

  - This allows to add attributes (typically an ID) to the `conref` elements created using Copy As Reference then Paste.

  - This allows to fine tune the `xpointer` attribute of the XIncludes created using Copy As Reference then Paste. Example: replace `xpointer="xpointer(id('disclaimer')/*[position() >= 1 and position() <= 8])"` by, simpler and more stable, `xpointer="xpointer(id('disclaimer')/*)"`.

Retransclude All

  Replaces all the inclusion directives found in the document being edited by the corresponding included nodes.

Edit Referencing Document

  If current document is referenced by another document already opened in XXE and displayed in another window, this command brings the window of this other document to front. If there is no such referencing document, this command is silently disabled.

  Example 3.2. Example: book referencing chapters

  Book `book.xml` references chapters `chap1.xml`, `chap2.xml`, `chap3.xml`, etc, created in separate documents.

  Clicking anywhere inside first chapter displayed in the `book.xml` window then using menu item Edit → Reference → Edit Referenced Document (Ctrl+Shift+E) brings the window containing `chap1.xml` to front. (If needed, `chap1.xml` is opened in XXE.)

  Now being inside the `chap1.xml` window, using menu item Edit → Reference → Edit Referencing Document (Ctrl+Shift+B) brings the window containing `book.xml` to front.

Edit Referenced Document

  If the caret or the selection is inside a reference to an element contained in another document, this command brings the window of this other document to front. If the referenced document is not yet opened in XXE, this command will open it.

  See example above.

  ### Tip

  Shift-click on this menu item to open referenced document in read-only mode.

[10] It can also be pasted in the same document at another location.

[11] But, unlike Edit → Reference → Copy as Reference, it cannot create references.