HTML Export Options

<< Click to Display Table of Contents >>

Navigation:  Reference > Project Configuration Settings > Publishing Options > HTML Help >

HTML Export Options

These options configure many key aspects of how your project content is converted to HTML code for the Microsoft HTML Help/CHM help file format and the two Microsoft Visual Studio Help file formats. There is a separate set of settings for the WebHelp and ePUB eBook formats, which have different requirements .

This section is not included in skins

This section is not stored in HTML skins, it is project-only. Even if you are using a skin, you must still configure this in your project.

HTML export settings for Microsoft CHM and Microsoft Visual Studio Help:

Setting up CHM files for high-resolution devices:

The Microsoft CHM Viewer in Windows uses an old HTML rendering engine that has special requirements. Help+Manual can automatically configure your CHM file so that it displays correctly on high-resolution 4K monitors and devices like the Microsoft Surface and Lenovo Yoga Pro. If you don't do this the text and other elements will often be too small to read on these devices.

1.Open your project in Help+Manual and in the Project Explorer navigate to Configuration > Publishing Options > MS HTML Help > HTML Export Options.

2.Set Font Size Encoding to: pt Points.

3.Select the checkbox for Make pixel sizes relative to monitor resolution (4K display compatibility)

All elements of your CHM file will then automatically be adapted for correct display on both normal and high-resolution devices and monitors.

Extension for HTML topic files:

By default all HTML topic files are exported with the extension .html. You can change this to .htm, here if you want. However, CHM and Visual Studio Help only support either .htm or .html. Other extensions are only allowed in WebHelp.

CSS stylesheet file name:

This setting allows you to change the name of the stylesheet file exported with the CSS style information. The default file name is default.css.

Font size encoding:

This setting allows you to choose how font sizes are defined in your output. You can choose pt (points), px (pixels), % (percent) or ems (where 1 em = 100%). Which setting you choose controls how fonts are displayed on the user's screen and whether or not the user can change the font size.

Special note on font size for CHM files and high-resolution devices:

Always choose points for CHM for the best results on modern devices. See above.

Normally, font sizes set in points cannot be adjusted by the user. However, because of the special way the MS CHM Viewer works, this is still the optimum setting for CHM files. You should always choose points for CHM unless you have a specific reason for choosing something else.

This is a 1:1 setting. The font sizes are set in screen pixels, so they should correspond directly to the number of pixels on the screen. This does not work on modern high-resolution monitors, where the physical pixels on the screen are no longer equivalent to the defined pixel dimensions of fonts and other elements.

Percent or Ems:
These are relative dimensions. Percent is relative to the base font size. Ems are more complicated, but they are also indirectly relative to the base font size. However, these font size encodings are not recommended for HTML Help/CHM files!

Font size of Normal style:

If you choose percent or ems for font size encoding (see above) you can also use this setting to define the size of the Normal style in relation to the default font of the user's browser, which is a 16-pixel font on all current browser. The value is expressed in percent and the default is 100%.

The 100% default is generally not the best choice, however! What you need really depends on the entire layout. For example, if your base font size is equivalent to 10-11 points the correct font size for Normal would be around 82%.

The ems and percent font size encodings used with this are not recommended for HTML Help/CHM files!

Make pixel sizes relative to monitor resolution (4K display compatibility)

This option encodes all dimensions that are normally specified in pixels, for example in a tag like

<img src="xxxxx.png" width="500" height="300"/>

as inches in CHM files to make the content automatically scalable on ultra-high resolution monitors.

For hi-res compatible CHM files you need to specify this option in combination with font encoding in points.

Exclude topics from CHM search if topic starts with an underscore

Topics whose IDs start with an underscore are automatically excluded from search in WebHelp. If you check this option, topics whose IDs start with an underscore will also be excluded from search in CHM files:

Important note for context help:

When you activate this option, the extension of the topic file is changed from .htm to .xhtm. You need to remember this for your context calls made to the internal topic HTML file in the CHM file.

For example, if the ID is _Introduction_Topic the new HTML file name to make the call to will be _introduction_topic.xhtm.

Replace blanks and underscores in HTML file names with hyphens:

If you leave this off, illegal characters, spaces and underscores in HTML file names will be replaced by underscores (old Help+Manual standard). Turning it on uses hyphens instead.

This is off by default to prevent breaking links in existing projects from earlier Help+Manual versions.

Export style names:

When this is selected Help+Manual uses the full names of your styles in the stylesheet. This makes the sheet much easier to read if you ever want to view or edit it manually.

If you deselect this option the style names are converted to brief, alphanumeric codes that are not so "human-friendly". This can make your project a little bit smaller but not much.

Export lists as text:

This setting is recommended. When it is selected numbered and bulleted lists are managed using text formatting in HTML-based output. This will generally provide better list formatting across browsers than the standard lists generated when you turn it off. Even in HTML Help, which uses MS Internet Explorer for HTML rendering, you will find that lists display better with this setting.

If you deselect this option lists will be exported as standard <OL> and <UL> lists with <LI> list elements. This option also supports formatted lists but has some limitations compared to the text option. See Formatting Lists for more information on this.

If an image has no caption export file name as hint:

Images in HTML pages can have an ALT attribute that displays a small text in a "tooltip" when the user positions the mouse pointer over the image.

Selecting this option exports the image file name as the ALT attribute if the image doesn't have a caption. Unless your graphics files have very descriptive names it is normally advisable to switch this off.

Highlight hotspots in pictures

When this is on hotspot links in images and graphics are highlighted for easier visibility and respond on mouseover. Turning this off creates invisible hotspots that only change the mouse cursor form on mouseover.

Conversion options for non-HTML image formats:

This option controls how images in your project not compatible with HTML are converted and exported when you publish to HTML-based formats. It does not affect JPEG, GIF and PNG images, which are exported without conversion.

Which option provides the best results depends on the type of images in your project. GIF and PNG generally provide the smallest files with the best quality for screenshots with 256 colors or less. PNG files are usually too large for images with more than 256 colors; JPEG is the better choice for those.

Screenshots often do not look so good when converted to JPEG so you should always choose your settings to make sure that this doesn't happen. It is better to use GIF or PNG and no more than 256 colors for screenshots.

JPEG and true-color PNG are really only needed for photographs and continuous-tone graphics, and JPEG is generally preferable for this because it produces much smaller files for true color images.

Output quality for JPEG images:

You can reduce graphic file size by decreasing the quality but this will also make the images look less good. A value of between 80 and 90 is normally acceptable.

Note that this quality setting is only applied to JPEG images actually generated by the program on the basis of the conversion settings (see above). JPEG images that you insert in your project directly are not affected. They are used as they are, without any changes.

Export topics of class "Popup" as JavaScript popup windows:

Activate this to use JavaScript popups in WebHelp, CHM and Visual Studio Help. See Creating popup topics and Using JavaScript popups for full details.

See also:

Configuring Your Output

HTML Help (Help Formats)

HTML Help Options (Help Windows)