Linking Conceptual Content with library help sytem

Question

 

Hi,

 

I have a sample conceptual content, and using sandcastle i am able to generate the .chm file. In this conceptual content i want few link which is pointing to my library (.dll) help file which i have created separately using sandcastle.

 

• Is it possible to integrate, i tried all short cuts but, nothing seems to be working.
• I have lot of CodeEntityReference tag those are not working. what could be the issue. (i am using conceptual sample which comes with sandcastle Oct 07 CTP).
• Sandcastle help file Builder (SHFB) tool is also used for building conceptual , how could do that is there any instructions.

Please throw some light on this conceptual help stuff.

 

Thanks,

Naveen

 

Answer 1

Hi Naveen,

 

Check out this forum thread:

 

Conceptual Help: Links

http://forums.microsoft.com/MSDN/ShowPost.aspx?PostID=2500167&SiteID=1

 

In it you'll find a working Sandcastle conceptual configuration file (conceptual.config) that I've used to successfully link to Framework topics and local reference topics using both the <codeEntityReference> and <link> linking styles.

 

- Dave

Answer 2

Hi Naveen,

 

I just tried linking to a reference topic from a conceptual topic without first creating an XML companion file and, as expected, it didn't work.  But then I tried to use an HTML hyperlink, <a href="html/guid-name.htm" />, but surprisingly that didn't work either.  It appears that the conceptual XSL transformations strip unknown HTML tags (just like the reference transformations) but some of the common tags, such as <a>, are not passing through.

 

Anand,

 

Could you please have the transformations pass through the same HTML tags in conceptual topics as are passed through in reference topics?

 

And is there any way to have links such as the following work so that the GUID isn't required in the link:

 

<link xlink:href="T:MyNamespace.MyClass">My Class</link>

 

Thanks,

Dave

Answer 3

Hi Naveen,

 

I was looking through the other thread and I noticed that the conceptual.config file that I posted is missing something if you want to use <codeEntityReference> tags to link to your library's local reference topics:

 

conceptual.config

<!-- resolve reference links -->

<component type="Microsoft.Ddue.Tools.ResolveReferenceLinksComponent2" assembly="%DXROOT%\ProductionTools\BuildComponents.dll">

  <targets base="%DXROOT%\Data\Reflection\" recurse="true" files="*.xml" type="msdn" />

  <targets files=".\reflection.xml" type="local" />

</component>

 

 

So it appears that the best way to link to local reference topics from within conceptual topics in the Sandcastle Oct. 2007 CTP is to add the highlighted <targets> element above to your conceptual.config file (it should point to the reference reflection file) and then use <codeEntityReference> tags within the documentation:

 

<codeEntityReference>T:MyNamespace.MyClass</codeEntityReference>

 

Alternatively, using the XLink style with an XML companion file gives an author control over the actual text value of the hyperlink; however, it's not practical since it requires GUID file names, which must be known ahead of time, and XML companion files must be generated for all reference topics as well.

 

- Dave

Answer 4

 

Hi Dave,

 

Thanks for the posting, i am able to get the library help system integrated to conceptual .chm file

 

Important note:

 

conceptual content is built based on VS2005 folder and style structure. if we create assemblies help system either in hana/Prototype style then there will be style/script mismatch. the links will be created but, when click the link the page will be load without style and throws javascript error.

 

command in build_Conceptual.bat :

call "%DXROOT%\Presentation\vs2005\copyOutput.bat"

 

 

Thanks,

Naveen

Answer 5

Hi Naveen,

 

Did you try replacing "vs2005" in the path with either "prototype" or "hana" to see if it works?

 

Anyway, have you tried using a tool that can automate Sandcastle?  See this article for links to software that will allow you to concentrate more on authoring and managing documentation instead of fiddling with Sandcastle's build process:

 

Sandcastle Help, Open Source GUIs for Sandcastle

http://www.codeplex.com/DocProject/Wiki/View.aspx?title=Sandcastle+Help#OpenSource

 

- Dave

Answer 6

Where is the conceptual.config file or how is it to be created?

I am using VS2010 ultimate and the latest Sandcastle via SandcastleStyles.

Answer 7

See my reply here: http://sandcastlestyles.codeplex.com/discussions/392804

Eric