<example><code source="{path}" lang="C#/></example> supported ?

Topics: Extensibility, Features, Sandcastle
May 27, 2008 at 8:25 AM
Hi first of all - I would like to say GREAT TOOL - Thanks.

I trawled all the posts on this forum and google to see if you already answered this but couldn't find anything. Hence, can i hassle you ?


In my source code I have the following lines on most classes..

/// <example>
///  <code source="{path}" lang="xml" />
///  <code source="{path}" lang="C#" />
/// </example>

The reason i do this is because my sample code is quite long and dont want it messing up my source code. (its also pre-generated to a known folder by a build process from a set of unit tests).

When i run Help File Builder it works like a dream. However, DocProject just ignores it. Is this somethign Help File Builder supports and DocProject doesn't ? If so, do you have a workaround to achieve the same ?

Cheers
Mark
May 27, 2008 at 12:49 PM
Hi Mark,

SHFB has a custom build component that provides that functionality.  I've chosen not to implement it in DocProject since Eric Woodruff, the author of SHFB, has made his build components available as a separate download called Standalone Sandcastle Build Components.  They should work in DocProject as well.

How To Use Third-Party Build Components In DocProject
http://www.codeplex.com/DocProject/Wiki/View.aspx?title=How%20To%20Use%20Third-Party%20Build%20Components%20in%20DocProject

- Dave
Jun 27, 2008 at 9:37 AM


mark_q_jones wrote:
Hi first of all - I would like to say GREAT TOOL - Thanks.

I trawled all the posts on this forum and google to see if you already answered this but couldn't find anything. Hence, can i hassle you ?


In my source code I have the following lines on most classes..

/// <example>
///  <code source="{path}" lang="xml" />
///  <code source="{path}" lang="C#" />
/// </example>

The reason i do this is because my sample code is quite long and dont want it messing up my source code. (its also pre-generated to a known folder by a build process from a set of unit tests).

When i run Help File Builder it works like a dream. However, DocProject just ignores it. Is this somethign Help File Builder supports and DocProject doesn't ? If so, do you have a workaround to achieve the same ?

Cheers
Mark

hi, Mark, have you resolved this problem? I wonder how since i can't add the Build Components to DocProject. What's the detail steps?

Many thanks to you in advance.

Jun 27, 2008 at 1:42 PM
Hi,

I am also interested in this issue, having used and been impressed with the code block component in SHFB, I was hoping to use it within DocProject. However, attempting to add SandcastleBuilder.Components.dll as a custom build component to the Help 1.x build component stack results in a loader exceptions error.

Many tia for any help, Harvey
Jun 27, 2008 at 2:04 PM
Hi,

Do you get the "loader exceptions" while adding the component or during builds?  What is the exact error message?

Please check the Application event log for more detailed information about the error.  See How to Diagnose and Resolve Issues for help finding the log.

If the error occurs while building, enable full tracing for Build > Build assembler options in the DocProject Properties window and send the build trace from the Output window to me so that I can see what's happening.  (Contact me and I'll respond with my email address.)

- Dave
Jun 28, 2008 at 4:07 AM


davedev wrote:
Hi,

Do you get the "loader exceptions" while adding the component or during builds?  What is the exact error message?

Please check the Application event log for more detailed information about the error.  See How to Diagnose and Resolve Issues for help finding the log.

If the error occurs while building, enable full tracing for Build > Build assembler options in the DocProject Properties window and send the build trace from the Output window to me so that I can see what's happening.  (Contact me and I'll respond with my email address.)

- Dave

There are not  any  information in the event log. When i add the SandcastleBuilder.Components.dll from the packet Sandcastle Standalone Build Components , only an error box turn out saying:" Unable to load one or more of the requested type. Retrieve the LoaderException property for more information". So i can't load this compoment
Jun 28, 2008 at 2:51 PM
Hi, 

What steps can I take to reproduce the problem?  I recently wrote a new build component to test the build component stack editor (DocProject Propertiesbuild component stack (...)) and I was able to add it and build without any issues.

Are you adding the component using one of the build component stack dialogs and getting the error when you click OK?

If yes, then instead try adding the component directly to the appropriate configuration files in your project's Help\Presentation\Style\Configuration folder and let me know if you can build at least.

- Dave
Jun 28, 2008 at 7:03 PM
Comments in line, thank you, davedev


davedev wrote:
Hi, 

What steps can I take to reproduce the problem?  I recently wrote a new build component to test the build component stack editor (DocProject Propertiesbuild component stack (...)) and I was able to add it and build without any issues.

Are you adding the component using one of the build component stack dialogs and getting the error when you click OK?

>>Yes, I take the same steps as you point out, and i choose the Help 1.x reference build componment stack to load the componment.
>>1.Click the ..., an dialogue was opened
>>2. Click +, another dialogue named as "Add build Compnment" open, then i click the browse button to navigate to the >>SandcastleBuilder.Components.dll, open, then the  error came out as i have said.


If yes, then instead try adding the component directly to the appropriate configuration files in your project's Help\Presentation\Style\Configuration folder and let me know if you can build at least.

