Customizing TOC and Type/Method Signatures

Topics: General Questions, Sandcastle
Nov 29, 2008 at 9:38 PM
Hiya, I'm new to Sandcastle and DocProject...and I'm very impressed with it...there are however 2 things I can't figure out...
1.  The signatures for types/methods in titles/TOC all seem to follow vb (I'm guessing) syntax....how do I change this to C#?  (for example generic type params display in ()'s instead of <>'s)...I'm not talking about customizing the 'Syntax' section, I've already disabled VB/JS from there, but the titles/toc still display in vb-like syntax.
2.  I played a bit with SHFB and it had a feature to let me specify which namespaces are listed in the TOC and which ones are heirarchial.  Is this possible in DocProject?  I'd like to be able to say 'make a TOC entry for all 2nd-level namespaces, and nest any 3+ level namespaces'...if you know what I mean....the default 1 TOC entry per namespace is a little inconvienient, because on a large project it's a huge list and a little overwhelming/scrolly :P
Nov 30, 2008 at 7:59 AM
Hi,

> The signatures for types/methods in titles/TOC all seem to follow vb (I'm guessing) syntax

Yes, Sandcastle uses VB-like syntax for the text in TOC titles and topic headers (it's referred to as, "language neutral syntax" in the XSLT comments).

DocProject uses Sandcastle's ChmBuilder utility to generate the Help 1.x TOC file (.hhc) but it doesn't support any switch to control the syntax style of TOC titles.

Header titles, on the other hand, are actually hooked up to the language filter (drop-down at the top).  When more than one language is selected, language neutral syntax is shown (this is the default).  But if you select C# and exclude the other languages then you'll see that the topic's title will change to use C# syntax instead (done via JavaScript).  This functionality is built-in to Sandcastle's VS 2005 presentation style - I'm not sure about the others at the moment.

>  I played a bit with SHFB and it had a feature to let me specify which namespaces are listed in the TOC and which ones are heirarchial

The current version of DocProject does not provide any tools for rearranging the reference TOC from within Topic Explorer, but there's a related work item for this:

http://www.codeplex.com/DocProject/WorkItem/View.aspx?WorkItemId=15220

The TOC is an XML file that is generated during the build process, so you may be able to inject a dynamic build step (using your project's Build Process Component) that moves nodes around with the XML DOM classes to get the desired arrangement.

I was going to post a working example that uses a simple LINQ to XML transformation, but I discovered a bug in VS 2008 that prevented me from doing so (fatal execution engine error w/ crash to desktop):  https://connect.microsoft.com/VisualStudio/feedback/ViewFeedback.aspx?FeedbackID=337149

So it seems that even if you're using VS 2008 you'll still have to use the legacy System.Xml.XmlDocument to manipulate the XML.

I tried several different approaches but it always resulted in a crash when using LINQ to XML.  It's a good starting point though, so here's what I had up until the crash.  Note that I had to add two assembly references as well: System.XML and DaveSexton.DocProject.Sandcastle (typically found in, C:\Program Files\Dave Sexton\DocProject\bin\).

public override void BuildStarting(BuildContext context)

{

  // Uncomment the following line to break into the debugger:

  // System.Diagnostics.Debugger.Break();

 

  buildStart = DateTime.Now;

 

  SandcastleSettings settings = (SandcastleSettings) context.Engine.Settings;

  string tocFile = settings.TocFile;

 

  base.InsertBeforeBuildStep(

    (settings.BuildConceptualTopics)

      ? "Build Assembler {conceptual.help1x.config}"

      : "Build Assembler {sandcastle.help1x.config}",

    "Arrange TOC", true, false, false,

    stepContext =>

    {

      XDocument document = XDocument.Load(tocFile);

 

      document = ArrangeToc(stepContext, document);

 

      if (document != null)

        document.Save(tocFile);

    });

}

 

private XDocument ArrangeToc(BuildContext context, XDocument document)

{
  // dump the TOC to the VS output window

  context.TraceLine(document.ToString());

 

  // identity transformation

  return new XDocument(document);

}

<!--EndFragment-->
If VS crashes for you then comment out all of the XDocument stuff and replace it with equivalent XmlDocument code.  I didn't go that far with it myself but it should work.

- Dave
Nov 30, 2008 at 6:09 PM
Awesome!  Thanks alot....that's a big help. 

There's 1 more thing I've ran into that I can't figure out....I'm generating help v2 for integration into VS....the generation seems to succeed fine after about 8 hours (it's quite a large project - the generated HxS file is about 85MB)...but when I view it only about a 3rd of my indexes are there ('A' through 'I')....am I hitting some sort of limit or is something going wrong?....any ideas how I would go about debugging this?
Nov 30, 2008 at 8:58 PM
Hi,

I've never worked with such a large documentation set before so I can't be sure, but it seems like that would be a problem with the Help 2.x system and not Sandcastle or DocProject.  The reason is that Sandcastle doesn't generate an index file for Help 2.x.  Instead, Help 2.x generates the index by pulling keywords from metadata found in the actual topic files.  The keywords are inserted by Sandcastle but it seems unlikely that it would stop generating them after 'I' since it generates them one topic at a time, and not in alphabetical order either.

I recommend posting this question on the Microsoft Developer Documentation and Help System forum.  If you discover that a particular process or setting for building Help 2.x documentation is missing in DocProject then I'll certainly consider it for a future release.

Before you post, you may want to search the .htm files (found in your project's Help\Html2 folder, which is probably not visible in Solution Explorer) for a few of the keywords that are missing in the Help 2.x index.  Look for the <MSHelp:Keyword> elements within the <xml> island of the topic's <head> element.  If you can't find any of the missing keywords in the actual topic files then maybe it's a Sandcastle or DocProject issue after all.

- Dave
Dec 4, 2008 at 8:40 PM
so yeah...I've posted on the MS forums about the keywords...no success so far http://social.msdn.microsoft.com/Forums/en-US/devdocs/thread/cd224170-4aa6-4d53-9030-cef98eacd369 ...and I've got the TOC customization working nicely, but there's a small polishing issue I can't quite figure out...on my custom TOC I have it so 3+ level namespaces are being nested underneath the second level namespace...but when the second-level namespace doesn't have any types directly in it there is no TOC entry made for that namespace (even tho there are multple 3rd-level namespaces off of it)....so....I'd like to create one.  I dunno if there's an easy way I could just add a 'namespace description' or something somewhere which would cause that node to be automatically generated (without actually moving any types into it)....or I could add a dummy entry pointing to a dummy page "there is no info for this topic" or something...what would be the best approach?

Thx
- Chris
Dec 5, 2008 at 1:13 PM
Hi Chris,

Sorry to hear that you haven't found a solution to the keyword issue.  I suggest trying Namespace#, yet another tool that may help.

I'll try to reproduce the problem with an empty namespace TOC entry later and get back to you.  For now though I'll agree that your solution to create custom namespace description topics (a bit more work) or a global "missing" topic (a bit less work) are the best approaches.

- Dave
Dec 5, 2008 at 3:27 PM
Don't get me wrong...I don't think it's a bug that the second-level namespace isn't being generated...it makes sense for what the current design is....it just doesn't play nicely with what I'm doing :)

- Chris