Table of Contents Lists HTML Titles, Not SiteMap Titles

Topics: User Forum
Oct 10, 2010 at 1:41 AM

I had all my table of contents titles specified in a sitemap, yet when I compile the help file, the titles in the table of contents are coming from the HTML file titles instead of the sitemap.  What's going on?

Coordinator
Oct 13, 2010 at 7:29 PM

The current release has some problems with HTML additional content files caused by changes in how the TOC is produced.  Since support for HTML and sitemap files has been deprecated for a while and the MS Help Viewer format cannot support them anyway, I'm recommending converting such files to MAML topics and using a content layout file which does work as expected and is supported by MS Help Viewer format.  An HTML to MAML converter is available at the Sandcastle Styles project site.

Eric

 

Oct 16, 2010 at 1:54 PM

I kind of liked the ability to post the HTML documentation online as well as having it compiled into the help file, but I guess I haven't used that much.  I'll give the converter a try.  Thanks.

Oct 17, 2010 at 2:43 PM

Looks like there's a lot of manual work to be done after performing a conversion.  I hope you can get me started with a few answers, and/or information on where I can look them up:

1. I have an image map that failed to upgrade automatically.  I have a _Media folder with two files in it: GfxEdit.PNG and _MediaFiles.xml.  _MediaFiles.xml contains:

<stockSharedContentDefinitions fileAssetGuid="a7e98e5c-9231-4940-b51d-caa514f904f2" assetTypeId="MediaContent">
  <item id="GfxEdit">
    <image file="GfxEdit.PNG">
      <altText>Graphics Editor</altText>
    </image>
  </item>
</stockSharedContentDefinitions>

I also have a file in the root of the project called GfxEdit.aml that contains this:

<content>
      <!-- TODO: Review markup -->
  <markup>
   <map id="GfxEditMap" name="GfxEditMap">
     <area shape="rect" coords="4,4,24,24" href="#FreeDraw" alt="Freehand Drawing" title="Freehand Drawing" />
     <!-- Lots of other area tags -->
     <area shape="rect" coords="191,326,520,471" href="#CellManager" alt="Cell Manager" title="Cell Manager" />
   </map>
  </markup>
  <mediaLink><image xlink:href="GfxEdit" /></mediaLink>
</content>

After looking around the site a bit, I found that I can make the image appear by changing the BuildAction to "Image" and setting CopyToMedia = True (not sure if that part is necessary).  Is that the right way to do it (the build output makes me suspect that this results in two copies of the image being included in the output file)?  But even then there are still no links on the image generated by the area tags.  And there are a bunch of warnings in the log like "Warning: Named anchor 'FreeDraw' needs review".  Great... what do I need to review exactly? :)

I tried adding <image src="GfxEdit.PNG"> before <map>, but that didn't fix it (didn't even cause another copy of the image to show up).

2. I had a number of links from the additional content into the generated content.  I have warnings like:

Warning: Unable to resolve topic link to 'html\M_GeneralRules_ShowMessage.htm'

And in the file are lines like:

<!-- TODO: Unknown topic link: html\M_GeneralRules_ShowMessage.htm -->
How can I resolve these to restore the links?  I tried replacing the comment with 
<link xlink:href="M_GeneralRules_ShowMessage.htm">
<!-- TODO: Unknown topic link: html\M_GeneralRules_ShowMessage.htm -->ShowMessage
</link>

But the link still doesn't work.  The full address of the page I'm trying to get to is mk:@MSITStore:C:\Users\Ben\Documents\Visual%20Studio%202010\Projects\SGDK20IDE\Help\SGDK2Help.chm::/html/M_GeneralRules_ShowMessage.htm

I also tried including the "html/" at the beginning of the href value.

3. I have a number of multi-level ordered lists in my additional content.  They used to use numbers for the top level and letters for the next level, but now they are using numbers for all levels.  Is there a way to control this so that the second level will use letters?

