Common Issues and Solutions

Missing end elements

These can be found by performing a build with your preferred documentation tool. The error message will list the failing topic along with the element name(s) and the line number and column where the starting and ending elements did not match up. To fix the issue, edit the topic and add the missing end element in the correct location.

Ill-formed or unencoded entities

HTML is quite forgiving when it comes to ill-formed or unencoded entities but XML is not. Examples include missing the ending semi-colon (&lt rather than <) or not encoding it at all (using && in example code rather than &&). These can also be found by doing a build and locating the offending entity via the information provided in the error message.

Table header formatting is lost

When an HTML table is converted to MAML, any th elements are converted to the equivalent entry MAML element. This results in the header cell being rendered as a normal cell in the table. In order to render the cells using the table heading style, wrap the containing row element to a tableHeader element. For example:

Copy

<table>
  <tableHeader>
    <row>
      <entry><para>Column 1</para></entry>
      <entry><para>Column 2</para></entry>
    </row>
  </tableHeader>
  <row>
    <entry><para>Value 1</para></entry>
    <entry><para>Value 2</para></entry>
  </row>
  <row>
    <entry><para>Value A</para></entry>
    <entry><para>Value B</para></entry>
  </row>
</table>

Image link type and alignment

As noted in the Context-based Conversions topic, you may need to change mediaLink elements to mediaLinkInline elements where appropriate. In addition, you may need to add captions and/or set the alignment attributes based on your preferences.

Paragraph spacing is inconsistent

Omitting para elements around paragraphs or using self-closing para elements can cause some inconsistent spacing between paragraphs. To make it consistent, wrap all paragraphs in opening and closing para elements.

Other Resources