Exclude from TOC?

May 5, 2008 at 5:21 AM
Is there an easy way to have a Reference item still included in the help index, but not listed in the Table of Contents?

I attempted to use ApiFilter, however this excludes the item from the help index completely, which I do not want. My SDK has a lot of structures and constants which I want people to be able to view through method params, but I don't want them in the TOC.

If nothing currently exists then I was thinking of a custom build component which would run after the GenerateTOC function and use a new XSLT to strip them. Would this be a proper route to take?

Thanks!
Editor
May 5, 2008 at 6:08 AM
If you are using the Sandcastle Help File Builder, the next release will contain a TOC Exclusion Plug-in that lets you do this. It'll be out shortly after the next release of Sandcastle.

Eric
May 5, 2008 at 6:18 AM
I actually had been using the production release of SHFB, however I just installed the beta and noticed this feature myself. I am testing it now, but it does seem to be exactly what I was looking for. Thanks!
May 5, 2008 at 6:19 AM


Eternal wrote:
I attempted to use ApiFilter, however this excludes the item from the help index completely, which I do not want. My SDK has a lot of structures and constants which I want people to be able to view through method params, but I don't want them in the TOC.

Constants? Do these appear in the TOC?

For the structures...how about considering one of these solutions
  • A namespace that groups the common structures?
  • A rewrite of the TOC that will group Classes, Interfaces, Enumerations and Structures?

As a user, I may want access any structure anytime I want, but if I have to go through a method/property using it before I could get an information on it, I do not see any advantage.

Best regards,
Paul.
May 5, 2008 at 6:55 AM

Constants? Do these appear in the TOC?

Sorry, I didn't mean constants, I meant Enums. Been working on this problem all weekend, and lack of sleep has finally caught up it seems...


For the structures...how about considering one of these solutions
  • A namespace that groups the common structures?
  • A rewrite of the TOC that will group Classes, Interfaces, Enumerations and Structures?


I had considered adding them to their own namespace, or moving them around a bit, however due to the way our code is organized and the number of customers with existing projects this is not really an option. While the API may seem messy at first glance, it is laid out so that all languages use a common API. The underlying code is unmanaged C+, but we have an automated generator that builds out the managed code library, as well as the COM interfaces/etc. Allows the SDK to be used from any of 10 languages w/ ease.

Rewriting the TOC so they group would have worked for me, however excluding them from the TOC entirely has made the help a LOT cleaner looking. (We already have 50+ classes documented, we didn't need to display 250+ enums and structures there.)


As a user, I may want access any structure anytime I want, but if I have to go through a method/property using it before I could get an information on it, I do not see any advantage.


Agreed, but simply clicking on the namespace itself will show you the enums/structures. This just keeps the TOC organized. With the amount of "high level" objects we have, combined with 15 topics and over 100 subtopics, we already have a large TOC.

Thanks again for the help all. The beta of SHFB already has my TOC in order, and it took less than 10 minutes to drop in the exclude tags.
May 5, 2008 at 7:31 AM


Eternal wrote:
...but simply clicking on the namespace itself will show you the enums/structures.

I think I missed this part, it will still be listed in the summary.

Best regards,
Paul.