Context-based Conversions

The following HTML elements must be converted based on their context within the topic. Since the context is hard to translate into an easily defined rule in the rules file, the elements described in this topic are handled by the application itself. As such, these elements should not appear in any of the previously defined rules.

• Anchor Elements
• Code Elements
• Heading Elements
• Image Elements
• See Elements

HTML anchor elements (a) are replaced as follows:

• Anchors with a name attribute are assumed to be in-page link targets. The MAML equivalent of such a link target is an address attribute on an element such as section, definedTerm, listItem, etc. Trying to place an address attribute on the appropriate element is almost impossible so these anchor types are replaced with a "<!-- TODO: -->" comment for later review. A warning is also written to the log file.

  An exception is targets inside of heading HTML elements. If properly formatted, these will be converted to address elements on the related section element when the heading elements are processed (see below).

• If the link's URL contains "://", starts with "mailto:", or the link specifies a target attribute it is converted to an externalLink.

• All other links are converted to link elements. If the topic ID cannot be resolved using the filename from the HTML href attribute, it is replaced with a "<!-- TODO: -->" comment for later review and a warning is written to the log file.

The normal code HTML element is equivalent to the MAML codeInline element. However, to support conversion of the Sandcastle Help File Builder option of including code blocks from external files, this element is replaced based on the following contexts:

• If no attributes are present on the element and no carriage return/line feeds are present in the element's inner text, it is replaced with a MAML codeInline element.

• If any attributes are present on the HTML element or if its inner text contains multiple carriage return/line feeds, it is replaced with a MAML code element and any attributes are preserved.

• In the event that no attributes are present and only a single carriage return/line feed pair are present in the inner text, it is assumed that the value simply spans a line break and it is replaced with a codeInline element instead.

HTML heading elements (h1 through h6) are replaced with a section element. The content of the heading element becomes the section title and is placed in the section's title element. The text following the heading becomes the content of the section. When a new heading element is encountered, closing section elements are inserted as needed. Closing section elements are also added to the end of the body text if at least one heading was encountered to close off the final section.

Anchor elements are processed before heading elements. As such, if a named anchor is replaced with a To Do comment and it appears within the heading tag, it will be converted to an address attribute on the section automatically as shown in the example below. This saves you from having to do it manually but you should still review the update to make sure that it is appropriate.

See the <a href="#BuildLogFile">BuildLogFile</a> property

.
.
.

<h3><a class="Reference" name="BuildLogFile">The BuildLogFile Property</a></h3>
<p>Section content</p>

See the <link xlink:href="#BuildLogFile">BuildLogFile</link> property

.
.
.

<section address="BuildLogFile"><!--h3-->
  <title>The BuildLogFile Property</title>
  <content>
<para>Section content</para>
  </content>
</section>

MAML sections can be nested within one another. However, attempting to do this during conversion would be very difficult and would most likely result in changes that were not intended or are not appropriate. As such, no attempt is made to nest sections with a higher heading number into prior ones with a lower heading number (i.e nesting h2 sections within an h1 section). The heading element that caused the section to be created is added in a comment following the section element. You can review the topic after conversion to decide whether to leave the topic as it is or rework the content to nest sections within one another.

HTML image elements (img) are replaced with an externalLink if the src attribute contains "://". If not, the image is assumed to be local to the project and is converted to a mediaLink. Note that it is not possible to determine whether or not to use a mediaLinkInline element instead. As such, you will need to update the link during the review after conversion. For mediaLink elements, you may need to add a caption element if needed and other attributes to properly set the image alignment as well.

When a new image is encountered, it is added to the media content file created by the conversion process and the image file is copied to the Media\ folder under the destination folder. The source image location is determined by combining the source conversion folder with the path from the src attribute. If the image file cannot be found, the replacement element is prefixed with a "<!-- TODO: -->" comment noting the missing file and a warning is written to the log file.

The Sandcastle Help File Builder supports see elements within additional content HTML files. When encountered, these are converted to links to the matching API member topics. To match this behavior, if a see element is encountered during conversion, it is converted to an appropriate codeEntityReference element.

The help file builder has the ability to resolve a reference based on a partial name. However, MAML requires that the name be fully qualified. As such, if a partial name is encountered, it will still be converted but a warning will be written to the log file. These will need to be fixed during the review to replace them with their fully qualified names.

Other Resources