Conceptual Content within namespace

Topics: Developer Forum, User Forum
Jun 27, 2008 at 4:02 PM
Hi
I am using the SHBH to create a help for my project. I want to know following things
1. How to add the Conceptual Contents within namespace. Right now there are two options available - AboveNamespace and BelowNamespace. But I want something like below

My Product
    - Overview
    - Getting Started Tutorial
    - Programming Reference  <-- This is where I want to embedd my namespace.

How to achieve this?

2. How to insert the link to namespace topics into my conceptual content? Like I want to give see also referene and link to classes from the namespace. How do I achieve this?

Please respond me as I am stuck at this point.

Thanks
Amol
Coordinator
Jun 27, 2008 at 7:42 PM
In the conceptual content editor, you can mark a conceptual content node as the split location (the toolbar button that looks like a page split in two or the Split Table of Content option on the Content menu).  Items before it appear above the reference content and the marked item and those below it appear below the reference content.  Then, using the RootNamespaceContainer project property you can get the reference content to appear in its own folder.  You can use the RootNamespaceTitle project property to give it a title other than "Namespaces" if you like.  Note that the split option can only be applied to root-level topics.  You can't place the reference content in a conceptual content sub-folder.  For that, you'd need to write a plug-in.

Regarding #2, you can use <codeEntityReference> elements within conceptual topics to link to the reference topics.  If using the SHFB content editor, hit F3 or select Code Entity Search from the Window menu to open the search pane.  From there you can search for elements and then drag and drop them into the topic to create the links automatically.  For more information on how the links are constructed, see the MAML Guide which is available at the Sandcastle Styles project site.

Eric
Jun 28, 2008 at 6:43 PM

Thanks for the prompt response Eric

I tried the solution for the first problem but it seems like there is something wrong. I splited the TOC. But it is not giving me the desired output. I will explain u what exactly I am doing.

My project has an assembly which exposes some classes and APIs. I am generating a help for the project that documents the classes and API, the tutorial on how to use API. The TOC should look like below.

My Project SDK  <--- Contains the welcome note.

     - Conceptual overview  <---- Overview of my project

     - Getting started tutorial  <--- Help on how to start using the project kit

     - Programming Reference <--- Help on all the classes and APIs exported by the namespace,

I have created first 3 pages as conceptual content and I am planning to display the namespace on the programming reference page. I splitted the 'My Project SDK' node. In SHFB I set the RootNamespaceContainer property to true and I set the name of the namespace in RootNamespaceTitle. The output chm file is showing the only the namespace node, not any conceptual content. This is how my project output looks

MyOutput.MyProject.MyNamespace
  - class1
   -class2

Please suggest me something.

Thanks
Amol



 


EWoodruff wrote:
In the conceptual content editor, you can mark a conceptual content node as the split location (the toolbar button that looks like a page split in two or the Split Table of Content option on the Content menu).  Items before it appear above the reference content and the marked item and those below it appear below the reference content.  Then, using the RootNamespaceContainer project property you can get the reference content to appear in its own folder.  You can use the RootNamespaceTitle project property to give it a title other than "Namespaces" if you like.  Note that the split option can only be applied to root-level topics.  You can't place the reference content in a conceptual content sub-folder.  For that, you'd need to write a plug-in.

Regarding #2, you can use <codeEntityReference> elements within conceptual topics to link to the reference topics.  If using the SHFB content editor, hit F3 or select Code Entity Search from the Window menu to open the search pane.  From there you can search for elements and then drag and drop them into the topic to create the links automatically.  For more information on how the links are constructed, see the MAML Guide which is available at the Sandcastle Styles project site.

Eric



Coordinator
Jun 28, 2008 at 8:40 PM
Seems like an obvious question but I have to ask: Did you add your topics to the ConceptualContent project property?  If you see "3 topic(s)" listed in its property description and the Topics sub-property then they are there and should be showing up.  You should also see them if you open up the conceptual content editor.  You might check the build log too to see if there's something going on in there too.

Eric
Jun 28, 2008 at 9:15 PM

Eric

I have added topics using the ConceptualContent property. It shows the "3 topic(s)" in property description but under Topics sub-property it shows "1 topic(s)" . If I send u my project, could you have a quick look at it and let me know if I am missing anything?
Thanks
Amol


EWoodruff wrote:
Seems like an obvious question but I have to ask: Did you add your topics to the ConceptualContent project property?  If you see "3 topic(s)" listed in its property description and the Topics sub-property then they are there and should be showing up.  You should also see them if you open up the conceptual content editor.  You might check the build log too to see if there's something going on in there too.

Eric



Coordinator
Jun 29, 2008 at 12:07 AM
That would be fine.  My e-mail address is in the About box and the footer of the pages in the help file.

Eric
Jun 29, 2008 at 4:07 AM
Eric

I have forwarded you my project. Please have a look at it and let me know what wrong I have done.

Thanks
Amol

EWoodruff wrote:
That would be fine.  My e-mail address is in the About box and the footer of the pages in the help file.

Eric



Coordinator
Jul 1, 2008 at 1:23 AM
There's a bug when the first conceptual content item has the split TOC option enabled on it.  See work item http://www.codeplex.com/SHFB/WorkItem/View.aspx?WorkItemId=17207

Eric
Jul 1, 2008 at 1:31 AM
Thanks for your feedback Eric.

Is there any chance of getting this bug fixed in near future?
Thanks
Amol

EWoodruff wrote:
There's a bug when the first conceptual content item has the split TOC option enabled on it.  See work item http://www.codeplex.com/SHFB/WorkItem/View.aspx?WorkItemId=17207

