Generation Table of Contents for DocSite failed

Topics: DocSites, Features, General Discussion, General Questions
Jul 9, 2007 at 2:52 PM
Error:

Generate Table of Contents for DocSite System.InvalidOperationException: The Html Help Workshop TOC file is invalid.

Reason:

We have custom TOC, where are some topics without file (Local parameter). HHC compiles it without problem. In SandcastleHelpSystem class is check for local parameter and if not exists, exception is thrown.

Questions:

1. Is there a reason why are not supported topics without links? (I unterstand lack of time, I just want to know if there is some limitation)
2. Why is processed only first UL tag from hhc file when generating DocSite TOC ? (Same as above)
3. Why is DocSite TOC generated from HHC and not from buildhelp/toc.xml?

Regards

Grbo
Coordinator
Jul 9, 2007 at 4:10 PM
Hi Grbo,


1. Is there a reason why are not supported topics without links? (I unterstand lack of time, I just want to know if there is some limitation)

A topic's file is required because without it there would be dead links in the TOC and index. Also, a topic's file is used to key the topic so when you click on a link in the index it can synchronize the TOC. Without an associated file the default node would be selected in the TOC and the File Not Found page would be displayed in the IFrame.

But I'm interested in why you've created TOC nodes without associated files. Would you mind describing a usage scenario where this would be useful?

If this is something that you feel that DocProject should support then please let me know what behavior is desired for TOC entries and index entries without associated files and I'll definitely look into it.


2. Why is processed only first UL tag from hhc file when generating DocSite TOC ? (Same as above)

I'm not sure that I understand your question. Are you asking why only the root UL's children are parsed? This is simply because I thought that a TOC could only have one UL tag as the root. Do you have any reference that you could point me to that states otherwise?


3. Why is DocSite TOC generated from HHC and not from buildhelp/toc.xml?

When performing a partial build after modifying the .hhc file, the DocSite's DocSiteContents.xml file will automatically be synchronized with the changes. Secondary to that, Sandcastle is CTP and so the toc.xml file format could change, but the .hhc format probably won't.

HTH

Thanks,
Dave
Jul 10, 2007 at 8:04 AM
1.

Here is our structure

Library
About
Reference
namespace1
namespace2

and Reference topic has not file, it is only container in tree for namespaces.

2.

Library
About
Reference
namespace1
namespace2
Library 2
About
Reference
namespace3
namespace4

more than one topics in root (for example open MSDN Library) there is in root
Development Tools and Languages
Enterprise Servers and Development
...
Knowledge Base
Help on Help

3. OK, I unterstand

Regards: Grbo

PS: I can send you our solution for custom topics, it is automated build, you must not do manual steps.
Maybe it will be interesting for you for extending DocProject.
Coordinator
Jul 10, 2007 at 9:29 AM
Hi Grbo,

Thanks for the reply.

1. Ok, I get it. So in the DocSite if you click a node in the TOC that's not associated with a file it should just expand, without navigation. It's purpose would just be as a container of other nodes. I'll see about adding this feature in the next release.

2. I see, but in DocProject 1.6.2 you can certainly do that - just add more than one LI under the root UL instead of adding more root ULs.

3. Cool.

Thanks for offering a solution to custom topics but I'm going to have to pass on that for now. I've already figured out a few ways of doing it but I'm not looking for a hack - I'm looking for support in Sandcastle's standard build process such as the conceptual configuration that Microsoft uses internally.

On this subject there are already a few discussions here and on Sandcastle's forums, as well as DocProject work items and some blog entries that I've written in case your interested. Look for stuff about "custom topics" or "additional topics".

Basically, I'm not interested in modifying Sandcastle's toc.xml file, reflection.xml file or automatically merging .HHCs. I'm looking for a solution that is based on a build-process component and utilities or transformations provided by Sandcastle so that the process of producing conceptual content would be standardized and supported by Microsoft. And of course, I could spend some time writing them myself but that doesn't make sense either when I'm sure Microsoft will end up releasing theirs. (Hopefully in the next release!)

Thanks,
Dave
Jul 10, 2007 at 10:07 AM
Hi Dave,

Thanks for informations.
Looking forward for next releases (either sandcastle or docproject), because I don't like custom solutions too.

Regards

Grbo
Coordinator
Jul 10, 2007 at 1:01 PM
Edited Jul 10, 2007 at 1:01 PM
Hi Grbo,

FYI, I just blogged about additional topics in DocProject:

Adding Additional Topics Using DocProject
http://davesexton.com/blog/blogs/blog/archive/2007/07/10/AddingAdditionalTopicsUsingDocProject.aspx

- Dave
Coordinator
Jul 20, 2007 at 8:07 PM
This discussion has been copied to a work item. Click here to go to the work item and continue the discussion.