Appendix id195AD0L60Y4

Prepare InDesign files for conversion id195DBF0045Z

InDesign provide authors with a rich set of features for creating attractive and complex documents. Often this means that the various parts of a document are placed on the page visually, but with no attempt to provide any flow between those text frames. When the ‘reading order’ of the text frames is not defined, the IDML file will contain stories that may not follow any meaningful order. The end result will be one or more DITA topics with paragraphs, tables and graphics in a random order.

While it is possible to edit the DITA content into a sensible order in a DITA editor, it is much easier to fix the InDesign file before creating the IDML file. This can be done without altering the look of the source document. It also has the benefit of making the source document accessible by properly defining the reading order.

Threading text frames

InDesign uses the term ‘threading’ for the process of linking one frame to another. For more details about threading text frames, see Threading text topic in InDesign documentation.

Overlapping frames

Some InDesign documents use un-threaded overlapping frames for layout reasons. It may be very difficult to merge this content into the main thread. The best option may be to edit the result in the DITA environment.

InDesign stories

Each threaded flow of content in an InDesign document is a called a ‘story’. For best results, it is recommended to keep the number of stories limited. However, there are some parts of your document that may not be needed in the DITA output. For example, page footers are rarely need, but may appear in the middle of a topic if they are not handled carefully.

The easiest way to exclude text that is not required in the document is to give it a special Paragraph Tag that is only used for the unwanted content. For example, instead of reusing a [Basic Paragraph] for the footer, create a dedicated Footer tag. Then in the MapStyle file simply set the Footer paragraphs to be dropped like this:

<paraRule style="Footer" local="0" refactor="drop">
   <attributeRules createID="false"/>
</paraRule>

Mapping to DITA doctypes

It is essential that your source document has at least one Paragraph style or Element that can mark the start of a topic. It is common for documents to use Heading1 as the name of the top-level titles in the document. You can then create a mapping from that style to a specific DITA doctype. If your document is well organized and the use of Heading1 is constant throughout, then you will get good results.

Multiple DITA doctypes

If some of the Heading1 paragraphs are need to convert to different DITA doctypes, then duplicate the paragraph style in InDesign. Give these styles an easy to recognize name such as Heading1_genTask or Heading1_troubleshooting as appropriate. Then, setup the mapStyle file as shown below:

<doctypes>
   <doctypeParaRule style="Heading1" local="0" mapToDoctype="concept">
      <attributeRules createID="true"/>
   </doctypeParaRule>
   <doctypeParaRule style="Heading1_genTask" local="0" mapToDoctype=" generalTask">
      <attributeRules createID="true"/>
   </doctypeParaRule>
   <doctypeParaRule style="Heading1_troubleshooting" local="0"mapToDoctype=" troubleshooting">
      <attributeRules createID="true"/>
   </doctypeParaRule>
</doctypes>

Structured InDesign documents

InDesign has a loose relationship with XML. While a document can include an XML DTD and the main story may be valid against that DTD, it is also possible to create hybrid documents where some of the content is XML, but no DTD is included. These are the undesirable cases for a successful conversion to DITA. If a document contains XML parts, try to save the output to XML and see if the results are acceptable. If not, then DITA content will also include invalid content, or may fail completely.

Table formatting

The conversion from InDesign table formatting rules to the equivalent table formatting in DITA is a complex process. This is due to the rich formatting features available in the source files compared to the basic options provided by the Oasis (CALS) table model used in DITA. Vertical and horizontal text alignment is provided and gives similar results although Justified text is always justified according to the text direction, while InDesign allows Left Justified and Right Justified.

InDesign’s handling of column and row separators is again far more capable than the Oasis table model’s basic options. InDesign provides four cell borders—Border type (solid or pattern), Border weight, Border color, Border tint, Border gap color and border gap tint. All of these have to be mapped down to borders on the right and bottom of each cell (entry element) where the only choices are 0 or 1 – hide the border or show the border.

Border ruling in InDesign can be applied at the following levels:

The InDesign to DITA conversion process applies the border ruling as follows:

Alternating patterns

