CodeBlockComponent: "Unable to locate start of region"

Topics: User Forum
Jan 17, 2007 at 10:57 PM
Hi,

SHFB seems to duplicate the code file source path when trying to retrieve a #region block from the source file:

Error message:
"Error: CodeBlockComponent: Unable to locate start of region 'CustomFormat' in source file G:\0069\embedded-interface\examples\G:\0069\embedded-interface\examples\TabControl\TabControlCustom.aspx.vb"

BasePath in SHFB:
"G:\0069\embedded-interface\examples\"

CodeBlock:
"<code source="..\examples\TabControl\TabControlCustom.aspx.vb" region="CustomFormat" lang="vbnet" title="Adding a custom format"/>"

I have no problem getting the whole source file into the help documentation, but as soon as I try to limit the content to a #Region block it throws the exception above.

I also seem to be having trouble with my BasePath, not sure whether this is related to ther #Region problem. SHFB seems to discard the last path element from my BasePath, so I also have to add it to the "source=" path in the CodeBlock. You will note above that the ..\examples\.." part is duplicated in the BasePath and the CodeBlock tag.

Thanks for all your efforts. I was about to roll my own (crude) version when I came across SandCastle and your GUI.

Regards,

Gerhard
Coordinator
Jan 18, 2007 at 3:12 PM
The error message repeats the path when it doesn't need to. The actual cause is that the code block component doesn't currently recognize VB.NET style #End Region statements. This has been fixed and will be in the next release.

Eric
Coordinator
Jan 18, 2007 at 3:15 PM
By the way, the reason you are needing to duplicate the "Examples\" part of the path is that you are prefixing it with "..\" in the source attribute. Get rid of the "..\Examples\" part and it will be fine.
You only need the relative reference if you want to go up a level into a different folder above the base path.

Eric
Jan 18, 2007 at 10:18 PM
Thanks Eric,

I thought the issue might be related to using the "poor cousin" of the CLR languages... I was hopeful though because the examples in the SHFB helpfile references vbnet code.

Likewise, I had found that using the usual HTML relative path syntax (i.e. leaving out the "..\" bit) fixed the issue with the basepath, but the help file uses the "..\" syntax, so I wasn't sure whether leaving that out was interfering with the "#Region" issue.

I'll look forward to the next version. Will that also fix the <see cref=...> issue which I can't get to work with VB.Net?

Too old to change tack to C# I'm afraid...

Regards and thanks for your help,


Gerhard

Coordinator
Jan 19, 2007 at 2:50 AM
What is the issue with the <see> tag? I think there's one where it keeps tacking on additional relative references with each new occurrence. That's been fixed and will be in the next release too. If that's not the one, please let me know and I'll look into it.

Eric
Jan 20, 2007 at 3:29 AM
Hi Eric,

This may be something I'm doing wrong, but I can't for the life of me get the <see cref="..."/> tags to render the links. Sandcastle just leaves out the link completely (and renders the rest of the text in the tag bold when using the VS2005 presentation style.

The output log has loads of warnings in like this one:
----------------------------------------------------------
Warn: ResolveReferenceLinksComponent: The reference link target 'system.Web.HttpBrowserCapabilities.Platform' is unknown.
---------------------------------------------------------------

From reading the help files I suspect this has something to do with the 'relection.xml' file, which I can't find in the sandcastle, shfb or documentation build folders.

I'm using the December CTP with the latest patches (which seems to have solved the problem for others).

Sample documentation follows below:

------------------------------------------------------------

''' <summary>
''' Gets or sets the usable height of the <b>TabControl</b> container.
''' </summary>
''' <value>A <see cref="Unit"/> that represents the height of the control. The default is <b>450px</b>. </value>
''' <returns>A <see cref="Unit"/> that represents the height of the control.</returns>
''' <remarks>This property sets the overal height of the <b>TabControl</b>.
'''</remarks>

----------------------------------------------------------

Using "Prototype" presentation it documents as follows:

--------------------------------------------------------

Value
A that represents the height of the control. The default is 450px.
Return Value
A that represents the height of the control.

--------------------------------------------------------------

I've tried using the full definition e.g. "cref="System.Web.UI.WebControls.Unit"/>" but that doesn't render either.

Regards,

Gerhard
Coordinator
Jan 20, 2007 at 8:35 PM
I haven't had any trouble with the <see> tag in the XML comments. What are you using as the ProjectLinkType and SdkLinkType settings? They can have an effect on how those links are rendered. If left set to Local for ProjectLinkType and Msdn for SdkLinkType, they should work as expected. If you can create a small demo that shows the problem, I can take a look at it.

Eric
Coordinator
Jan 23, 2007 at 2:09 AM
Hi Gerhard,

I believe that the problem with the <see> tag is with the VB.NET compiler. It doesn't write out the fully qualified name to the XML comments file which is what the other compilers do such as the C# compiler. See this thread in the MSDN Documentation forum for details: http://forums.microsoft.com/MSDN/ShowPost.aspx?PostID=802863&SiteID=1

Apparently, you can manually enter the fully qualified name such as "T:System.Drawing.Unit" or whatever. There's also a modification to the transformation files that may help.

Eric