Less Than Symbol in Code Block

Topics: Developer Forum
Nov 19, 2007 at 12:05 AM
I'm getting an error when trying to use less than symbols in a code block:

<!-- Badly formed XML comment ignored for member "HasIt" -->

At the end of this message is an example of documentation that generates this error. The documentation building system doesn't seem to like the less-than character in the "for" statement. The documentation builds fine when the less-than character is removed. I had no success with using various HTML escape codes in place of the ascii less-than symbol. Any ideas?

Having documentation that displays some code along with the result of running the code is common. Does anyone have any thoughts about the best pattern of xmldoc tags for this?

Incidentally, a more precise error message would help when isolating the problem, especially for large documentation blocks. It would be nice if this were on a bug list somewhere.

/**
<summary>
A boolean value indicating whether this instance has it.
</summary>
<returns>
True iff the instance has it.
</returns>
<example>
The following code prints the value of
the <see cref="HasIt" /> property for a few numbers.
<code>
for (int i = 0; i < 5; i++) {
Thing x = new Thing(i);
Console.WriteLine("{0}: {1}", x, x.HasIt);
</code>
The output is shown below.
<code>
0: True
1: False
2: False
3: False
4: True
</code>
</example>
*/
public bool HasIt
{ get { return something; } }
Coordinator
Nov 19, 2007 at 12:22 AM
Edited Nov 19, 2007 at 12:22 AM
What you have to remember is that XML interprets characters such as <, >, an & as special so you have to encode them when used in the <code> tag (&lt;, &gt; and &amp;). If the code block is large and you'd rather not do that, the Code Block Component supplied with the help file builder allows you to import literal code from an external file using the source attribute and an optional region attribute to limit it to a defined region. See the help file for details.

Eric
Nov 19, 2007 at 3:58 AM
Eric, thanks.

Escaping the character was the first thing I tried. As luck would have it, the original case had <= rather than <, and I tried the HTML escape code ampersand l e semicolon, which didn't work. That turns out to be the wrong thing to do because even if it had worked, it would have resulted in a less-than-or-equal symbol appearing in the displayed code, and that is wrong since that character cannot occur in real code. What's needed is the XML escape code ampersand l t semicolon. And that does seem to work. I was misled by ampersane l e semicolon not working, and didn't think to try ampersand l t semicolon =. The key is that you cannot use HTML escape codes to get around this problem - you have to use XML escape codes. Dealing with multiple levels of escapes can be tricky..

What's the best way to display sample program output within an <example> tag? Do you use <code> inside the <example> block, or something else?
Coordinator
Nov 19, 2007 at 6:33 AM
Edited Nov 19, 2007 at 6:34 AM
You can place it in a separate <code> tag. If you do put it in a separate code tag, add a lang="none" attribute so that the code block component doesn't try to colorize it using the default language syntax. You can use the title attribute to give it a title too or set it to a string with a single space to have no title.