4. A large segment of one of my pages is colored blue like a link (and the blue ends at the end of the next link), but it is not a link.  I didn't see anything unusual in the AML file.  How do I figure out what's going on here and correct it?  It begins at a section heading (that is not a link nor is it next to a link, but has the same text as an earlier link).  I looked at the generated HTML in the help file and it doesn't look problematic.  It has <span sdata="link"> </span> around the links, and other <span> tags that are properly closed around the section headings.  There is a self-closed <a> tag marking the beginning of each section.

5. My ProjectSummary property (stored in the shfbproj file, presumably) has a bunch of HTML in it that didn't get converted.  It looks OK except for the fact that the code snippets are not formatted.  I guess they never were, but can/should I convert this to MAML format instead of HTML format, and would that allow me to format it as code?

I'm concerned that this conversion is presenting more problems than I can solve, (and still didn't fix the original problem -- showing the wrong title in the table of contents).  But if there are easy answers to most of these questions, I'll keep at it.

Coordinator
Oct 18, 2010 at 7:50 PM

The help file that comes with the converter describes the process that occurs and all of the resulting output.  There is a section in it that gives some information on what each of the common warning messages means and how to go about fixing up the potential issues (See The Conversion Process | Warnings and To Do items).  Most of the comments inserted by the conversion are simply there to draw your attention to something that may or may not need fixing.

There is no equivalent to an image map in MAML.  The converter wraps it in a markup element and inserts a comment to draw your attention to it so that you can review it and make sure it still works.  The Image build action is mainly for MAML images.  It ensures that they get copied to the right place if referenced in MAML topics.  If set to Image but CopyToMedia is false, the image won't get copied unless referenced in a MAML image element.  You can use it for other images too but do need to set CopyToMedia to True so that it gets copied if not used in a MAML image element which is the case with your image map element image.  If you include the image as a Content item, it gets copied to the resulting help file in the folder in which it resides in the project.  If treated as a MAML image, it always gets copied to the .\Media folder.  The _MediaFiles.xml file is for manual builds or tools that do not manage the images via a project.  SHFB handles the images so you can ignore the media content file produced by the conversion.  You'll need to update the image map element to include the appropriate folder on the image name.

 "Unable to resolve topic link" means the converted couldn't find the HTML file that was the link target.  In your case, it looks like you've got links to API topics.  In this case, you'd replace the link with a <codeEntityReference> element that links to the API topic.  These can be inserted into a topic from the Entity References window in the SHFB GUI.

Regarding the list item numbering/lettering, you'll probably have to alter the Sandcastle presentation stylesheet to get the effect that you want.  Just note that it may affect other places where nested lists are used (i.e. perhaps in API topics).

Regarding the link coloring on the bulk of the page, you probably haven't applied the Sandcastle Styles patch.  It fixes a number of issues like that.  You'll need to apply it for proper support of the markup element too.

Project and namespace summaries are not part of any MAML topic and thus use HTML rather than MAML elements.  Anything in the project and namespace summary properties gets inserted as <summary> elements thus you won't get colorized code.  If you want colorized example code in namespace comments, you'll need to use a NamespaceDoc class instead where you can use the full range of XML comments elements.  Since there is no namespace for the project summary, you'd have to manage those comments and code samples using a manually edited XML comments file.

Regarding the TOC title versus the topic title, you can set a different TOC title in the content layout file editor.  Select the topic in question and set the TocTitle property to the value you want to use.  If not set, it defaults to the standard Title property value.

Eric

 

Oct 20, 2010 at 2:57 AM

Copying the files from the Sandcastle Styles patch fixed a lot.  I thought that I wouldn't need it because I had just downloaded and installed Sandcastle and SHFB, but I guess the patch isn't incorporated into the latest installer.

