Add images in XML doc

Topics: User Forum
May 17, 2013 at 2:02 PM
I have used SHFB, to produce code documentation for a while, and now I want to add pictures like class diagram and so on.

SHFB - Project Properties

In SHFB project settings I have:
[Paths/Output Paths/Help content output path] = doc\
(Warning: The output folder will be erased, when building a web-site)

My file structure

    [doc]\ (shfb-output)
    [img]\ (images)
    [projname]\ (the VS project)
  • [] - folder
  • <> - file
  • () - comment


(From SHBF documentation) "The path is relative to the basePath configuration element."
Q: What is the "basePath"?
  1. doc
  2. doc\Working\Output\HtmlHelp1
  3. projname
I cant get it to work, only placeholder of image.
  1. <img src="ControlBox.png" alt="ControlBox Class Diagram" />
  2. <img src="../ControlBox.png" alt="ControlBox Class Diagram" />
  3. <img src="../img/ControlBox.png" alt="ControlBox Class Diagram" />
Q: How to add image-path(s) to shfbproj-file
  1. I would prefere to specify (a list of) image-folder(s), when runing the shfb project
  2. In XML doc of code-file only use file name, <img src="ControlBox.png" alt="ControlBox Class Diagram" />
Q: List of supported image formats
?: (gif, jpg, png)


SHBF - Discussions
May 17, 2013 at 7:32 PM
The basePath only relates to the code block component which has no bearing on how images are displayed or referenced. In relation to imported code blocks, the base path is the project folder.

Bear in mind that when you add an image to a SHFB project, it's default BuildAction is set to Image with the assumption that it will be used in MAML topics. With that build action, it only gets copied if referenced in a MAML topic and will end up in the Media\ folder. Setting the CopyToMedia property to true will force it to always get copied to the .\Media folder even if not referenced in MAML topics.

If your intent is to simply use it from XML comments, set its BuildAction property to Content so that it is always copied to the output folder. If located at the root, it will get copied to the root of the help content. If in a subfolder, it will get copied to a like-named subfolder in the help content. From there, the information in the FAQ entry is correct. Use either a relative path (..\Image.png) or relative path with subfolder (..\Images\Image.png) to access it.

However, if producing MS Help Viewer output, the above may not work as I recall since the viewer modifies the URLs. I'd have to try it and see if there's a way to make it work.

May 20, 2013 at 10:11 AM
The help file is currently only for internal usage, so I prefere MS Help1 file (one file, easy to use).

New file structure

I changed my file structure, if I want to produce other help-formats. I imported the [images]-folder into shfb Project Explorer, and marked the images as CopyToMedia=True. I use .NET Framework 4.5 in Build settings.
        [help] (shfb-output, temprary folder)
        [images]\ (images-folder, to use in shfb-build)
        <appname>.chm (copied from [help]-folder)
    [projname]\ (the VS project)
And the [help]-folder (shfb-output) is only used as a temprary folder.

Source code documentation

The path is relative to the [help] (shfb-output) folder, i guess after your description.
The images is referenced from XML documentation in source code, like this:
<img src="..\images\ControlBox.png" alt="ControlBox Class Diagram" />

SHBF builds

I have tryed all build formats, and the only one that I can get to work is Website (HTML/ASP.NET), if I manually copy the [images]-folder into the [help]-folder, after a shfb-build. And its okey with a html help. I could do a batch, containing:
xcopy images\*.* help\images\*.* /q /y
%SystemRoot%\Microsoft.NET\Framework\v4.0.30319\msbuild.exe <appname>.shfbproj
And in shfb proj change to include the [projname]<projname>.csproj insted of <appname>.sln, because I get some error running the batch, no problen running in shbf gui. (SHFB : error BE0042: You must specify at least one documentation source)


I have not tryed adding/using MAML-pages, but it maybe a better aproach, then I could extend code documentation, with custom Welcome-, History-, Class description-pages, before the code documentation.
May 20, 2013 at 10:54 AM
Yes! I did'it, with MS help1 file. ;-)
I did a longshot, when building the help file.

Create a batch containing:

xcopy images\*.* help\Working\Output\HtmlHelp1\images\*.* /q /y

Build help file

  1. In shfb, push the Build the help file button
  2. In Build Output wait for the Clearing working folder... output
  3. Run the batch file
After the build, you have a <appname>.chm help file, with images. Not so easy, but the result was correct.
May 20, 2013 at 12:06 PM

Batch for all help file formats

:: 1. In shfb, push the "Build the help file" button
:: 2. In "Build Output" wait for the "Clearing working folder..." output
:: 3. Run this batch file

REM Comment/uncomment in Build selected help file formats
xcopy images\*.* help\Working\Output\HtmlHelp1\images\*.* /q /y
REM MS Help 2 (HxS)
REM xcopy images\*.* help\Working\Output\MSHelp2\images\*.* /q /y
REM MS Help Viewer (MSHC)
REM xcopy images\*.* help\Working\Output\MSHelpViewer\images\*.* /q /y
REM xcopy images\*.* help\Working\Output\Website\images\*.* /q /y
I havent verifyed MS help 2 and MS Help Viewer.
May 20, 2013 at 4:33 PM
I think you missed what I said in my first response. If these the images are not being used in MAML topics, just set the BuildAction in the SHFB project to Content and place them in an Images folder off the root of the project. They'll get copied into the working folder automatically and compiled into the help file.

May 21, 2013 at 6:18 AM
I certainly did, the CopyToMedia is something else, I check it later. Now this is the way to do;-)

Use images, not referenced by MAML topics

Import the [images]-folder into shfb Project Explorer, not referenced by MAML topics:
  1. Select Add and Existing Folder... from tree context menu, select the [images]-folder
  2. For each image-file, set BuildAction from Image to Content
  3. In shfb, push the Build the help file button
After the build, you have a <appname>.chm help file, with images. Easy :-).