Eric



Coordinator
Jul 1, 2008 at 3:40 AM
Edited Jul 1, 2008 at 3:41 AM

I'm in the middle of overhauling the project format at the moment so it may be a few weeks.  I'm converting the project system to use an MSBuild project file format for a future release that will include Visual Studio 2008 integration.  I'll have an alpha release out for the existing standalone GUI once I get the project format stuff done that include the fix.

Eric

 

Jul 1, 2008 at 6:43 PM
Eric

just for learning purpose I added one more root topic in the conceptual content. So I have two root topics now. I splited the second topic but it is not getting added under the root namespace. In the chm file there are three root topics. Two conceptual root topics and one namespace topic.What would be the problem?

Also when I use the codeEntityReference from the conceptual content to refer the class/method from my namespace, it is not showing as the link. In chm file the class is getting displayed without hyperlink like any other word. In the code entity search box the class is available. When I refer any system class then the link works fine.

Amol

EWoodruff wrote:

I'm in the middle of overhauling the project format at the moment so it may be a few weeks.  I'm converting the project system to use an MSBuild project file format for a future release that will include Visual Studio 2008 integration.  I'll have an alpha release out for the existing standalone GUI once I get the project format stuff done that include the fix.

Eric

 




Coordinator
Jul 1, 2008 at 7:09 PM
With only two topics, the split issue probably manifests itself on the last item as well.  You probably need three or more root entries with the split set on anything but the first or last topic.  Regarding the codeEntityReference, be sure you fully qualify the name or it won't find it.  The easiest way to create them is to use the Code Entity Search pane and drag one from there and drop it in the topic.

Eric
Jul 1, 2008 at 8:00 PM
Eric

Now I tried it with more topics and tried to split the middle topics. ContentPlacement option is set as BelowNamespace. The RootNamespaceContainer option is True and RootNamespaceTitle is set. CollectionTocStyle is set as 'Hierarchical' and the 'Hierarchical Table of Content' plugin is disabled. Still all the topics are listed as the flat. The output is as below

AA
BB
MyNamespace
MyProject  <-- This was splitted in the Conceptual Content Editor
YY
ZZ

I had expected something like
AA
BB
MyNamespace
    - My Project
    - YY
    - ZZ

And regarding the codeEntityReference I am using the Code Entity search pane to drag and drop in the topic. But seems like it only works with the classes and methods available under System namespace. When I drag class/method from my namespace, the output Chm file doesnot show the hyperlink for my class / method.

Seems like I am doing something wrong. If u want I can forward u the project one more time. Please suggest me the solution.

Thanks
Amol


EWoodruff wrote:
With only two topics, the split issue probably manifests itself on the last item as well.  You probably need three or more root entries with the split set on anything but the first or last topic.  Regarding the codeEntityReference, be sure you fully qualify the name or it won't find it.  The easiest way to create them is to use the Code Entity Search pane and drag one from there and drop it in the topic.

Eric



Coordinator
Jul 1, 2008 at 10:14 PM
CollectionTocStyle has no effect on the help file TOC.  It just defines how the help file's TOC will appear when merged with a Help 2 collection.  As I noted earlier, there is no way to have your topics merged into the root namespace container with the reference topics.  You'd have to create a plug-in to do that.  The split option simply specifies where the split occurs.  Topics before the split appear above the refrence content and the split item and those following it appear after the reference content but they are all at the root level.  Also, when using the split option, the ContentPlacement project property has no effect since the split option overrides it.

I can't see any reason why the code entity references shouldn't work so go ahead an send me the project and I'll take another look at it.

Eric
Jul 2, 2008 at 3:15 PM
Eric
I got the codeEntityReference working. I had set the ProjectLinkType property as Index as a result it was not working in CHM file.
I have one doubt. As per documentation if I want to generate multiple help file format and if I want to use the Index for Help 2 format, it will need to be placed in seperate project file. Does it mean that I need to create seperate project for Help 1 format and Help 2 format? Ad using the Addition Reference Links plugin merge the build process for both?

Regarding creating the new plugin for my requirement, do u have sample plugin code which I can refer?

Thanks
Amol


EWoodruff wrote:
CollectionTocStyle has no effect on the help file TOC.  It just defines how the help file's TOC will appear when merged with a Help 2 collection.  As I noted earlier, there is no way to have your topics merged into the root namespace container with the reference topics.  You'd have to create a plug-in to do that.  The split option simply specifies where the split occurs.  Topics before the split appear above the refrence content and the split item and those following it appear after the reference content but they are all at the root level.  Also, when using the split option, the ContentPlacement project property has no effect since the split option overrides it.

I can't see any reason why the code entity references shouldn't work so go ahead an send me the project and I'll take another look at it.

Eric



Coordinator
Jul 2, 2008 at 6:44 PM
If you want to generate Help 1 and Help 2 files, you can either use two separate projects each with the same info but with a different HelpFileFormat and ProjectLinkType settings.  The other option is to use one project file and then build it using SandcastleBuilderConsole.exe and override the property settings using command line parameters.  You could build both help files from the command line once without the property overrides and once with them.  That would be simpler.

The additional reference links plug-in is only used for  linking to content in a totally separate help file.  For example, you build product one's help file and product two's help files separately.  Product one needs links to items in product two's help file.  That's when you'd use the additional reference links plug-in.  It doesn't apply to different versions of the same file.

See the SHFB code for working examples of plug-ins.  There's also a starter plug-in example in the help file.

Eric