Table Of Content (TOC) Headache - Please Help!

May 5, 2014 at 3:42 PM
Edited May 5, 2014 at 3:43 PM
Hello, this email is aimed mainly at the coordinator but also at whomever might help.

I have a problems with the Table Of Content (TOC) for which I'm not especially looking for an implemented solution meaning hints could do just fine.

The TOC I`ve managed to generate goes like this:
+Namespace1
      -Namespace1.Class1
                  -M:CompanyName.BranchId.Namespace1.Class1.Member1
      -Namespace1.Class2
-Namespace2
-Namespace3
Two here issues:

1. The class names are pre-fixed with the namespace name.
I must absolutely get rid of that.
2. The members are listed with full member names
The need is obvious here.

Again, any help or hint would be appreciated. I started looking in the XSL transform xml files and other places. Anthing that could shorten my journey would be highly appreciated.
Coordinator
May 5, 2014 at 5:08 PM
What presentation style are you using? Have you created your own presentation style? The above output is not typical of any of the presentation styles using the Help 1, Help 2, Help Viewer, or Website formats. Even in Open XML documents where the TOC you add would be generated off of the topic titles, class and member topic titles are not prefixed with the namespace.

Eric
May 5, 2014 at 6:36 PM
Edited May 5, 2014 at 6:36 PM
Thing is, I've created an utility inspired on AjaxDoc. (It's extensible, framework-agnostic/not locked on AJAX, has sophisticated error catching, etc...)

From there I've created an "OverrideDocSources" plug-in which allows what the name evokes.
(Because I couldn't predict if I would need to override the doc sources generation in the future, I split generation from the plug-in.)

The utility determines namespaces based on folder tree (this is specific to my needs), creates the VSDoc and Reflection XML files, validates them against schema.

So this is the context in which this output has been created. Additionally I use VS2013 as a presentation style.

Regarding Point 1:

The reason I assumed the namespace prefix was not my case specific is the existence of that thread.

Regarding Point 2:

The full member name might be due to my utility input or my plug-in (though I based it on the AjaxDoc plug-in, basically doing the same thing except doc files generation).

I`'m not looking for you to debug it for me. Again, hints are all I'm looking for.
May 5, 2014 at 6:55 PM
As a reference.

Here's a link to my log file.
I get a lot of ResolveReferenceLinks warnings since I presume it fails to find the assemblies/types in the application domain.

Back to debugging it!
Coordinator
May 5, 2014 at 9:52 PM
I guess it depends on what you're putting in the reflection information file. The XSL transformations use that to determine the topic title and metadata that is written to each one. In the case of the Help 1 and Website formats, the TOC title is pulled from the MSHelp:TocTitle element in the XML data island written to each topic by the transforms. If that's not there, the topic title from the <title> element is used. Note that you'd have to look in the working folder prior to the Sandcastle HTML Extract tool running to see what it will find since it strips out the XML data island once it's done processing each topic. Bear in mind that the intermediate TOC file will still show the fully qualified API member names. This has no bearing on the end result.

Eric
May 8, 2014 at 7:20 PM
Thanks for your input.

I first found the search for the MSHelp:TocTitle or input HTML elements in the SandcastleHtmlExtract MSBuild Task.
I have good reason to think that this is the place that determines the on-screen title as it outputs the first TOC xml
containing title information. Also there's a clear part that defaults the title to the id in case both title HTML elements are missing.

Then I realized on what SandcastleHtmlExtract bases itself. It`s obvisouly not reflection info hence the name 'SandcastleHtmlExtract'. I found it's the output of the XSL Transformations that mentioned. I could put in my words and please correct me, it would be SandCastle itself as a sub-module of SHFB.

I guess I had to go through all of it to make links from the explanations.

OK, here's me questions:

1-Do you know if there's a field I could add to the reflection info that would actually be used as the topics titles?
2-Otherwise what proper thing could I do somewhere in BuildProcessso SandcastleHtmlExtract sees titles.

FYI Right now I'm using WebSite type of output only.

Thanks
Coordinator
May 8, 2014 at 7:55 PM
Topic titles in the XSL transformations are generated of the reflection data. In some cases it's the member name alone but in others it can include parameter type information and/or generic type information. You'll see templates in the XSL transformations such as t_topicTitlePlain and t_topicTitleDecorated. Those would be the place to start with regard to how the titles are formatted. You can track down where they are called and either call new templates instead, pass other parameters to them that alter their behavior, or utilize new reflection elements that you've added within them to get the title format you want.

Eric
May 8, 2014 at 8:38 PM
Edited May 8, 2014 at 8:38 PM
OK thanks. It's up to me now, I'll hopefully be back with the solution.
May 9, 2014 at 6:03 PM
As promised.... I finally found the problem. Thing is, I took the whole beast apart to the bolts (believe me) to realize the issue was right under my nose.
I was building the api containers wrong in the reflection file. That's it.

At least I know more about SHFB than ever and if anyone have similar problem in the future, he`ll know what to do.

Please keep this in mind Eric, so we can spare a soul this trouble.

Thanks for your help!
Marked as answer by Olograph on 5/9/2014 at 10:03 AM