1. I don't fully understand the nature of this "Content" build action.  I was guessing that I should be able to set the build action to "Content" for my image and then refer to it in the markup section, but I couldn't find any valid path to that image when build action was content.  So I switched it back to Image.  Now I can successfully refer to it by any of the following paths:

  <img src="media/GfxEdit.PNG" />
  <img src="Media/GfxEdit.PNG" />
  <img src="../Media/GfxEdit.PNG" />
  <img src="../media/GfxEdit.PNG" />

And, thanks, presumably, to the patch, all the links on the image map work.

2. Thanks for pointing me to the Entity References window!  This is a much easier way to insert links to my API topics... and it works!

3. Altering the Sandcastle Presentation style sheet stylesheet doesn't sound like an ideal solution (not to mention, I would have to learn how first).  This help file is part of an open source project, and having to tell others to update their SandCastle instsallation in order to properly compile the code seems iffy.  So let me approach this from another angle.  Is there another way to document procedures with top-level steps and details beneath each step?  I thought I saw something about a process template of some sort.  Should I consider using more than just the "developerConceptualDocument" template for my Conceptual Content or whatever it's called?  (I'm also a bit troubled by the fact that all my titles are small and the same size now whereas I used to have different level/size headings when it was HTML -- I feel like I'm missing something basic about MAML architecture here.)  I don't really understand conceptual content... can I be using other templates... I also saw something about a FAQ template and am wondering if I can use that for the FAQ page.

4. Patch fixed my link coloring problems.

5. I guess I'm still quite green when it comes to authoring help content in the modern world (or using Sandcastle/MAML).  You say something about using NamespaceDoc and an XML comments file.  What does this mean?  Do I add a new aml file to my project and put a NamespaceDoc tag in it somewhere?  Or add an XML file to my project or what?  (One wonders how I got this much help content written without knowing these basics I suppose.)

I got my table of contents worked out.  I figured it was simple so I had actually already fixed it.  I was just kind of nonplussed that I went through the whole conversion, and the fix I was looking for wasn't automatic :).  But it was easy enough.

Thanks for your help.  I think I'm almost to the point where I can figure the rest out on my own.

Coordinator
Oct 21, 2010 at 7:35 PM

The "Content" build action simply copies the associated file to the build folder so that it will get compiled into the help file.  If the file is at the root of the project, it will be in the root of the compiled help file.  If it is in a sub-folder, it will get copied to a like named sub-folder in the help file.  If in a folder, you do need to qualify any reference to it with the path.  Since the HTMl files are in a .\html folder, you generally need to use a relative path reference to locate the file (i.e. <img src="../GfxEdit.png" /> if at the root or <img src="../Media/GfxEdit.png" /> if in a folder called .\Media).

The "Image" build action is for images that are referenced in conceptual content topics via a mediaLink or mediaLinkInline element.  Since you don't specify a path in the MAML for those elements, all such images end up in the .\Media folder and the build component uses that folder when it renders the image link at build time (it converts the ID to a file path).  Unless forced by setting CopyToMedia to true, only images that are actually referenced in a topic get copied to the output folder and compiled into the help file.

Regarding the document procedures stuff, you can use a Walkthrough or How To topic type since they contain elements that represent procedures with numbered steps.

Regarding NamespaceDoc and a separate XML comments file, they are alternate ways of managing the namespace and project summaries.  See these topics for more info: Using NamespaceDoc classes and Sharing Project Summary and Namespace Comments.

Eric

 

Oct 24, 2010 at 2:21 PM

Solved: Content build action.  I have all my MAML content in a folder called MAML, so I had to use <img src="MAML/Media/GfxEdit.PNG"> when using the "Content" build action on GfxEdit.PNG.  Thanks.