Eric
Nov 19, 2007 at 9:24 AM
I had actually tried lang="none" in a code tag. With it, the code block is not displayed at all. The block displays fine without it (except that it's labeled as being C# code). This is with the hana style.
Coordinator
Nov 19, 2007 at 4:00 PM
There's a bug in the 1.6.0.1 version that causes that. Update to the 1.6.0.2 version to get the fix.

Eric
Nov 19, 2007 at 9:20 PM
I am running 1.6.0. I attempted to upgrade to 1.6.0.2 using the download at http://www.codeplex.com/SHFB/Release/ProjectReleases.aspx?ReleaseId=8261 , and
got this error when executing SandcastleBuilderSetup.msi: unable to upgrade because a newer version of this product is already installed.
Coordinator
Nov 20, 2007 at 12:43 AM
The installer created by VS doesn't go past "1.6.0" when checking the version. Uninstall the one you have using Add/Remove programs and then install the new one.

Eric
Nov 20, 2007 at 3:25 AM
I uninstalled Sandcastle and Sandcastle Builder, reinstalled both, using the October CTP of Sandcastle, and Sandcastle Builder 1.6.0.2.

A code block with lang="none" still displays nothing. Adding 'title="hello"' with lang="none" didn't seem to help.
Coordinator
Nov 20, 2007 at 4:05 PM
Post an example of the XML comments that aren't working.

Eric
Nov 21, 2007 at 1:01 AM
I get this behavior with the XML comments in the original post, modified so that the < symbol in the for loop is replaced with "ampersand l t ;". With a "lang=none" attribute added to the last code block, the last code block is not displayed, without "lang=none" add to the last code block, the block displays fine. Another copy of the XML comments is at the end of this post.

By the way, the self-reference to the HasIt property inside the example block displays nothing. Is this supposed to work? If so, is there something wrong with the reference there?

/**
<summary>
A boolean value indicating whether this instance has it.
</summary>
<returns>
True iff the instance has it.
</returns>
<example>
The following code prints the value of
the <see cref="HasIt" /> property for a few numbers.
<code>
for (int i = 0; i < 5; i++) {
Thing x = new Thing(i);
Console.WriteLine("{0}: {1}", x, x.HasIt);
</code>
The output is shown below.
<code lang="none">
0: True
1: False
2: False
3: False
4: True
</code>
</example>
*/
public bool HasIt
{ get { return something; } }

Coordinator
Nov 21, 2007 at 4:11 PM
The language filter appears to be hooking up the "none" language blocks as well and since "none" isn't a recognized language, they are always hidden. I've fixed it for the VS2005 and Prototype styles but the Hana style does it differently so I'm still looking into it. For the time being, you can select the ComponentConfigurations property, click the "..." to the right of it, add the Code Block Component to the project, edit its configuration, and uncheck the "language filter" option. That will make all code blocks visible all the time.

The behavior of the HasIt link within its own page is normal. If you look at the HTML, you'll see it's wrapped in a span tag with a selfLink tag. Since it points to itself, it doesn't make sense to make it a link as it would just load the same page.

Eric
Coordinator
Nov 21, 2007 at 4:12 PM
This discussion has been copied to a work item. Click here to go to the work item and continue the discussion.
Nov 22, 2007 at 10:10 AM
Good deal, Eric.

Is there a workaround for operating in console mode? The automated build process I'm using doesn't use the GUI.

It makes sense that self-references wouldn't be links. But they should at least display something. In the Hana style they just display empty space (probably 0 width).
Coordinator
Nov 22, 2007 at 6:25 PM
Regarding the console mode builder, you can pass a configuration on the command line or in a response file (probably easier). Use the -component command line options. You could also edit the configuration in a project and pass that as the first parameter. Subsequent options will override the project options. See the Console Mode Builder topic in the help file for details.

I didn't see any problems with the self links apart from the style not being there. All it does for them if it was there is bold them, they aren't clickable. Right now, the text just shows up as normal unbolded text.

Eric
Nov 23, 2007 at 7:46 PM
Alright, I'll try that in Console mode.

As I said, what I see with the self links in the Hana style is just empty space. Did you try it in the Hana style?
Coordinator
Nov 24, 2007 at 1:12 AM
There's a bug in the stylesheet for the Hana and Prototype styles. They're missing the selfLink class. Add the following to the presentation.css file found in the styles\ folder under each presentation style:

span.selflink {
font-weight: bold;
}

Eric
Nov 24, 2007 at 4:39 AM
I added that to the presentation.css file in Program Files/Sandcastle/Presentation/hana/Styles/presentation.css and Program Files/Sandcastle/Presentation/Prototype/Styles/presentation.css, and rebuilt the document. Self links still are showing up as only empty space.
Coordinator
Nov 24, 2007 at 4:42 AM
I don't know what else to do then. It worked for me once I added that.

Eric
Nov 29, 2007 at 7:14 AM
I don't know what to do either. Have you actually tried it in the Hana style?
Coordinator
Nov 29, 2007 at 4:02 PM
Yes, and with the span.selfLink added to the Hana stylesheet, they show up.

Eric