HTML Export Options

<< Click to Display Table of Contents >>

Navigation:  Reference > Project Configuration Settings > Publishing Options > WebHelp >

HTML Export Options

These options configure many key aspects of how your project content is converted to HTML code for WebHelp and eBooks (ePUB, Kindle and EWriter eBooks). There is a separate set of settings for Microsoft HTML Help CHM files and the Microsoft Visual Studio Help 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 WebHelp and eBooks (ePUB, Kindle and EWriter):

Extension for HTML topic files:

By default all HTML topic files are exported with the extension .html. You can change this to.htm, .asp, .php or a manually-entered extension but extensions other than .htm or .html are only supported in WebHelp. The .html extension is always used for topic files in HTML Help (CHM files) and Visual Studio Help.

This setting is also irrelevant for eBooks.

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.

Arrow_rChoose pt or px to lock your font size and layout, % or ems to allow the user to change the font size.
Arrow_rAlways choose % or ems for ePUB eBooks, otherwise many readers will not allow font size changing.

When you export the font size in points the user cannot adjust the font size. However, the size of the fonts displayed on the user's computer screen will vary depending on the Windows screen DPI setting and/or font size settings. For example, if you develop your help on a machine with Windows set to 96dpi (the standard) your text layout may be incorrect on computers set to 120dpi (fonts look much too big, text in hanging indents may be wider than the indent etc). This is because the size of the fonts changes but the size of the other layout elements (indents, locked table cells etc.) doesn't.

This is the only setting that ensures that the fonts and your layout will always be displayed exactly as you see them on your development machine. The font size is always uses the same number of pixels, so it is always the same size relative to other elements of your layout like indents, graphics and so on.

Percent or Ems:
If you select percent or Ems the user will be able to adjust the font size in the help, for example by holding down Ctrl and turning the mouse scroll wheel. This may or may not be a good thing, because the size of other layout elements (graphics, indents, locked table cells etc.) will not change, so the user adjustments may "break" your layout.

Important note on the % and ems settings:
If you choose these units all the other dimensions in the HTML output for WebHelp and eBooks will use relative ems dimensions instead of absolute values. This is necessary for responsive designs in which the entire layout can be scaled by changing the base font size.

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. 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%.

Export WebHelp with UTF-8 BOM:

Only switch this off if you are using PHP code in your project and your server's PHP system is having trouble with the BOM at the beginning of your webhelp files. If you don't know what PHP is you don't need to turn this off!

All Help+Manual webhelp files are stored in UTF-8 Unicode. The UTF-8 BOM (Byte Order Mark) is a special character code at the beginning of the file that identifies it as a UTF-8 Unicode file. It is generally better to leave this in because it will prevent old and badly-configured servers from misinterpreting the UTF-8 Unicode formatting. However, the PHP installations on some servers still have trouble with the BOM and so you may need to switch the BOM off if you are using PHP.

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.

Apply date and time stamp of topic to HTML topic files:

When this is on (default setting) the timestamps of your HTML topic files will be set to the date and time of the topic in your project, which is equivalent to the time of the last change. This makes it easier to synchronize your output folder with an old version on your web server, for example. This is only really relevant for WebHelp output – in CHM help the topic files are all hidden inside the CHM.

If you turn this off the timestamps of all HTML files will always be the date and time at which your entire project was published.

Do not turn this setting off unless you have a specific reason to do so.

Modify archive bit of topic files depending on changes:

Turning this on will automatically clear the archive bits of all modified files in your WebHelp output folder. Use this if you have an FTP program like weblink Second Copy that can synchronize your output folder with your web server folder using archive bits.

The advantage of this is that it automatically flags all modified files, even if their timestamps have not changed. This is important because the timestamps of your topic files are only changed if the topics have actually been edited. For example, if you change your HTML templates this will change all your topic files but it will not change the timestamps of topic files that have not been edited, even though their contents change because of the template changes. Using archive bits guarantees that all modified files are identified.

Using this option only makes sense if you have an FTP program that supports folder synchronization on the basis of archive bits, however...

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

WebHelp (Help Formats)