>>Yes, when i try to add it manually by change the sandcastle.help1x.config, it works correctly

 <!--SHFB Code Block Component. This must appear before the TransformComponent-->
        <component type="SandcastleBuilder.Components.CodeBlockComponent" assembly="I:\Aquarius\Sandcastle Help File Builder\SBComp_v1700\SandcastleBuilder.Components.dll">
          <basePath value="..\SandcastleComponents" />
          <languageFilter value="true" />
          <colorizer syntaxFile="I:\Aquarius\Sandcastle Help File Builder\SBComp_v1700\highlight.xml"
          styleFile="I:\Aquarius\Sandcastle Help File Builder\SBComp_v1700\highlight.xsl"
          copyImageUrl="I:\Aquarius\Sandcastle Help File Builder\SBComp_v1700\CopyCode.gif"  numberLines="false" outlining="false" keepSeeTags="false" tabSize="0" defaultTitle="true" />
        </component>

<!--SHFB Post-transform component configuration. This must appear after the TransformComponent. See also: CodeBlockComponent. -->
        <component type="SandcastleBuilder.Components.PostTransformComponent" assembly="I:\Aquarius\Sandcastle Help File Builder\SBComp_v1700\SandcastleBuilder.Components.dll" >
          <!-- Code colorizer files (required). Attributes: Stylesheet file (required) Script file (required) "Copy" image file (required) -->
          <colorizer stylesheet="I:\Aquarius\Sandcastle Help File Builder\SBComp_v1700\highlight.css" scriptFile="I:\Aquarius\Sandcastle Help File Builder\SBComp_v1700\highlight.js" copyImage="I:\Aquarius\Sandcastle Help File Builder\SBComp_v1700\CopyCode.gif" />
          <!-- Base output path for the files (required). This should match the parent folder of the output path of the HTML files (see SaveComponent). -->
          <outputPath value="Output" />
          <!-- Logo image file (optional). Filename is required. The height, width, altText, placement, and alignment attributes are optional. -->
          <!--logoFile filename="I:\Aquarius\Sandcastle Help File Builder\SBComp_v1700\Logo.jpg" height="64" width="64" altText="Test Logo" placement="left" alignment="left" /-->
        </component>



- Dave


Jun 28, 2008 at 10:47 PM
Edited Jun 28, 2008 at 10:48 PM
Hi,

Thanks for the reply.

The solution is to open up DocProject's config file (commonly found at, C:\Program Files\Dave Sexton\DocProject\bin\DaveSexton.DocProject.dll.config) and add the following element as a child of the configuration\addin\dependencies element.

<add name="SyntaxComponents" assembly="%DXROOT%\ProductionTools\SyntaxComponents.dll" />

Restart Visual Studio and you should be able to add the component now.

The reason that this is necessary is because SyntaxComponents.dll is not in the GAC and it's referenced by Eric's CodeBlockComponent.  By adding this line DocProject knows about the dependency and resolves it automatically from within VS's process when the assembly is needed (delayed loading).

Please let me know if this works for you.  I'll make sure that the config is updated for the next release.

- Dave
Jun 30, 2008 at 7:29 AM
Edited Jun 30, 2008 at 7:30 AM
After add the dependencies  to the DaveSexton.DocProject.dll.config, there are not any exceptions came out, but the code block componment are not added into the sandcastle.help1x.config.

Another Problem: When i add the code block componment to the  sandcastle.help1x.config manually, it works well for me, the generated help file can display the code example, but the link to the script and css are not correctly resolved. The code is not rendered and the copy picture don't exist. You can get more info here http://www.codeplex.com/SHFB/Thread/View.aspx?ThreadId=15504
Jun 30, 2008 at 8:54 AM
Edited Jun 30, 2008 at 9:00 AM

Hi,

Did you click the Save All tool bar button in Visual Studio after you added the component
?  You must use Save All in order for the changes to be saved.  (Note that VS can also be configured to save changes automatically before each build - I think that this setting is typically enabled by default.)  Also realize that if you update the config file manually after using the stack editor it will not know about your changes - if you add or configure another component using the stack editor your manual changes will be overwritten the next time that you click Save All or build.  For this reason it's best to use either the editor or manual configuration, but not both.

I looked at the details of your second problem and I think the issue is that you haven't configured Help 1.x to import the necessary files that are required by Eric's component.  You have two options:

  • Add the necessary style sheet and JavaScript files to the Help\Styles and Help\Scripts folders in your project and then use a relative path in the component's configuration.
  • Alternatively, in the DocProject Properties window, open the Build | Help 1.x project editor and include the paths to the necessary dependencies.  For Help 2.x output you must edit the Help\files.HxF file manually to include the new paths.

The first option is recommended :)

- Dave

Edit: It seems that you may have to add an image to the Help\Art folder as well.  Here's an example of the relative paths that you can use (not tested though): ../art, ../styles, ../scripts

Jun 30, 2008 at 3:02 PM
Edited Jun 30, 2008 at 3:03 PM

Dave, Thank you so much for your detail explanation. I get it now.
Jun 30, 2008 at 3:08 PM
Many thanks, I confirm that the extra config file element allows the component to be referenced correctly.

