chmProcessor

chmProcessor. A Html / Word converter to Compiled

HTML Help / Java Help (v 1.7.2)
chmProcessor is a tool for creating HTML help (CHM files) from MS Word or HTML
files. If the file is a Word document, the section titles must use the “Title 1”, “Title 2”, etc
styles that offers by default Word. If the file is a HTML file, the titles must use the <H1>,
<H2>, etc. tags.

From this original file, each section of the document is split to different HTML files.
Each of these files will be a topic page at the help. From the original document, you
can generate:

• A Microsoft Help Workshop project.

• A compiled HTML help (CHM file).
• A web site.
• An Adobe PDF file.
• A Microsoft XPS file.
• A Java Help JAR file.

Requirements
To use this program, you must to have installed the following software:

• Microsoft Windows. Tested versions: Windows 2000 (32 bits), Windows XP

(32 bits), Windows 7 (32 and 64 bits), Windows 8. Console interface will not
work over windows 2000. Versions 1.4 and earlier of chmProcessor do not work
on 64 bits operating systems.
• Microsoft .NET Framework 2.0. You can download the runtime version here:
http://www.microsoft.com/download/en/details.aspx?displaylang=en&id=19
• HTML Help Workshop. If you don’t have it, you cannot compile the help, you
can generate a web site only. You can it download from here:
http://msdn2.microsoft.com/en-us/library/ms669985.aspx
• Microsoft Word if you will work with Word files. Ms Word 2003, 2007 and 2013
has been tested. Starter versions will not work, they don’t support
automation.

Optionally, you can generate PDF and XPS files. To generate a PDF, there is two
ways: PDFCreator or the Microsoft Office 2007 Add-in to generate PDF and XPS. The
last one is the recommended. To generate a XPS file, the MS Office 2007 Add-in is
mandatory:

• PDFCreator. Version 1.2 ONLY. You can download it from here:

http://www.pdfforge.org/products/pdfcreator/download. This kind of generation
will not be supported on the future.
• Microsoft Office 2007 Add-in. It’s an optional tool of the Office suite to
generate PDF / XPS files. It’s not needed with Office 2013. You can download it
from http://www.microsoft.com/downloads/details.aspx?FamilyID=4D951911-
3E7E-4AE6-B059-A2E79ED87041&displaylang=en.

If you want to generate a Java Help, you will need the following software:

Page 1
chmProcessor

• Sun JDK. 1.4 or upper. Only 1.6 has been tested. You can download it from
here: http://www.oracle.com/technetwork/java/javase/downloads/index.html.
• Java Help 2.0 or upper. You can download from here: http://javahelp.java.net/.

If you are going to generate CHM files with a character codepage different than your
system default, for example if you live on Spain and your help will be written in Cyrillic,
you will need this:

• Microsoft AppLocale. Can be downloaded from here:

http://www.microsoft.com/download/en/details.aspx?id=13209

Limitations
• Versions 1.5 and older will not work generating CHM files with source files with
encodings different than Windows-1252. Version 1.6 and higher should work.
• Not all kind of documents will be well formatted, especially HTML documents.
Try to avoid put titles into tables, put images with title styles, and such kind of
things, because the application will be confused about how to split and index
the document. Avoid Javascript.
• Keep in mind that if you use more than one Word source files, the text styles
used should be equal on all documents. So, if some style is different on some
document, it can be overwritten by the definition of other document.
• JavaHelp generation will not work if “Use Tidy over the split HTML files” is not
checked on settings window. JavaHelp seems to need 100% standard HTML
input files to work.
• To generate CHM files with a character codepage (character set) different than
your system default will only work if the source file is a Unicode encoded HTML
file. MS Word 2003 / 2007 source files will not work.
• If you have a MS Office starter version, this application cannot make the HTML
conversion automatically. You can do it manually using “Save as…” option and
using the HTML file as source. Make sure you save it as filtered HTML (no
HTML), and add the directory with the document images on “Additional files”

Interface
Win Interface

This is the main window:

Page 2
chmProcessor

Source files