Mostly Solved: NamespaceDoc. I created a class called NamespaceDoc in the default namespace (the project has no namespace), and the "dummy" NamespaceDoc class was documented as expected (I see there's a description on how to hide that), but those comments did not show up on the namespace page or the namespace root page.  Then I looked at your link about sharing project summary and namespace comments.  I removed the NamespaceDoc class and simply added an XML file to my documentation sources that contained the same XML as I had added in the code (nested within the "R:Project" member).  That worked pretty well.  I tried to add a table using <table>, <row> and <element> tags, but that didn't work.  And based on a little research (related to using the <img> tag in XML comments), it looks like I should be using html tags in my xml code docs instead of MAML tags, which would explain that problem.  So I tried replacing the <row> elements with <tr>, the <entry> elements with <td> and <th>, and the <tableHeader> element with <thead>.  That got the layout corrected, so now I just need to work on the styling (applying borders and background colors similar to the generated tables), which I think I can figure out. However, I am wondering if there is a way to merge the namespace root page and the default namespace page.  Currently, I have RootNamespaceContainer set to True so that I can set the title of the root page with RootNamespaceTitle.  But underneath that I have a node for the default namespace (containing everything) titled "Namespace".  I would like the ability to control the name of the root page, but also the ability to eliminate the unecessary level of hierarchy.  If I set RootNamespaceContainer to False, I eliminate the extra level of hierarchy, but I can't set the title of the "Namespace".  Is there a way to override the table of contents entry title for a namespace?

TBD: I see how I can add How To and Walkthrough topics to the project, but have yet to try this to convert one of my existing topics.  Thanks for the suggestion.  There are other cases where I lost some HTML formatting during the conversion to MAML, and I wonder what the general feeling about using the <markup> tag is in certain circumstances.  For example, I have a topic that has an image map at the top, and a whole bunch of headings below that are grouped into 3 general sections.  Right now the headings for these 3 major sections are the same size as the rest of the sub-headings, so it's kind of hard to navigate visually.  Should I be using a different template, or would it make sense for me to do something as simple as <markup><h2>My Title</h2></markup> instead of <section><title>My Title</title></section>?  (Or should I retain some of the <section> tagging?  Does it work to embed <markup> inside <title>?)

Coordinator
Oct 24, 2010 at 5:52 PM

In the content layout file, you can indicate which node acts as the parent to the API content (the Set API Insertion Point options on the toolbar and on the context menu when you right click on a topic in the layout file editor).  You can mark a topic as the point before or after which the API content is inserted or indicate that it will act as the parent topic to the API content (Content Placement Options)

MAML is used to apply structure to the topic.  The layout and styling is handled by the selected presentation style.  This gives the conceptual topics the same look and feel as the API topics.  The <markup> element support was added to provide a means to pass through small sections of HTML to handle stuff that isn't address in MAML such as image maps.  You're better off in the long run not trying to override individual element styles with <markup> elements as it's going to be more work to maintain especially if you are trying to be consistent across numerous topics.  You're better of modifying the Presentation.css file for the presentation style to fit your needs.  Changing it will apply the change to all topics automatically.

Note that if you add a .\Styles folder to the root of your SHFB project and place a copy of Presentation.css in it, it will get copied to the output folder during the build and will override the default presentation style's stylesheet file.  As such, you can make changes on a per project basis without affecting the default stylesheet supplied with Sandcastle (Replacing Stock Content).

Eric

 

Oct 25, 2010 at 2:07 AM

I already saw that the API content insertion point can be controlled.  My problem is that I can't seem to insert all the contents of the namespace without inserting a node called "Namespace" representing the default namespace (in which all my classes reside for this particular project).  I don't suppose there's any way to control that?

So if I want to have two levels of headings within a topic, what can I do?  The MAML doesn't seem to allow that.  Or can I use a different template to accomplish this?  I can understand how modifying the Presentation.css file will allow custom and centralized control of the styles, but I don't see how it could be used to add new styles if the MAML doesn't allow for it by distinguishing a new kind of content (namely a second level heading).  I basically want to nest sections (visually).  Could I accomplish a second level heading by applying a special style to sectionContent.subsectionTitle (for sections nested in other sections)?

Coordinator
Oct 25, 2010 at 6:04 PM

The reason you're getting a generic "Namespace" title is that the transformations generate the title based on the namespace containing the code.  Since the generic global namespace has no title, all you are seeing is the suffix that gets appended to the namespace.  If you have no other namespaces, you can add a resource item file to your project and replace the text of the namespaceTopicTitle item with a title of your choice (I think that's the one).

