Embedding images in Documentation

Feb 19, 2009 at 8:37 AM

I got yet another issue...

In my doc comments i got the following html tag and the png file is included in the vsproj. But all i see in the chm file is a red cross and i tried to keep an eye on the working folder and it dosnt seem to get copied there... What to do!?

 

<

img src="overview.png"/>

 

Feb 19, 2009 at 8:53 AM
Hello,
img is an HTML tag and like all the other HTML tags it is not supported by the Sandcastle.
The reference build allows the HTML tags to pass through to the output, but does not process them.

Now, since you are using SHFB (by your other posts), use the Additional Contents property to let
the SHFB copy the images to the output folder for you, and in time for the compiler to see.

Best regards,
Paul.
Feb 19, 2009 at 9:26 AM
Thank you for your very fast answer Paul!
I looked in the documentation but cant find any info on how to do this, u got some reference for this?
Feb 19, 2009 at 9:47 AM
>>I looked in the documentation but cant find any info on how to do this, u got some reference for this?

In the Version 1.7.x, which is the one I have installed:
You will find it in the documentations as...
(-) The GUI Project Manager
        (-) Additional and Conceptual Contents
              (-) Additional Content Properties
Well, it is stated that is deprecated - it seems that it is not well explained, that should be only the additional
HTML files, which both SHFB and DocProject introduced until the conceptual help support was released
by the Sandcastle.
Otherwise, I do not know if Eric is providing another means of handling this.
In my build library (Sandcastle Assist), I refer to this operation as Help Resources, and it is well supported.
Hopefully, both SHFB and DocProject will improve their support for this operation.

Best regards,
Paul.
Feb 19, 2009 at 10:08 AM
Oh yes i agree. The issue is that im not using the gui but only the console application because i calling it from my buildscripts.
This might be a long shot, but do you know if its possible to pass the additionalcontent property through commandline to the consoleapllication?
Feb 19, 2009 at 11:03 AM
>>but do you know if its possible to pass the additionalcontent property through
>>commandline to the consoleapllication
?
It might depend on the format or version of the SHFB. I think Eric might help here. Another way is to
create a sample with the GUI and see how the project format handles it.

For my personal work, I currently use my own build library, which I am improving and enhancing as the
Sandcastle Helpers (currently only in Alpha stage and recommended only for testing) in the Sandcastle Assist project.

Best regards,
Paul.
Feb 19, 2009 at 11:54 AM
Okay thanks for your help Paul. The issue is that we got like 25 vsproj which all gets build through msbuild and they all got different images to include in the docs.

So i should create a sample with the gui for each project, dont want to do that.

I figured out another way to include the pictures, meybe not pretty but hey it works. I made a target which finds the images to include and copy them to sandcastle icon dir, because its included in the chm.
And now it works, but im still looking for a much more pretty solution :-)
Feb 19, 2009 at 12:44 PM
>>So i should create a sample with the gui for each project, dont want to do that.
Why? you only need to know the format used by the SHFB and do a similar thing since you are using the SHFB.

>>I figured out another way to include the pictures, meybe not pretty but hey it works.
Since you are using MSBuild, you can use the copy task to copy the images, and you should not have any
problem since you are writing your own script.

Normally, you should not use just <img src="imageFile.xxx"/> in your project,
but something like  <img src="folderName/imageFile.xxx"/> then you can copy the images to the
folderName directory.
The "images" directory is commonly used and supported by most Sandcastle builds. I am not sure, the icon dir
will work in other cases, since the CHM compiler does a lot to resolve the links.

Best regards,
Paul.
Feb 19, 2009 at 2:49 PM
What i end up doing to make a bit more pretty was to copy the images automaticly by script to icons/images og then i deleted the images afterward. My html code from the code looks like this, and it works :)

<

img src="icons/images/PositionFormatClassDiagram.png"/>

 

Feb 19, 2009 at 3:19 PM
>>My html code from the code looks like this, and it works :)
It should work, unless not done well.
I do not know if there is any need to use the extra "icons" directory, though.

Best regards,
Paul.
Editor
Feb 19, 2009 at 4:37 PM
If you're using SHFB 1.7, you can use the -addcontent command line parameter to define additional content such as images that need to be included in the help file.  With SHFB 1.8, the project format is MSBuild based so images and HTML files added to the project with a Content build action are included as content by default.  Files in the root of the project end up in the root of the help file.  Files in sub-folders end up in like-named subfolders in the help file.  This is a much cleaner approach than the prior version's method via the AdditionalContent property since what you see in the project explorer is what you get in the help file with regard to layout for content items.  The deprecation reference only concerns HTML content as MAML is now the preferred way of adding non-API topics to the help file though HTML continues to be supported for backward compatibility.

With the MSBuild format in v1.8, you can still override any project property from the command line.  You can also use one or more response files or more likely target override files (set using the CustomBeforeSHFBTargets property override) to make it easier to do this.  Target override files are the better approach for the XML-based properties such as documentation sources and component configurations.  See the Building Projects Outside the GUI help file topic for more information.

Eric
Feb 20, 2009 at 7:41 AM
That was exactly what i need! Thank you both for help!