NIM0004: Malformed Help Viewer topic

NIM0004 reports a generated Microsoft Help Viewer topic that is not well-formed XML. Help Viewer parses every topic as XML when it indexes a help package, and it skips any topic it cannot parse. The topic still installs and can still be reached from the table of contents, but it is absent from search results and cannot be reached by an F1 keyword.

Nimbus checks each Help Viewer topic as it is generated and reports this diagnostic instead of letting the problem reach end users, where it would appear only as documentation that cannot be found.

This diagnostic applies only when the Build Help 3 (Help Viewer) output option is enabled for the help project. The other output formats are rendered by browsers and by MadCap Flare, which accept ordinary HTML.

What Help Viewer requires

A Help Viewer topic must be XHTML, not HTML. In particular:

• No DOCTYPE declaration. Help Viewer parses topics with document type definitions prohibited, so any <!DOCTYPE ...> line fails the topic immediately.
• Every element closed. Elements that HTML allows to stand alone must be closed explicitly — <br /> rather than <br>, and likewise <img>, <hr>, <meta>, and <link>.
• Only the five XML character entities. &, <, >, ", and ' are defined; named HTML entities such as   and — are not, because they are supplied by a document type definition that Help Viewer does not read. Use a numeric reference such as   instead.
• Ampersands escaped. A bare &, such as one inside a URL in an href, must be written &.

Common causes

The generated portion of a topic is produced by Nimbus and is well formed, so this diagnostic almost always points at authored content that reached the page as raw HTML:

• A raw HTML block in a Remarks field, or in another custom field, that uses HTML rather than XHTML conventions.
• A conceptual topic in a customized help template that contains an unclosed element or a named HTML entity.
• A customized layout or partial in a help template that emits an unclosed <meta> or <link> element.

How to fix it

The diagnostic message includes the parser’s description of the problem and the line and column where it was found, and the Error List entry opens the generated topic at that position. Correct the markup at that point in the field, conceptual topic, or template it came from, and rebuild.

Where content must contain characters that are awkward to escape, prefer a fenced code block. Its contents are escaped automatically when the topic is rendered.

Configuring this diagnostic

Set the NIM0004Severity property to control how this diagnostic is treated (None, Information, Warning, or Error).

Unlike the other diagnostics, it defaults to Error in every configuration. The others report work an author may still be in the middle of, which is why they begin as warnings. A malformed Help Viewer topic is different: it is not a matter of unfinished authoring but of output that end users cannot search, and it is silent everywhere else — Help Viewer installs the package without reporting an error and omits the topic.

See Configuring Driver Design Analysis.

See also

• Driver Design Diagnostics
• The Markdown Help Template System