You can next a <sections> element within a <section> element to create sub-sections down to about two levels.  I believe it uses <h1> for topic level titles, <h2> for sub-sections and <h3> for sub-subsections.  Play with the styles as suggested to see what effect it has on the rendered topics.

Eric

 

Nov 4, 2010 at 11:20 AM

I think the resource item file will solve my first issue, allowing my to have just a single SDK root entry where my namespace would be, with all the contents immediately beneath it.

I'm still not seeing desired results for nested sections, though.  Am I nesting them wrong?

The following AML code:

<section><!--h2-->
  <title>File Menu</title>
  <content>

<section><!--h3-->
  <title>Import Graphic</title>
  <content>
      <para>Select any portion of an external image file to import into the
(with all tags later closed)

Generates this HTML:

<span class="subsectionTitle">File Menu</span>
<div class="subsection">
<span class="subsectionTitle">Import Graphic</span>
<div class="subsection">
<p>Select any portion of an external image file to import into the

So I'm not seeing any heading tags generated as you suggested would happen.

Nov 7, 2010 at 9:46 PM

After a little experimenting I have found that using the vs2005 presentation style does give the desired headings.  The prototype presentation style, however, does not seem to do any sort of levels with nested sections.  What is the Prototype presentation style?

Nov 8, 2010 at 11:23 AM

OK, back to the topic of the empty namespace name.  How to I create a link to this root namespace node?  The following is what the Entity References tab generates, but it doesn't work:

<codeEntityReference qualifyHint="false">N:</codeEntityReference>

 

Coordinator
Nov 9, 2010 at 3:34 PM

The Prototype style was the original style used by Sandcastle when it was first released.  Hana was an experiment that never really went anywhere.  VS2005 is the style that eventually replaced both.  The others don't get updated anymore and they are missing a lot of support for MAML content.  With the release of the latest version of Sandcastle they have been effectively deprecated as they do not support the MS Help Viewer output at all.

Regarding the root namespace page, try "R:Project" as the ID rather than "N:".

Eric

 

Nov 11, 2010 at 11:25 AM

I tried using R:Project and this caused the help file to output (in bold and brackets) [R:Project] in its place with no link.  I thought this might be because I had set RootNamespaceContainer to False.  So I tried setting it to true.  Now I can't even build due to the following error message:

 Unhandled Exception: System.InvalidOperationException: Operation is not valid due to the current state of the object.
     at Microsoft.Ddue.Tools.LinkTextResolver.WriteTarget(Target target, DisplayOptions options, XmlWriter writer)
     at Microsoft.Ddue.Tools.ResolveReferenceLinksComponent2.Apply(XmlDocument document, String key)
     at SandcastleBuilder.Components.MultiFormatOutputComponent.Apply(XmlDocument document, String key)
     at Microsoft.Ddue.Tools.BuildAssembler.Apply(IEnumerable`1 topics)
     at Microsoft.Ddue.Tools.BuildAssembler.Apply(String manifestFile)
     at Microsoft.Ddue.Tools.BuildAssemblerConsole.Main(String[] args)

The line immediately before this is:

  Info: BuildAssembler: Building topic 9cc40393-eb18-4a5d-b579-a2006b78e398

This is the GUID of the topic containing the link.

Coordinator
Nov 11, 2010 at 4:20 PM

The namespace list page isn't really a member so it may not be possible to link to it.  The above was a guess since I haven't done it before.  If you can find the page name for it, you could use an externalLink element to link to it.

Eric

 

Nov 13, 2010 at 6:08 PM

Thanks, that works.

<externalLink>
  <linkText>root page of the coding reference</linkText>
  <linkUri>N_.htm</linkUri>
  <linkTarget>_self</linkTarget>
 </externalLink>