Here are stored the source document files to generate the help: A single HTML file, or
a list of Word files. If there is more than one Word document, they will be joined to
create the help.

General

Help Title Title of the generated help.

Cut level Level of sections that is used to split the document on topics. As
example, if a level 2 is set, the document will be split on many topics
as paragraphs with “Title 1” or “Title 2” ( or tags <H1> / <H2> if the
document is HTML) are found. If is zero, only a topic page will be
generated for the entire document.
Table of Maximum level of the sections that will appear on the table of
contents max. contents of the help. If is zero, all the titles will appear on the table. As
level example, if a level 3 is set, Titles 1, 2 and 3 will appear on the table of
contents.
Index topics Maximum level of the sections that will appear on the index of the
max. level help. If is zero, all the titles will appear on the index. As example, if a
level 3 is set, Titles 1, 2 and 3 will appear on the index.
Source files List of HTML or Word file sources to generate the help. Only one
HTML file can be used as source, but multiple Word documents can
be used. No HTML and Word documents can be mixed on the list.
Additional files List of other files / directories that must be included on the compiled
help. For example if the source file is an HTML, and it contains
images, these images, or the directory with the images must be

Page 3
chmProcessor

included in this list.

Execute this If you need to make something after the generation, as copy the CHM
command line to other place, put it on a web site by ftp…, you can do it by a
after generate command line here.
Generate If the source file is a word document, you MUST NOT be editing the
button file when you press this button. When this button is pressed, the
project / help generation will start and a new window will be opened,
logging the generation process:

Additional files
Here is stored the list of additional files that are reference by the help document:
Images referenced on the header / footers, text files, etc. You can include single files or
directories. If you include a directory, all files and subdirectories into the directory will
be added. All the additional files and directories will be included at the same directory
than the document source files. So, if a hyperlink on the source files needs to reference
to some of these files, the URL should be relative to the current directory (=
“./theadditionalfiletoreference.txt”)

Important: By default, when MS Word saves a Word document as HTML, all relative
links are rewritten. The application does a save as HTML into a temporal directory of
the Word file to create the help. So, if you include a relative link “./file.txt”, it will
be replaced by a “<temporaldirectory>/file.txt”. To avoid this, there is a MS
Word setting called “Update links on save”. You must to disable this option to use
relative links to additional files. This article explains where it is located and how to
disable it.

Menu File

Here you can load and save the current help generation configuration from / to a
“project” file, to access to the last open projects, and edit the settings of the application.

Page 4
chmProcessor

Compiled Help

Compile help / Dst. File If it’s checked, the help will be compiled on a CHM file, on
the path selected at the Dst. File field.
Generate help project If it’s checked, a help project for the Microsoft Help
Workshop will be generated at the directory selected on Dst.
Directory, and it will not be compiled.
Generate web / Dst. If “Generate” it’s checked, a simple web with the help
Web directory / content will be generated on the Dst. directory. The
Description meta / description and meta fields are the values of this “meta” tags
Keywords meta at the index of the web page generated.
HTML Header File Can be null. If not, the content of this file will be added to the
start of each topic page as header. The content must be
HTML code. As example, this file can contain an IMG tag
with the banner of the application title.
HTML Footer File Can be null. If not, the content of this file will be added to the
end of each topic page as footer. The content must be
HTML code. As example it can be a <BR> tag to add an end
bar to the page or a script to count visits at the generated
web.
Language Language of the CHM contents. If you select a language
with a character codepage distinct of the system default, you
must to install Microsoft AppLocale and check “Use
Microsoft AppLocale to comple CHM files” on the Settings
window.

Web Help

Generate Web / If “Generate” it’s checked, a simple web with the help content will
Dst. Web be generated on the Dst. directory.
directory
Description meta Values of the “meta” tags at the web pages generated. They
/ Keywords meta should explain to the web indexers (as Google) the topic of the
document.
HTML Header Can be null. If not, the content of this file will be added to the start
File of each topic page as header. The content must be HTML code.
As example, this file can contain an IMG tag with the banner of the
application title. This can be different to the header of the CHM.
HTML Footer File Can be null. If not, the content of this file will be added to the end
of each topic page as footer. The content must be HTML code. As
example it can be a <BR> tag to add an end bar to the page or a
script to count visits at the generated web, or a javascript code to

