How to Use Help XML Tags in Namespace Summary

Topics: Developer Forum, User Forum
Nov 1, 2007 at 6:31 AM
Hi..

Is there some way to use XML help tags within a namespace summary? Microsoft seems to do it - see the System.Diagnostics information, for example.

It looks like one cannot currently use help XML tags within a namespaceSummaryItem tag in a .shfb file. I have an example where a simple 'hello world' summary works fine, but adding tags like angle-bracketed 'para' generates error messages:

% SandcastleBuilderConsole.exe numi.shfb -assembly=numi.dll -comments=numi.xml -include=NamespaceName.Numi
Sandcastle Help File Builder Console, version 1.6.0.0
Copyright c 2006-2007, Eric Woodruff, All Rights Reserved
E-Mail: Eric@EWoodruff.us

Fatal error applying command line option 'numi.shfb' in project 'Unnamed.shfb': SandcastleBuilder.Utils.BuilderException: Error reading project from 'numi.shfb':
An attempt was made to set an unknown or read-only property: para Value:
Hello world.
---> SandcastleBuilder.Utils.BuilderException: An attempt was made to set an unknown or read-only property: para Value:
Hello world.

at SandcastleBuilder.Utils.SandcastleProject.SetProperty(String name, String value)
at SandcastleBuilder.Utils.SandcastleProject.LoadProject(String projectFile)
--- End of inner exception stack trace ---
at SandcastleBuilder.Utils.SandcastleProject.LoadProject(String projectFile)
at SandcastleBuilder.ConsoleMode.SandcastleBuilderConsole.Main(String[] args)
Nov 1, 2007 at 8:41 AM
Edited Nov 1, 2007 at 8:42 AM

Is there some way to use XML help tags within a namespace summary? Microsoft seems to do it - see the System.Diagnostics information, for example.


Yes, you can and I have done it for my docs too. Just use SHFB's project and namespace summary file.

Please read about "Sharing Summary and Namespace Settings Between Projects" in the help SHFB's online
help, and do not touch the *.shfb file unless you know what you are doing.

The following is a sample in the help file

<?xml version="1.0"?>
<doc>
<assembly>
<name>SharedItems</name>
</assembly>
<members>
<member name="R:Project">
<summary>
Shared project summary comments go in here.
</summary>
</member>
<member name="N:">
<exclude />
<summary>
Exclude the global namespace from all projects.
</summary>
</member>
<member name="N:CustomControls.Internal">
<exclude />
</member>
<member name="N:CustomControls.Design"> -------- I will extend here...
<summary>
Common namespace summary info for the CustomControls.Design
namespace go here.
</summary>
</member> ------ which ends here.
</members>
</doc>

For example, you can do something like this
<member name="N:CustomControls.Design">
<summary>
Common namespace summary info for the CustomControls.Design
namespace go here.
<para>
<list type="bullet>
<item>
<description>I will link to a class <see cref="T:CustomControls.Design.MyClassName"/> </description>
</item>
</list>
</para>
</summary>
</member>

To link, provide the full namespace.

Best regards,
Paul.
Nov 1, 2007 at 10:26 AM
Edited Nov 1, 2007 at 10:27 AM
Thanks Paul! I was able to get this working.

I'm using SandcastleBuilderConsole.exe and not SandcastleBuilderGUI.exe, so some manual editing of the *shfb file seems necessary to specify the help file format (Website), copyright message, and a few other things. I did not have to edit the *shfb file for the namespace summary. I used the "-comments" command line argument to SandcastleBuilderConsole.exe to specify the location of the file containing the XML for the namespace summary, using the template from the application help as you suggested.

(This might make a good addition to the FAQ or online help in the future.)
Coordinator
Nov 1, 2007 at 3:14 PM
All project properties are setable from the command line. For example:

SandcastleBuilderConsole -HelpFileFormat=Website -CopyrightText="Copyright My Company" -assembly=numi.dll,numi.xml

See the Console Mode Builder topic in the help file. The help topic can be opened directly from the Start | Program Files | Sandcastle Help File Builder menu.

Eric
Nov 1, 2007 at 7:37 PM
Edited Nov 1, 2007 at 7:39 PM
That is good to know. Originally I used a .shfb file because I wanted to avoid having to mess around with escaped characters and the shell, especially since the 2 or 3 minute turnaround time for a small 'hello world' program made screwing around with escape characters even more painful than it usually is (I can't stand this activity). Everything seems to work fine, except one thing - I cannot get the copyright symbol to display properly. I am using this inside Make code (GNU Make):

-CopyrightText="Copyright AMPERSANDBACKSLASHNUMBERSIGN169; 2007 My Name"

where the actual symbols are ampersand, backslash, and number sign (written this way so that it displays OK in this forum). These simply occur verbatim in the help output and do not display the copyright symbol. (This worked fine when in the .shfb file, without the backslash. I added the backslash so that Make won't think that the number sign starts a Make comment.) Any tricks for getting the copyright symbol to appear using a SandcastleBuilderConsole command line argument would be appreciated.
Coordinator
Nov 1, 2007 at 7:58 PM
Edited Nov 1, 2007 at 7:59 PM
Use the literal text "\xA9". The encoded hex value will get parsed at build time and will come out as a copyright symbol.

Also, if you specify a project file, any options on the command line after it will override its settings.

Eric
Nov 1, 2007 at 11:56 PM
Thanks. Backslash x A 9 works in a command line argument; ampersand backslash 169 ; works in a .shfb file but not in a command line argument. I won't ask why..