The only (slight) issue I have now is that in the compiled help file, mousing over CopyCode.gif throws an object expected error. Any ideas what could be causing this?

All the best, Harvey
Jun 30, 2008 at 3:57 PM
Hi Harvey,

Thanks for the confirmation.

Are you sure that all of the required resources are being compiled into the help file?  (e.g., all JavaScript files, style sheets and images that are required by the component.)

If yes then this is an issue best answered by the author of the component.  I recommend searching the SHFB forum for an answer or start a new thread there if you can't find any.

(Note that DocProject does not modify Sandcastle's XSL transformations at all, so unless you've done that yourself the component should behave the same way as it does when used outside of DocProject.  If you have modified the XSL transformations then try the component in a new DocProject or DocSite to see if maybe something that you've modified is affecting it.)

- Dave
Jun 30, 2008 at 4:41 PM


harveyalison wrote:
Many thanks, I confirm that the extra config file element allows the component to be referenced correctly.

The only (slight) issue I have now is that in the compiled help file, mousing over CopyCode.gif throws an object expected error. Any ideas what could be causing this?

All the best, Harvey



Copy   highlight.js-->Sandcastle\Presentation\vs2005\Scripts            
            highlight.css-->Sandcastle\Presentation\vs2005\Styles
            CopyCode.gif and CopyCode_h.gif--> Sandcastle\Presentation\vs2005\icons  So that all of the required resources can be compiled into the help file
Jun 30, 2008 at 5:03 PM
That's a good idea but beware that it will only work for new DocProjects and DocSites.  You still must add those files to existing projects manually.

- Dave
Aug 29, 2008 at 8:58 PM
Edited Aug 30, 2008 at 12:23 AM
Harvey, did you get the mouse-over resolve? I'm trying to use SHFB's code component in DocProject and it's almost but not quite working. The code isn't colorized and the copy icon is on the left hand side. When I moust over I get the error you mentioned.

I'm still not decided what to do about code examples, haven't tried snippets yet. Right now SHFB gives me nice colorized code but I like the convenience of DocProject. Would I get colorized code in DocProject if I used <codeReference> and snippets? Or am I totally confused?

Thanks,
Andrew

Edit: never mind - everything's working now. I think the issue was where the highlight.* files were being copied. At first I copied them to the wrong place, now it's working.
Aug 30, 2008 at 5:42 AM
I've wrote a note 2 months ago, see if it can help you.
STEPS TO INSTALL DOCPROJECT


1. Install the HTML Help Workshop http://msdn2.microsoft.com/en-us/library/ms669985.aspx, to build Help 1.X
2. Install the VS2005/2008 SDK, to build Help 2.x
4. Get the Sandcastle Standalone Build Components packet, and put it in the path Sandcastle\ProductionTools, name the directory as "SHFB BuildCompoment"
http://www.codeplex.com/SHFB/Release/ProjectReleases.aspx?ReleaseId=10445
We get this packet in order to use its Code Block Componment.
5. Add the Sandcastle\Presentation\vs2005\configuration\sandcastle.config with following 2 configure statements.
Pay attention to the position in the comments.




<colorizer syntaxFile="(SHFB BuildCompoment)\highlight.xml"
styleFile="(SHFB BuildCompoment)\highlight.xsl"
copyImageUrl="../icons/CopyCode.gif" numberLines="false" outlining="false" keepSeeTags="false" tabSize="0" defaultTitle="true" />










6. Copy highlight.js-->Sandcastle\Presentation\vs2005\Scripts
highlight.css-->Sandcastle\Presentation\vs2005\Styles
CopyCode.gif/CopyCode_h.gif--> Sandcastle\Presentation\vs2005\icons

--
**********************
Name: Kevin Guan
Microsoft SQL Group
Tel: ( 010)58965464
**********************

??2008-08-30??aqueisser ??????

From: aqueisser

Harvey, did you get the mouse-over resolve? I'm trying to use SHFB's code component in DocProject and it's almost but not quite working. The code isn't colorized and the copy icon is on the left hand side. When I moust over I get the error you mentioned.

I'm still not decided what to do about code examples, haven't tried snippets yet. Right now SHFB gives me nice colorized code but I like the convenience of DocProject. Would I get colorized code in DocProject if I used and snippets? Or am I totally confused?

Thanks,
Andrew
Aug 30, 2008 at 10:34 PM
Ok, thanks. I did actually get it going but reading over your post I see how I can arrange the DLLs better. This is what we'll do for the next guy in our team to set up the build component.

Now that my tools are working I'll have to get cranking on my content!

Andrew
Aug 31, 2008 at 5:07 AM
It is a good news. Enjoy yourself with your team work.

--
**********************
Name: Kevin Guan
Microsoft SQL Group
Tel: ( 010)58965464
**********************

??2008-08-31??aqueisser ??????

From: aqueisser

Ok, thanks. I did actually get it going but reading over your post I see how I can arrange the DLLs better. This is what we'll do for the next guy in our team to set up the build component.

Now that my tools are working I'll have to get cranking on my content!

Andrew