Warnings and To Do Items

The following warnings may appear in the log file.

Warning: Found unknown tag [tag] which will be removed

This warning appears if an HTML element is encountered that is not covered by one of the rules defined in the configuration file. In such cases, the unknown tag will be removed.

Warning: Image file '[file]' not found

This warning appears when an HTML image link is converted to a mediaLink and the source file could not be found. While the link will still be created and an entry made in the media content file, the corresponding source file will not be found in the media folder after conversion. You will need to manually locate the file and add it to the project.

Warning: Named anchor [id] needs review

This warning appears when an HTML anchor element with a name attribute is encountered. This is a reminder that you will need to edit the topic and apply an address attribute with the specified ID to the appropriate MAML element. Refer to the Sandcastle MAML Guide for information on which elements support an address attribute.

Warning: Reference to code entity [id] is not fully qualified

This warning appears if a codeEntityReference is added and the target specified in the source HTML file is not a fully qualified name. You will need to update these to specify the fully qualified name. If not, the reference will not be rendered as a link when the topic is built.

Warning: Unable to resolve topic link to '[file]'

This warning appears when the target file of an HTML anchor could not be found in any of the converted topics. In such cases, a To Do entry in the topic replaces the link and you will need to locate the file and add the link when reviewing the topic.

Warning: Unknown entity encountered: [entity]

This warning appears if a named entity is encountered that is not defined in the entity conversion rules. In such cases, the entity is passed through to the converted topic as-is. When you build the topic, it will most likely fail because the .NET XML parser will not recognize it. The entity will need to be corrected or removed.

While reviewing topics after conversion, you will see various "<!-- TODO: -->" comments. The following items describe what each of them means.

TODO: Add named anchor: [id]

This comment appears in the place of a named HTML anchor. This is a reminder that you will need to apply the indicated ID as an address attribute on the appropriate MAML element located near the comment. Refer to the Sandcastle MAML Guide for information on which elements support an address attribute.

TODO: Missing source image: [file]

This comment appears when an HTML image link is converted to a mediaLink and the source file could not be found. While the link will still be created and an entry made in the media content file, the corresponding source file will not be found in the media folder after conversion. You will need to manually locate the file and add it to the project.

TODO: Move introduction text here

This To Do item will be seen in the required introduction section that is added to every topic. Since the conversion process cannot guess what text you might want to appear there, it leaves it for you to handle during the review.

TODO: Reference not fully qualified

This comment appears next to a codeEntityReference in which the target is not a fully qualified name. You will need to update the reference to specify the fully qualified name. If not, the reference will not be rendered as a link when the topic is built.

TODO: Review markup

This comment precedes any HTML elements wrapped in the MAML markup element. The content of the element should be reviewed to see if it should be retained, removed, or edited to use other appropriate MAML elements.

TODO: Unknown topic link: [file]

This comment appears in place of an HTML anchor when the indicated target file/ID could not be found in any of the converted topics. In such cases, you will need to locate the file and add the link when reviewing the topic.

Other Resources