InDesign Table Styles allow column and cell ruling to follow an alternating pattern. While this feature is supported for conversion, the results will only be obvious when one pattern group maps to show ruling (1) and the other pattern group maps to hide ruling (0).

Prepare the mapping file for InDesign to DITA migration id194AF0003HT

The correct DITA conversion requires a mapping file that matches the contents of the source document. For unstructured InDesign documents, this means all available Paragraph Styles and Character Styles need to be mapped. For XML structured InDesign documents all elements in its associated DTD must be mapped.

The mapping files for unstructured and structured InDesign documents are different. This is due to the more complex processing requirements for converting unstructured source content to DITA.

A sample of the mapping file is given below:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE styleMap SYSTEM "mapStyle.dtd">
<styleMap xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="mapStyle.xsd" >
   <doctypes>
      <mapDoctypeParaRule root="itpx:stories" mapToDoctype="map">
         <attributeRules createID="true">
            <addNew name="outputclass" value="map"/>
         </attributeRules>
      </mapDoctypeParaRule>
      <doctypeParaRule style="Heading 1" local="0" mapToDoctype="concept">
         <attributeRules createID="true"/>
      </doctypeParaRule>
      <doctypeParaRule style="Heading A" local="0" mapToDoctype="topic">
         <attributeRules createID="true"/>
      </doctypeParaRule>
   </doctypes>
   <wrappingRules>
      <wrap elements="li+" context="number" wrapper="ol">
         <attributeRules createID="true"/>
      </wrap>
      <wrap elements="li+" context="bullet" wrapper="ul">
         <attributeRules createID="true"/>
      </wrap>
   </wrappingRules>
   <paragraphStyleRules>
      <paraRule style="Heading 2" local="0"  mapTo="p">
         <attributeRules createID="true"/>
      </paraRule>
      <paraRule style="Heading 3" local="0"  mapTo="p">
         <attributeRules createID="true"/>
      </paraRule>
      <paraRule style="List Paragraph" local="p[-|-|-|-|-|b|-|-]" context="bullet" mapTo="li">
         <attributeRules createID="true"/>
      </paraRule>
      <paraRule style="List Paragraph" local="p[-|-|-|-|-|n|-|-]" context="number" mapTo="li">
         <attributeRules createID="true"/>
      </paraRule>
      <paraRule style="List Paragraph" local="0" context="bullet" mapTo="li">
         <attributeRules createID="true"/>
      </paraRule>
      <paraRule style="Normal" local="0"  mapTo="p">
         <attributeRules createID="true"/>
      </paraRule>
      <paraRule style="Normal" local="p[-|-|-|-|-|b|-|-]" context="bullet" mapTo="li">
         <attributeRules createID="true"/>
      </paraRule>
      <paraRule style="Title" local="0"  mapTo="p">
         <attributeRules createID="true"/>
      </paraRule>
   </paragraphStyleRules>
   <characterStyleRules>
      <charRule style="Bold" local="0" mapTo="b">
         <attributeRules createID="false"/>
      </charRule>
      <charRule style="Code" local="0" mapTo="codeph">
         <attributeRules createID="false"/>
      </charRule>
      <charRule style="[No character style]" local="c[Bold|-|-|-|-|-|-|-]" mapTo="b">
         <attributeRules createID="false"/>
      </charRule>
      <charRule style="[No character style]" local="c[Italic|-|-|-|-|-|-|-]" mapTo="i">
         <attributeRules createID="false"/>
      </charRule>
   </characterStyleRules>
</styleMap>

The mapping file is an XML file with a simple structure that lists all the source paragraph styles and character style codes. The file contents are explained below:

Style Mapping

In the styleMap element, you can specify two optional attributes – @map_date and @map_version for recording the version of the mapping file.

Document Type

The doctypes element lists the supported DITA map and topic mappings.

Map document type paragraph rules

The mapDoctypeParaRule element is mandatory. This element’s attributes must not be edited because the source XML’s root element is always mapped to the DITA map’s root map element.

Document type paragraph rule

