Sandcastle Help File Builder

New Post: Add images in XML doc

Guson — Tue, 21 May 2013 06:18:13 GMT

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:

Select Add and Existing Folder... from tree context menu, select the [images]-folder
For each image-file, set BuildAction from Image to Content
In shfb, push the Build the help file button

After the build, you have a <appname>.chm help file, with images. Easy :-).

Regards
/Jonas

New Post: Add images in XML doc

Guson — Tue, 21 May 2013 06:18:13 GMT

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:

Select Add and Existing Folder... from tree context menu, select the [images]-folder
For each image-file, set BuildAction from Image to Content
In shfb, push the Build the help file button

After the build, you have a <appname>.chm help file, with images. Easy :-).

Regards
/Jonas

New Post: Add images in XML doc

EWoodruff — Mon, 20 May 2013 16:33:45 GMT

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.

Eric

New Post: Add images in XML doc

EWoodruff — Mon, 20 May 2013 16:33:45 GMT

New Post: Add images in XML doc

Guson — Mon, 20 May 2013 12:06:51 GMT

Batch for all help file formats

@ECHO OFF
:: 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
REM HTML Help1 (CHM)
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 Website (HTML/ASP.NET)
REM xcopy images\*.* help\Working\Output\Website\images\*.* /q /y

I havent verifyed MS help 2 and MS Help Viewer.

New Post: Add images in XML doc

Guson — Mon, 20 May 2013 12:06:51 GMT

Batch for all help file formats

@ECHO OFF
:: 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
REM HTML Help1 (CHM)
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 Website (HTML/ASP.NET)
REM xcopy images\*.* help\Working\Output\Website\images\*.* /q /y

I havent verifyed MS help 2 and MS Help Viewer.

New Post: Add images in XML doc

Guson — Mon, 20 May 2013 10:54:50 GMT

Yes! I did'it, with MS help1 file. ;-)
I did a longshot, when building the help file.

Create a batch containing:

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

Build help file

In shfb, push the Build the help file button
In Build Output wait for the Clearing working folder... output
Run the batch file

After the build, you have a <appname>.chm help file, with images. Not so easy, but the result was correct.

New Post: Add images in XML doc

Guson — Mon, 20 May 2013 10:54:50 GMT

Yes! I did'it, with MS help1 file. ;-)
I did a longshot, when building the help file.

Create a batch containing:

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

Build help file

In shfb, push the Build the help file button
In Build Output wait for the Clearing working folder... output
Run the batch file

After the build, you have a <appname>.chm help file, with images. Not so easy, but the result was correct.

New Post: Add images in XML doc

Guson — Mon, 20 May 2013 10:11:23 GMT

Hi!
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.

[appname]\
    [doc]\
        [help] (shfb-output, temprary folder)
        [images]\ (images-folder, to use in shfb-build)
        <appname>.shfbproj
        <appname>.chm (copied from [help]-folder)
    [projname]\ (the VS project)
    <appname>.sln

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:

@ECHO OFF
xcopy images\*.* help\images\*.* /q /y
%SystemRoot%\Microsoft.NET\Framework\v4.0.30319\msbuild.exe <appname>.shfbproj
pause
help\Index.html

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)

MAML-pages

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.

New Post: Add images in XML doc

Guson — Mon, 20 May 2013 10:11:23 GMT

Hi!
The help file is currently only for internal usage, so I prefere MS Help1 file (one file, easy to use).

New file structure

[appname]\
    [doc]\
        [help] (shfb-output, temprary folder)
        [images]\ (images-folder, to use in shfb-build)
        <appname>.shfbproj
        <appname>.chm (copied from [help]-folder)
    [projname]\ (the VS project)
    <appname>.sln

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

@ECHO OFF
xcopy images\*.* help\images\*.* /q /y
%SystemRoot%\Microsoft.NET\Framework\v4.0.30319\msbuild.exe <appname>.shfbproj
pause
help\Index.html

MAML-pages

Commented Unassigned: Impossible to reconfigure /Web because of Windows Installer [34068]

EWoodruff — Sat, 18 May 2013 18:25:26 GMT

Hello,

Could you please either make an option to use a non-default /Web or alter the Windows Installer to not try to restore that directory? It makes it impossible to keep modified settings -- every time I change it or remove a file, Windows Installer restores it the next time I run SHFB.

Thanks

James
Comments: ** Comment from web user: EWoodruff **

Remember that Windows doesn't really take kindly to modifying files in the Program Files folder anymore, not since Vista as I recall. I can't change that. I can probably extend the presentation style definition to allow specification of alternate website files. Changes you make would then be treated like a custom presentation style and would be copied in from an alternate location.

Created Unassigned: Impossible to reconfigure /Web because of Windows Installer [34068]

IllusoryStudios — Sat, 18 May 2013 13:33:30 GMT

New Post: Add images in XML doc

EWoodruff — Fri, 17 May 2013 19:32:30 GMT

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.

Eric

New Post: Add images in XML doc

EWoodruff — Fri, 17 May 2013 19:32:30 GMT

New Post: Add images in XML doc

Guson — Fri, 17 May 2013 14:02:10 GMT

Hi!
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

[appname]\
    [doc]\ (shfb-output)
    [img]\ (images)
    [projname]\ (the VS project)
    <appname>.shfbproj
    <appname>.sln

Description

[] - folder
<> - file
() - comment

Questions

(From SHBF documentation) "The path is relative to the basePath configuration element."
Q: What is the "basePath"?

doc
doc\Working\Output\HtmlHelp1
projname

I cant get it to work, only placeholder of image.