Page 5
chmProcessor

register the visits. This can be different to the footer of the CHM.
Language Language used on the texts of the web site. If your favourite
language is not here, you can create your own translation. To do
this check at the “webTranslations” folder of the program. Copy the
“English.txt” to your “mylanguage.txt”, open it with the notepad,
and change the text of each second line. Example:

“English.txt” file:
Contents
Contents
Topics
Topics
…

“mylanguage.txt”:
Contents
<translation of Contents>
Topics
<translation of Topics>
…

If you do this, please or put an entry at the patches tracker and it

will be added to the application.
Make Full Text If it’s checked, a full text index of the document will be created, and
Search (Require all the document text can be searched. To run the searches, the
ASP.NET web site must be hosted into an ASP.NET server. Only Microsoft
application) IIS 6 and 7 has been test, but probably will work with the Mono
server (only over Windows).

If this field it’s not checked, a simple search at the web help will
allow you to search at the topic titles of the document only.
<head> include Can be null. If not, the content of this file will be added into the
file <head> tag of each topic page. The content must be valid HTML
code for that head.
As example, it can be the javascript tag needed by Google
Analytics to register the visits.
Make Sitemap / If “Make sitemap” is checked, a file called “sitemap.xml.gz” will be
Web Base / added to the web site. This file is a help for the web indexers as
Change Freq. Google to know what pages contains your web site. See
http://www.google.com/webmasters/sitemaps/ to know more about
this file. If you check this field, you must to put the root of your web
site at the field “Web base” (as example,
“http://chmprocessor.sf.net”). At the field “Change freq.” you say
the frequency of change of the document: daily, monthly, etc.
Web template Here you select the template to generate the webhelp.
chmProcessor comes with some standard templates that can be
chosen here. If you have built your own template, you can chose
here the value “Custom”, and select the location of your template
at the “Template directory” field.
Template If “Web template” is “Custom”, here you define the location of the
directory custom template for this help project.

The standard “template” pages for the web help are stored at the “webFiles” folder into
the chmProcessor installation. If you want to change the look of the web help, you can
edit them, but don’t change the texts %XXX% because they are replaced by the

Page 6
chmProcessor

application during the generation process. If you write a nice template and you want to
share it with the world, please put an entry at the patches tracker and it will be added to
the application.

If you want to add navigation links on the header / footer of the help topics, the
application can replace some texts with the URL for the previous/next topic page. Here
are the texts to put:

%NEXTLINK% Link to the previous topic page. If there is no previous page, it will be
replaced by a “#”
%PREVLINK% Link to the next topic page. If there is no next page, it will be replaced
by a “#”
%HOMELINK% Link to the first topic page.

So, a tag to the previous page would be like this:

<a href="%PREVLINK%">Previous</a>

PDF / XPS

Generate PDF / If it’s checked, a PDF file will be generated with the printing of the
Dst. File source Word / Html document at the file on Dst. File. You will need
to have the PDFCreator or the “MS Office 2007 Add-in: Save as
PDF / XPS” installed to use this.
Generate with Choose of how to generate the PDF file: With PDFCreator o with
PdfCreator / the MS Office 2007 Add-in. The last one is the recommended.
Generate with Only version 1.2 of PdfCreator will work, and sometimes hangs up
Office 2007 add- the PDF print.
in
(recommended)
Generate XPS / If it’s checked, a XPS file will be generated with the printing of the
Dst. File source Word / Html document at the file on Dst. File. You will need
to have the the “MS Office 2007 Add-in: Save as PDF / XPS”
installed to use this.

Java Help

Generate Java If it’s checked, the help will be compile a Java Help JAR file, on the
Help / Dst. File path selected at the Dst. File field. You will need to have the JDK
and the Java Help installed to use this.

Settings

Going to the menu File > Settings..., you can access to the settings of the program:

Page 7
chmProcessor

MS Help Path to the compiler exe contained into the HTML Help Workshop.
Workshop It must to point to the installation directory of this package.
Compiler Path
Use Tidy over Tidy is software than cleans and repair HTML files, according to the
the split HTML W3C standards. If it’s checked, when a HTML page of the help is
files generated, tidy is executed over this file. Usually works VERY well,
but I have found some problem with some XHTML files. If you have
troubles with the generated HTML (strange characters, javascript
errors, etc) try to uncheck this field.
Sun JDK Path Installation path of the Sun JDK. It’s needed if you want to generate
Java Help.
Java Help Installation path of the Sun Java Help. It’s needed if you want to
directory path generate Java Help.
Save relative If is checked, when you save a project, the paths to directories and
paths on projects files of the project will be stored relative to the location of the
project file. So, if you store your source files and the project file on
the same folder, you will can move that folder safely to other
locations, and reopen the project and the reference to the source
files will still work.
If is not checked, paths will be saved as absolute, so, if you move
your source files, they will not be found.
Remove/replace If it’s checked, when an internal link (a link pointing to a place into
broken internal the same document) is broken, the application will try to search a
links section into the document with the same title as the broken link
text. If it’s found, the link will be changed to point to that section. If
no section is found, the link will be removed, but its content (text,
image, etc) will be kept.
If it’s unchecked, the broken link will be kept as is.
Use Microsoft If it’s checked, the execution of the CHM compiler will be executed
AppLocale to by the AppLocate application. This is only needed if you will
compile CHM generate a CHM file for a character codepage distinct than the
files / path system default.

Page 8
chmProcessor

This is the short story:

AppLocate is an application that changes the codepage of the
execution of other application. If you don’t use it generating a CHM
file for a character codepage distinct than the system default, the
generated table of contents and index of the CHM file will show
wrong characters.

The long story:

The MS Help workshops, and so the CHM compiler, are very
outdated software, and they don’t know anything about Unicode.
More sad, if you set a Language on the help workshop project, you
encode the source files for the TOC and index with the right
encoding, all of this is ignored, and the local system locale is used
to generate the CHM file. The patch for this is to use AppLocate, to
lie the CHM compiler about the local codepage. More info about
this topic can be found here:
http://blogs.msdn.com/b/sandcastle/archive/2007/09/29/chm-
localization-and-unicode-issues-dbcsfix-exe.aspx
Wait MS Word When the help is generated from a Word file, MS Word is called to
until it closes save it as HTML, then the Word file is closed and then MS Word is
open documents closed. It has been reported that sometimes the application hangs
waiting Word do the closes.
If this field is checked, the application will wait (up to 15 seconds) to
Word closes files and itself. If it’s not checked, the application will
not wait. Uncheck this field can generate troubles with large Word
files, and it’s not recommended.

Console Interface

The application can be called from the command line to generate or open project files.
There are two exes for that: ChmProcessor.exe and ChmProcessorCmd.exe. The first
one is the Windows application, and the second is a console application.
ChmProcessor.exe can be used to open or generate help files, ChmProcessorCmd.exe
only to generate help files. The command line parameters for both are the same:

Use XXXXX.exe [<projectfile.WHC> | <wordfile.DOC>

|<wordfile.DOCX> | <wordfile.HTM> | <wordfile.HTML>] [/g]
[/e] [/y] [/?][/q] [/l1] [/l2] [/l3] [/l4]
Options:
/g Generate help sets (chm, javahelp, pdfs,…)
specified by the project
/e Exit after generate
/y Dont ask for confirmations
/? Print help and exit
/q Prevents a window being shown when run with the
/g command line and logs messages to stdout/stderr
/l1 /l2 /l3 /l4 Lets you choose how much information is
output, where /l1 are errors, /l2 warnings, /l3 application
status information and /l4 are debug messages

If you are going to generate a help file from a batch file, ChmProcessorCmd.exe is
preferred. Windows applications have limitations to interact with the console.

Page 9
chmProcessor

As you can see, you can generate a CHM directly from a Word file with a command
line call, but this has a lot of limitations: The CHM generated will not have cut levels (a
single help page will be generated), no title, etc. The preferred way to use the
command line is create a WHC file, set there the title, cut levels, etc. and to generate
the help with that file.

The application exit codes are:

• 0: OK
• 1: There were warnings.
• 2: There were errors.

Web Site Generation

The application can generate a simple web site with a similar format to the compiled
help. Any topic indexed at the help can be opened directly using the URL. The way to
open it depends of the template used.
For the “Frames” template, a “topic” parameter can be used on the URL. As example, if
you have a topic called “Download”, you can open it like this:
http://chmprocessor.sf.net/index.html?topic=Downloads.
For the “jQuery” template, you can use the “topic” parameter and the URL hash. The
last one is the preferred, because the hash will be updated each time a new help topic
is loaded. An example is http://chmprocessor.sf.net/index.html#Downloads.

Here are some examples of web sites generated with chmProcessor:

• AdminUCV NGN manual

• SiteFX User's Guide
• Microrenewables Toolkit
• Bijlagen: de Vergelijkingseditor in Word 2007
• SprinxCRM online help
• Agile Salesforce to Exchange Synchronizer

Note about Chrome

The standard webhelp templates of chmProcessor use frames (or iframes) and
javascript to show the help content. Chrome has a security control that disable some
javascript functions of frames/iframes when the page is on the local file system (=when
the protocol is file:///). The standard webhelp templates of chmProcessor use those
functions, so you will get an error:

Blocked a frame with origin "null" from accessing a frame

with origin "null". Protocols, domains, and ports must
match

This will not happen when the page is located on a web server (=when the protocol is
http://). To fix this, you must run Chrome with the option “--allow-file-access-from-files”:

"C:\Program Files\Google\Chrome\Application\chrome.exe" --
allow-file-access-from-files
"thewebhelpdirectory\index.html"

Page 10
chmProcessor

License
The license of chmProcessor is GPL. It uses the following software:

• Tango icons
• Tidy
• SQLite

Downloads
You can download the chmProcessor installation binaries from here. Source code is
available from subversion repository here. You can get this document as a PDF here.
See the changelog here.

Bug reporting
The bug reporting can be done at the SourceForge page:
https://sourceforge.net/p/chmprocessor/bugs/. Please, post always the following
elements with the bug report:

• An example file (the Word/Html document, additional files, the WHC help
project file, etc.) to reproduce the bug.
• The chmProcessor version.

It’s the faster way to fix bugs.

Info for developers

Here come some tips if you want to open a help file generated with chmProcessor from
your application. Usually there is three ways to show a help topic on your application:

• Open directly the help file.

• Open a help topic by its title.
• Open a help topic by its HTML file name.

The last one is discarded, because you cannot control how chmProcessor will generate
the file names, and more, those file names can change if you add more titles to your
source help document. So, if you want to open a topic help directly you should use the
topic text titles to open the help. Here are the functions you can use to open the help by
one topic name on C# and Java:

JavaHelp

Your code should look something like this, without any warranty:

// The generated JAR must to be on your class path.

ClassLoader cl = this.getClass().getClassLoader();
URL hsURL = HelpSet.findHelpSet(cl, “help.hs”); //
help.hs if the fixed name for the generated help.
HelpSet hs = new HelpSet(null, hsURL);
HelpBroker hb = hs.createHelpBroker();
hb.setCurrentID(“The topic title to show”);

Page 11
chmProcessor

hb.setDisplayed(true);

Much, much more info on the JavaHelp documentation.

CHM file with C#

System.Windows.Forms.Help.ShowHelp(null,
“C:\pathtomyhelpfile.CHM” ,
System.Windows.Forms.HelpNavigator.KeywordIndex , “The
topic title to show”);

Web help with C#

Keep in mind that the topic title must be encoded for the URL:

System.Diagnostics.Process.Start("http://chmprocessor.sourc
eforge.net/index.html?topic=Web%20Help");

Page 12