## 3. DITA map reference

## 3.1. DITA map menu

When a DITA map is opened in XMLmind XML Editor, the XML menu becomes the Map menu and this menu is populated with items which are specific to DITA maps. This reference contains a description of such menu items.

### Check map

Conditional Processing Profile
  Displays a dialog box allowing to specify a conditional processing profile (a .ditaval file) which is to be applied to the map being edited and also the medium targeted by this map. The conditional processing profile is used by the Check Map command and also by all the Convert commands found in the Convert Document menu.
  The target medium specified in this dialog box is used only by the Check Map command. If you specifically target a print form (PDF, PostScript, RTF, etc) for your deliverable, check Print. In any other case, check Screen.
  Figure 2. The dialog box displayed by menu item "Conditional Processing Profile"

  ##### Remember

  Note that the values specified in the above dialog box are remembered for use during subsequent editing sessions. For example, in the case of the above screenshot, if you reopen the same map later, this map will still be filtered by `print.ditaval` and its target medium will still be Print, and this even if you do not explicitly use menu item Map → Conditional Processing Profile during the new editing session.

Check Map
  Extensively check the map being edited. This task which can be lengthy is run in background. While this task is running, a non-modal dialog box displays all the errors and warnings found in the map being edited, its submaps and all the topics referenced by these maps. If no errors or warnings are found, the dialog box is automatically closed. Otherwise it stays opened allowing you to review each error or warning. After you are done, you'll have to close the dialog box by clicking Close if you want to be able to re-run Check Map.
  Figure 3. The dialog box displayed by menu item "Check Map"
  As you can see it in the above screenshot, clicking on an underlined filename or URL opens the corresponding topic or map in XMLmind XML Editor and selects the element having the error or a warning.

### Convert Document menu

##### Attention

The items of this menu are all disabled if the document being edited needs to be saved to disk.

Convert to XHTML
Convert to XHTML [one page]
  Converts the document being edited to multi page or single page XHTML 1.0.
Convert to Web Help
  Converts the document being edited to Web Help .
Convert to HTML Help
  Converts the document being edited to a .chm file. This command is disabled on platforms other than Windows.
  Requires:
  1. Download and install Microsoft®'s HTML Help Workshop.
  2. Declare the HTML Help compiler, `hhc.exe`, as the helper application associated to files having a "hhp" extension. This can be specified by using the Preferences dialog box, Helper Applications section.
Convert to Java Help
  Converts the document being edited to a .jar file for use by the Java™ Help system.
  Requires:
  1. Download and install JavaHelp .
  2. Declare the Java™ Help indexer, `jhindexer` (`jhindexer.bat` on Windows), as the helper application associated to files having a "application/x-java-help-index" MIME type. This can be specified by using the Preferences dialog box, Helper Applications section.
Convert to Eclipse Help
  Converts the document being edited to a directory containing various files for use by the Eclipse Help system.
Convert to EPUB
  Converts the document being edited to an .epub file.
Convert to RTF (Word 2000+)
  Converts the document being edited to RTF (Rich Text Format) using. The document generated by this command can be edited and printed using Microsoft® Word 2000 and above.
  Requires downloading and installing the "XMLmind FO Converter XSL-FO processor plug-in " add-on using Options → Install add-ons.
Convert to WordprocessingML (Word 2003+)
  Converts the document being edited to WordprocessingML. The document generated by this command can be edited and printed using Microsoft® Word 2003 and above.
  Same requirements as Convert to RTF.
Convert to Office Open XML (Word 2007+)
  Converts the document being edited to Office Open XML (.docx file) . The document generated by this command can be edited and printed using Microsoft® Word 2007 and above.
  Same requirements as Convert to RTF.
Convert to OpenDocument (OpenOffice.org 2+)
  Converts the document being edited to OpenDocument (.odt file). The document generated by this command can be edited and printed using OpenOffice.org 2.
  Same requirements as Convert to RTF.
Print PostScript
  Convert the document being edited to PostScript® and send the generated file to the chosen printer.
  Requires downloading and installing any of the following add-ons using Options → Install add-ons.
  - Apache FOP 1.x XSL-FO processor plug-in;
  - RenderX XEP XSL-FO processor plug-in(1).
Convert to PDF
  Convert the document being edited to PDF.
  Same requirements as Print PostScript.

### Changing the look and contents of the files generated by the Convert Document menu

There are three ways to change the look and contents of the files generated by the items of the Convert Document menu.

1. Specifying custom XSLT stylesheet parameters. This is done by using Options → Customize Configuration → Change Document Conversion Parameters.
   For example, selecting parameter group "Convert to HTML Help" and adding parameter number with value all allows to number the sections of the generated .chm file.
   The reference manual of the parameters of the XSLT stylesheets used to perform the conversion is found in XMLmind DITA Converter Manual - XSLT stylesheets parameters. This reference manual can be directly accessed from the "Change Document Conversion Parameters" dialog box.
2. Using menu item Options → Customize Configuration → Customize Document Conversion Stylesheets is also a relatively simple way to influence the layout and style of the deliverable (PDF, RTF, HTML, etc) which results from the document conversion.
   The document being edited is converted to other formats by the means of XSLT stylesheets. This menu item allows to:
   - select an XSLT stylesheet other the default one,
   - create a custom XSLT stylesheet on the fly,
   - invoke a specialized editor —XMLmind XSL Customizer— to modify a user-created XSLT stylesheet.
   However, when the document being edited is converted to an HTML-based format (Web Help, EPUB, HTML Help, etc), the HTML pages which are automatically generated by the aforementioned XSLT stylesheets are styled mainly by CSS stylesheets. When this is the case, this menu item allows additionally to:
   - select a CSS stylesheet other the default one,
   - create a custom CSS stylesheet on the fly,
   - invoke a helper application (generally, a text editor) to modify a user-created CSS stylesheet.