<img src="ControlBox.png" alt="ControlBox Class Diagram" />
<img src="../ControlBox.png" alt="ControlBox Class Diagram" />
<img src="../img/ControlBox.png" alt="ControlBox Class Diagram" />

Q: How to add image-path(s) to shfbproj-file
Why:

I would prefere to specify (a list of) image-folder(s), when runing the shfb project
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)

Links

SHBF - Discussions

SHFB - FAQ

New Post: Add images in XML doc

Guson — Fri, 17 May 2013 14:02:10 GMT

Hi!
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

[appname]\
    [doc]\ (shfb-output)
    [img]\ (images)
    [projname]\ (the VS project)
    <appname>.shfbproj
    <appname>.sln

Description

[] - folder
<> - file
() - comment

Questions

(From SHBF documentation) "The path is relative to the basePath configuration element."
Q: What is the "basePath"?

doc
doc\Working\Output\HtmlHelp1
projname

I cant get it to work, only placeholder of image.

<img src="ControlBox.png" alt="ControlBox Class Diagram" />
<img src="../ControlBox.png" alt="ControlBox Class Diagram" />
<img src="../img/ControlBox.png" alt="ControlBox Class Diagram" />

Q: How to add image-path(s) to shfbproj-file
Why:

I would prefere to specify (a list of) image-folder(s), when runing the shfb project
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)

Links

SHBF - Discussions

SHFB - FAQ

Commented Issue: Too small font in member filter in VS2005 website [34061]

Takajalka — Fri, 17 May 2013 13:06:04 GMT

In a VS2005-style website generated with Sandcastle Help File Builder 1.9.7.0, each class has a page that lists its members. At the top of this page, there is a label "Members: Show All". When I hover the mouse pointer over that label, it drops down a list of two check boxes labeled "Include Protected Members" and "Include Inherited Members". The font size in these two labels is so small that they are difficult to read.

In particular, with the default settings of Firefox 21.0 on Windows 7, the font size of "Members: Show All" is 12.3167px, but the font size of "Include Protected Members" and "Include Inherited Members" is only 7.75px. I think these should be the same size.

The font size of "Members: Show All" comes from these CSS properties:
1. body { font-size: medium; } /* 17.6px */
2. div#header table td { font-size: 70%; } /* 17.6px * 70% = 12.32px */

The font size of "Include Protected Members" comes from these CSS properties:
1. body { font-size: medium; } /* 17.6px */
2. #memberOptionsMenu { font-size: 70%; } /* 17.6px * 70% = 12.32px */
3. div#header table td { font-size: 70%; } /* 12.32px * 70% = 8.624px */
4. .checkboxLabel { font-size: 90% } /* 8.624px * 90% = 7.7616px */
Comments: ** Comment from web user: Takajalka **

Thanks. With that change, the font of "Include Protected Members" is a little smaller than that of "Members: Show All", but the difference is only 10% and the text is not too difficult to read.

Created Unassigned: ShowMissingComponent issue [34065]

rpcode — Fri, 17 May 2013 13:04:31 GMT

Hi,

I've encountered an issue with ShowMissingComponent. Here's my case: I have a public static class with a private member class implementing a interface method all documented with XML comments. When I build documentation, SHFB is reporting ShowMissingComponent warning.

```
public static class IPServices
{
private class ServiceProtocolComparer : IComparer<ServiceProtocol>
{
/// <summary>
/// ...
/// </summary>
/// <param name="x">
/// ...
/// </param>
/// <param name="y">
/// ...
/// </param>
/// <returns>
/// ...
/// </returns>
int IComparer<ServiceProtocol>.Compare(ServiceProtocol x, ServiceProtocol y)
{
...
}
}
...
}
```

Visual Studio 2010 generated XML contents:

```
<member name="M:IMiS.Net.IPServices.ServiceProtocolComparer.System#Collections#Generic#IComparer{IMiS#Net#IPServices#ServiceProtocol}#Compare(IMiS.Net.IPServices.ServiceProtocol,IMiS.Net.IPServices.ServiceProtocol)">
<summary>
...
</summary>
<param name="x">
...
</param>
<param name="y">
...
</param>
<returns>
...
</returns>
</member>
```

SHFB output log:
```
Warn: ShowMissingComponent: [M:IMiS.Net.IPServices.ServiceProtocolComparer.System#Collections#Generic#IComparer{{IMiS#Net#IPServices+ServiceProtocol}}#Compare(IMiS.Net.IPServices.ServiceProtocol,IMiS.Net.IPServices.ServiceProtocol)] Missing <summary> documentation
```
As seen above, there is a difference in member name. In the generated XML there is a {IMiS#Net#IPServices#ServiceProtocol} and in output log {{IMiS#Net#IPServices+ServiceProtocol}}. Notice the double curly braces ({}) and a plus (+) sign.

I've used both SHFB v1.9.6.0 and v1.9.7.0 and both have same issue.

I'm using VS2010 presentation style and including the following API elements in the documentation: Expicit interface implementations, Internal members, Private members, Protected members, Protected members of sealed classes.

I there a easy way I could fix this? Great work btw ;)

Thanks in advance,
Robert

Closed Issue: Too small font in member filter in VS2005 website [34061]

EWoodruff — Fri, 17 May 2013 02:07:02 GMT

Closed Issue: Index.html casing [34035]

EWoodruff — Fri, 17 May 2013 02:05:00 GMT

Hello,

On Unix servers, SHFB's default Index.html is a problem. Could you please rename it index.html? Case sensitivity and all.

Thanks

James
Comments: Renamed as requested.