The doctypeParaRule element is mandatory. This gives the conversion process a way to identify the start of a new topic. Normally the @style attribute is used on its own with the @local attribute set to 0. However, if there are always local formatting overrides on the chosen style, you will have to add a rule for each style plus its local overrides. This is simple to recognize in the generated mapping file where it would be possible to find this or similar:

<paraRule style="Heading 1" local="0" mapTo="p">
   <attributeRules createID="true"/>
</paraRule>
<paraRule style="Heading 1" local="p[Italic|-|-|-|-|-|-|-]" mapTo="p">
   <attributeRules createID="true"/>
</paraRule>

In the above example, there are two paraRule elements for @style = “Heading1”. Simply, create an equivalent doctypeParaRule elements with the @mapToDoctype attribute set as required.

The attributes used in the doctypeParaRule are explained below:

Element wrapping rules

The element wrapping rules define the ways to wrap or move elements in the incoming document into a predefined element according to a set of attribute values.

wrap element

This is an optional element. The wrap element lists the elements that will be wrapped or moved. Wrapping is typically used where a series of elements must be given a common parent element. For example, multiple li elements being wrapped in a ol element. Additionally, wrap can be used for moving elements such as titles for figures and tables.

The attributes used in the wrap are explained below:

The following example shows how to create a fig element from a title and an image element:

The following example shows how to move a title into a table:

Paragraph style rules

The <paragraphStyleRule> elements are described below:

paraRule element

The paraRule element is mandatory. This specifies the mapping rules for all Paragraph Styles. In an InDesign document, all text is contained within sub-structure of Paragraph Styles, even paragraphs without any style are named [No paragraph style]. The square brackets, these indicate a built in InDesign style name.

The attributes used in the paraRule are explained below:

Character style rules

The charRule elements are described below:

charRule element

This is an optional element.

These are the mapping rules for all Character Styles. In an InDesign document, all text is contained within child elements of Character Styles.

The attributes used in the charRule are explained below:

Attribute rules

This element can be a child of the following element contexts:

The purpose of attribute rules is to manage the attributes for the matched elements.

Depending on the context, the following attributes are available the attributeRules element:

The attributes used in the attributeRules are explained below:

Local formatting codes

In any InDesign document, it is possible for paragraph styles and character styles to carry several hundred different formatting overrides. Most of these properties provide no useful role in the conversion process. However, we have identified a core set of formatting features that do affect the semantics of the document and need to influence the conversion process.

The @local attributes are presented as a special delimited format where eight fields are provided along with a prefix to show the type of formatting override. The formatting codes fields are listed below:

Careful use of this feature allows otherwise lost local formatting can help to improve the quality of a transfer from styled content into DITA. This example can be resolved to mean Italic, 16pt text in a bulleted list: p[Italic|16|-|-|-|b|-|-].

Structure Mapping

The structure mapping file is similar to the Style Mapping file with a simple structure that lists all the source element and relevant attribute types. Two attributes, @map_date and @map_version are provided for recording the version of the mapping file to be used.

Document Type

The doctypes element lists the supported DITA map and topic mappings.

Map document type element rules

The mapDoctypeElemRule element is mandatory. This element’s attributes must not be edited because the source XML’s root element is always mapped to the DITA map’s root map element.

Element wrapping rules

elementRules element This lists all elements.

elementRule element The elementRule element is mandatory. These are the mapping rules for all source elements. While an InDesign document does contain unstructured style elements, these are ignored for structured content unless the ‘hybrid mode’ processing is enabled.

The attributes used in the elementRule are explained below:

Troubleshooting AEM Guides

Once you have installed and configured AEM Guides, you can troubleshoot the issues.

Validate references

You can run the given scripts to validate the references. These scripts can help you identify the broken references and then patch or fix them.

Validate script

Perform the following steps to check the references, using the validate script available in the product package:

Patch script

Perform the following steps to patch any broken references, using the patch script available in the product package:

Logger

You can also create a separate logger for this script execution, as per the details given below:

The created log file will record all the information that is related to script execution and is useful in case the browser session timeouts, while triggering the script from the browser.