3. To a lesser extent, changing the options of the XMLmind DITA Convert (ditac) preprocessor. This is done by using Options → Customize Configuration → Preprocessing Options.
   For example, selecting option group "Convert to PDF, PostScript" and then selecting "Generate as backmatter" in the Index combobox allows to add an index at the end of the generated PDF files.
   More information about this facility in Section 7.

Note that a technical writer is not expected to know which parameter, option or style is to be specified to get the desired effect. Unless she/he is the local guru, a technical writer is expected to post a support request to the xmleditor-support public, moderated, mailing list in order to learn this. But at least the three above facilities allow her/him to customize her/his deliverables without having to hand edit configuration files.

### Syntax highlighting

You can automatically colorize the source code contained in pre, codeblock or any other element specializing pre. This feature, commonly called syntax highlighting, has been implemented using an open source software component called "XSLT syntax highlighting ".
If you want to turn on syntax highlighting in a DITA document, suffice to add attribute outputclass to a pre, codeblock or any other element specializing pre. The value of attribute outputclass must be any of: language-c, language-cpp, language-csharp, language-delphi, language-ini, language-java, language-javascript, language-m2, language-perl, language-php, language-python, language-ruby, language-tcl, language-xml.
If you want to customize syntax highlighting for an HTML-based output format (XHTML, EPUB, etc), redefine any of the following CSS styles:

- .hl-keyword (keywords of a programming language),
- .hl-string (string literal),
- .hl-number (number literal),
- .hl-comment (any type of comment),
- .hl-doccomment (comments used as documentation, i.e. javadoc, or xmldoc),
- .hl-directive (preprocessor directive or in XML, a processing-instruction),
- .hl-annotation (annotations or "attributes" as they are called in .NET),
- .hl-tag (XML tag, i.e. element name),
- .hl-attribute (XML attribute name),
- .hl-value (XML attribute value),
- .hl-doctype (<!DOCTYPE>and all its content).

Example:

    .hl-keyword {
        font-weight: bold;
        color: #602060;
    }

This can be done from within XXE using Options → Customize Configuration → Customize Document Conversion Stylesheets.
If you want to customize syntax highlighting for an XSL-FO-based output format (PDF, RTF, etc), redefine any of the following attribute-sets: hl-keyword, hl-string, hl-number, hl-comment, hl-doccomment, hl-directive, hl-annotation, hl-tag, hl-attribute, hl-value, hl-doctype.
Example:

    <xsl:attribute-set name="hl-keyword" use-attribute-sets="hl-style">
      <xsl:attribute name="font-weight">bold</xsl:attribute>
      <xsl:attribute name="color">#602060</xsl:attribute>
    </xsl:attribute-set>

This can be done from within XXE using Options → Customize Configuration → Customize Document Conversion Stylesheets.

## 3.2. DITA map tool bar

When a DITA map is opened in XMLmind XML Editor, buttons which are specific to this kind of document are automatically added to the tool bar. This reference contains a description of such buttons.

Button | Description
--- | ---
Insert topicref before | Insert a topicref before selected topicref, topichead, topicgroup.
Insert topicref into | Append a topicref child element to the selected topicref, topichead, topicgroup.
Insert topicref after | Insert a topicref after selected topicref, topichead, topicgroup.
Move up | If selected element is a topicref, topichead, topicgroup, navref or anchor and if this selected element is preceded by a topicref, topichead, topicgroup, navref or anchor, this command moves selected element one position up in its container element.
Move down | If selected element is a topicref, topichead, topicgroup, navref or anchor and if this selected element is preceded by a topicref, topichead, topicgroup, navref or anchor, this command moves selected element one position down in its container element.
Promote | If selected element is a topicref, topichead, topicgroup, itself contained in a topicref, topichead, topicgroup, this command removes selected element from its parent and makes it a sibling following its ex-parent. Moreover, all elements that followed selected element in the ex-parent are also removed from this ex-parent and made children of the newly ``promoted'' element.
Demote | If selected element is a topicref, topichead, topicgroup, itself preceded by a topicref, topichead, topicgroup, this command moves selected element at the end of its predecessor.

Edit referenced topic or map

Opens in XMLmind XML Editor the topic or map referenced in the conref, href or mapref attribute of selected element.
If this document is already opened in XMLmind XML Editor, this command brings its view to front and makes it the active one.
If this document does not exist yet, the File → New dialog box is displayed and allows the user to choose which document (i.e. topic, task, reference, map, etc) is to be created at the location specified by attribute href, mapref or conref.

## 3.3. DITA map bindings

When a DITA map is opened in XMLmind XML Editor, additional keyboard shortcuts which are specific to this kind of document are automatically made available to the user. This reference contains a description of such keyboard shortcuts.

Keyboard shortcut | Description
--- | ---
F2 Up | Move up
F2 Down | Move down
F2 Left | Promote
F2 Right | Demote
F2 e | Edit referenced topic or map

(1) | Unlike all the other add-ons, the RenderX XEP XSL-FO processor plug-in is not self-contained. You'll need to download, install and activate RenderX XEP (for example, free Personal Edition ) prior to using the RenderX XEP XSL-FO processor plug-in.