Information for committers
Understanding the documentation smoke test tool's errors and warnings

[info1] <title> not defined
Not an error (can be ignored) but HTML files typically define a <title> in their <head>. This info is here to let someone know if they haven't defined one when they typically do. If you don't care about the <title> then ignore this message.

[error5] This TOC file contains a link element with no label
A TOC file has a link defined to link to the file but the link has no text and thus the user has no idea what will appear if they click on the link. It'll appear as a blank row in the TOC navigation.

[error6] <fileName>, topic: <topicName> Broken link (or found hyperlink) in TOC
Either the TOC file has a broken link or it has a link to a file external to the docs, e.g. "http://www.eclipse.org/tptp". We check for hyperlinks in the TOC for translatability; everything linked by the user docs must be translatable, and external files typically aren't. While we could link to an external file in the ISV docs, I avoid it because I like to let the user know when they're about to open content that may not be controlled by TPTP. For example, instead of linking to the CBE PDF directly on the TPTP web site, we link to a doc in our plug-in that states that the PDF file is on an external web site and it also provides a link to the download site for Adobe Reader in case the user doesn't have it.

[warning10] <HREF> HTML missing heading: either h1 or h2 expected to be defined in the file.
Each HTML file is expected to have a heading. Originally I expected that they would have <h1> headings but I found that some files (for some unknown reason) used <h2> instead. This rule checks that at least one <h1> or <h2> heading exists in the file.

[orphan] <HREF>
An orphan file is a file that exists in the plug-in but is not linked by the TOC. That means that the user cannot navigate to it nor vsm the Eclipse Search find it. It's a file that can never be read by the user unless he happens to know what its URL is. If it's important information then it should be linked into the TOC (which also makes it available to the search engine), or it's a dead file and should be removed from the plug-in. Another possible cause for this message is if a packaging problem in the plug-in means that the TOC file isn't in the driver.

[error anchor html]: anchor anchorName is not defined in file <fileName>, referenced by: <referringFile>
Broken link. Someone either needs to update the link to the anchor or update the anchor name to match the link.

[error anchor xml]: anchor anchorName is not defined in file <fileName>, referenced by: <referringFile>
Broken link. Someone either needs to update the link to the anchor or update the anchor name to match the link.

[error7] <HREF> HTML title, <title>, must match TOC link label, <label>
[error8] <HREF> HTML h1 title, <h1Text>, must match the TOC link label, <label>
[error8] <HREF> HTML h2 title, <h2Text>, must match the TOC link label, <label>

This group of errors (error7, error8) checks that the label in the TOC matches the label in the file.

This check was added because when I first tested the docs I found that some labels in the TOC were completely incorrect. I can't remember the exact problems, but the labels were misleading. This check is intended to catch only the big discrepancies, for example a TOC link that says "ABC View" which, when the user clicks on it, opens an Agent Controller doc, but String comparisons being the way that they are, even an extra space character will be flagged.

If any of the following strings are at the start of a <title>, <h1>, or <h2>, then the tool should now ignore that difference.