Odd behavior of created CHM file

[Nemo]

In our application we wanted the ability to create CHM files. ( the
application isn't a help system generator itself, we just want to generate
help files as an "extra" for the user ). At various points in the
application the user is allowed to browse/select HTML/HTM files on thier
machine. When the user publishes, we use the HTML/HTM files to generate a
CHM. The application creates a project file and a map file in a temp dir to
generate the CHM. We convert all the absolute paths to the accumulated
HTML/HTM files to relative paths(relative to the temp dir with the project
file). An example of the project file looks like

[OPTIONS]
Binary Index=No
Compatibility=1.1 or later
Compiled file=alpha2.chm
Default topic=..\..\..\..\..\Help\SpecialAdd.html
Display compile progress=Yes
Enhanced decompilation=Yes
Language=0x409 English (United States)


[FILES]
..\..\..\..\..\Help\SpecialAdd.html
..\..\..\..\..\SecondHelp\SpecialDel.html

[ALIAS]
TEST_1000=..\..\..\..\..\Help\SpecialAdd.html
TEST_1001=..\..\..\..\..\SecondHelp\SpecialDel.html

[MAP]
#include Map.h

[INFOTYPES]

and map file looks like

#define TEST_1000 1000
#define TEST_1001 1001

we then run the hhc.exe( setting the working dir as the temp directory) and
generate the CHM. The project compiles correctly and gives no errors and
produces the requested CHM.

However when we attempt to load a specfic topic using the ID such as
hh -mapid 1001 alpha2.chm

it always gives the "This program cannot display the webpage" error in the
help window, when we would expect to see the SpecialDel.html displayed.
When alpha2.chm is decompiled it correctly extracts all the html/html and
images required, thus they are present in the CHM. If we replace the
relative paths with the absolute paths, it results in the same bad behavior.
However if we put all the html and images into the temp dir so everything is
referenced locally and create a CHM, running hh -mapid 1001 alpha2.chm,
does show the specialdel.html correctly. Thus is must be related to the
paths provided in the [FILES] and [ALIAS] sections. I have been searching
for a solution to this issue but have not found any leads in the MS
documentation on rules for the paths. The only reason we use relative paths
is because HTML Workshop also uses relative paths. If we do the equilivant
steps above using HTML workshop, we get the same bad results. (no big shock
since it uses hhc.exe too)

We are using version 4.74.8702.0 on Vista.

Any help is appreciated.

[Rob Chandler [MVP]]

Hey Nemo

Post by Nemo
..\..\..\..\..\Help\SpecialAdd.html
..\..\..\..\..\SecondHelp\SpecialDel.html

These paths wont cut it.
Relative paths in the .HHP cannot start with a "..".
Think of the CHM like a zip file. A path like ..\..\xxx has no meaning from
the root.

The rules are...
The .HHP .HHC .HHK project files generally live together in the root folder
of your project.
All other content files must be in that folder or in folder below that
folder.
The working dir needs to be the project dir (containing the .HHP).
(well you have that right).

Now the CHM output path you can make any path.

eg. Compiled file=d:\anypath\alpha2.chm

Cheers
Rob

Post by Nemo
In our application we wanted the ability to create CHM files. ( the
application isn't a help system generator itself, we just want to generate
help files as an "extra" for the user ). At various points in the
application the user is allowed to browse/select HTML/HTM files on thier
machine. When the user publishes, we use the HTML/HTM files to generate a
CHM. The application creates a project file and a map file in a temp dir
to generate the CHM. We convert all the absolute paths to the accumulated
HTML/HTM files to relative paths(relative to the temp dir with the project
file). An example of the project file looks like
[OPTIONS]
Binary Index=No
Compatibility=1.1 or later
Compiled file=alpha2.chm
Default topic=..\..\..\..\..\Help\SpecialAdd.html
Display compile progress=Yes
Enhanced decompilation=Yes
Language=0x409 English (United States)
[FILES]
..\..\..\..\..\Help\SpecialAdd.html
..\..\..\..\..\SecondHelp\SpecialDel.html
[ALIAS]
TEST_1000=..\..\..\..\..\Help\SpecialAdd.html
TEST_1001=..\..\..\..\..\SecondHelp\SpecialDel.html
[MAP]
#include Map.h
[INFOTYPES]
and map file looks like
#define TEST_1000 1000
#define TEST_1001 1001
we then run the hhc.exe( setting the working dir as the temp directory)
and generate the CHM. The project compiles correctly and gives no errors
and produces the requested CHM.
However when we attempt to load a specfic topic using the ID such as
hh -mapid 1001 alpha2.chm
it always gives the "This program cannot display the webpage" error in the
help window, when we would expect to see the SpecialDel.html displayed.
When alpha2.chm is decompiled it correctly extracts all the html/html and
images required, thus they are present in the CHM. If we replace the
relative paths with the absolute paths, it results in the same bad
behavior. However if we put all the html and images into the temp dir so
everything is referenced locally and create a CHM, running hh -mapid 1001
alpha2.chm, does show the specialdel.html correctly. Thus is must be
related to the paths provided in the [FILES] and [ALIAS] sections. I
have been searching for a solution to this issue but have not found any
leads in the MS documentation on rules for the paths. The only reason we
use relative paths is because HTML Workshop also uses relative paths. If
we do the equilivant steps above using HTML workshop, we get the same bad
results. (no big shock since it uses hhc.exe too)
We are using version 4.74.8702.0 on Vista.
Any help is appreciated.

[Nemo]

Hi Rob,

Thank you for your response, your answer corresponded exactly to our tests
showing all files need to be in the project directory or a sub directory
below the project directory. This causes us an issue, since we allow the
use to select the HTML/HTM files and they may be anywhere on the disk(and the
HTML/HTML files may have relatively referenced dependancies). Even though we
have a workaround for this issue, I consider it to be a very poor solution.
Since I have not been watching the help building world for a while, should we
abandon using hhc.exe and investigate a move to sandcastle, or will it just
be more of the same issues?

TIA

Post by Rob Chandler [MVP]
Hey Nemo

Post by Nemo
..\..\..\..\..\Help\SpecialAdd.html
..\..\..\..\..\SecondHelp\SpecialDel.html

These paths wont cut it.
Relative paths in the .HHP cannot start with a "..".
Think of the CHM like a zip file. A path like ..\..\xxx has no meaning from
the root.
The rules are...
The .HHP .HHC .HHK project files generally live together in the root folder
of your project.
All other content files must be in that folder or in folder below that
folder.
The working dir needs to be the project dir (containing the .HHP).
(well you have that right).
Now the CHM output path you can make any path.
eg. Compiled file=d:\anypath\alpha2.chm
Cheers
Rob

Post by Nemo
In our application we wanted the ability to create CHM files. ( the
application isn't a help system generator itself, we just want to generate
help files as an "extra" for the user ). At various points in the
application the user is allowed to browse/select HTML/HTM files on thier
machine. When the user publishes, we use the HTML/HTM files to generate a
CHM. The application creates a project file and a map file in a temp dir
to generate the CHM. We convert all the absolute paths to the accumulated
HTML/HTM files to relative paths(relative to the temp dir with the project
file). An example of the project file looks like
[OPTIONS]
Binary Index=No
Compatibility=1.1 or later
Compiled file=alpha2.chm
Default topic=..\..\..\..\..\Help\SpecialAdd.html
Display compile progress=Yes
Enhanced decompilation=Yes
Language=0x409 English (United States)
[FILES]
..\..\..\..\..\Help\SpecialAdd.html
..\..\..\..\..\SecondHelp\SpecialDel.html
[ALIAS]
TEST_1000=..\..\..\..\..\Help\SpecialAdd.html
TEST_1001=..\..\..\..\..\SecondHelp\SpecialDel.html
[MAP]
#include Map.h
[INFOTYPES]
and map file looks like
#define TEST_1000 1000
#define TEST_1001 1001
we then run the hhc.exe( setting the working dir as the temp directory)
and generate the CHM. The project compiles correctly and gives no errors
and produces the requested CHM.
However when we attempt to load a specfic topic using the ID such as
hh -mapid 1001 alpha2.chm
it always gives the "This program cannot display the webpage" error in the
help window, when we would expect to see the SpecialDel.html displayed.
When alpha2.chm is decompiled it correctly extracts all the html/html and
images required, thus they are present in the CHM. If we replace the
relative paths with the absolute paths, it results in the same bad
behavior. However if we put all the html and images into the temp dir so
everything is referenced locally and create a CHM, running hh -mapid 1001
alpha2.chm, does show the specialdel.html correctly. Thus is must be
related to the paths provided in the [FILES] and [ALIAS] sections. I
have been searching for a solution to this issue but have not found any
leads in the MS documentation on rules for the paths. The only reason we
use relative paths is because HTML Workshop also uses relative paths. If
we do the equilivant steps above using HTML workshop, we get the same bad
results. (no big shock since it uses hhc.exe too)
We are using version 4.74.8702.0 on Vista.
Any help is appreciated.

.

[Rob Cavicchio]

Post by Nemo
Thank you for your response, your answer corresponded exactly to our tests
showing all files need to be in the project directory or a sub directory
below the project directory. This causes us an issue, since we allow the
use to select the HTML/HTM files and they may be anywhere on the disk(and the
HTML/HTML files may have relatively referenced dependancies). Even though we
have a workaround for this issue, I consider it to be a very poor solution.
Since I have not been watching the help building world for a while, should we
abandon using hhc.exe and investigate a move to sandcastle, or will it just
be more of the same issues?

Sandcastle is not equivalent to the HTML Help compiler. Sandcastle is a
mechanism of extracting an API structure into a set of HTML files, which you
can then use the HTML Help compiler to create a CHM out of.

BTW, as far as I know the compiler itself is not legally redistributable
(although it is free). Hopefully your solution takes that into account.

As for your path problem, why doesn't the automated process automatically
copy the selected HTML files into the same folder as the HHP, then do the
compile?


********************
Rob Cavicchio
***@mvps.org

[Nemo]

Thank you for your info on SandCastle. We do not plan to distrubute the help
compiler, the user must have it installed on thier machine and point our
application to the compiler path. Once the user does this via application
options, the functionality discussed here becomes available to the user to
generate help files. Since our system allows the user to select any
html/html files to include we can't just copy the html file to the project
directory. We would also have to parse the html/htm files to determine any
relative dependances the files had, and then copy those dependancies, and so
on. Suddenly the job of allowing a user to create the help files
automatically grows into a larger job, one that we are not ready to tackle
considering our tight deadlines.

Post by Rob Cavicchio

Post by Nemo
Thank you for your response, your answer corresponded exactly to our tests
showing all files need to be in the project directory or a sub directory
below the project directory. This causes us an issue, since we allow the
use to select the HTML/HTM files and they may be anywhere on the disk(and the
HTML/HTML files may have relatively referenced dependancies). Even though we
have a workaround for this issue, I consider it to be a very poor solution.
Since I have not been watching the help building world for a while, should we
abandon using hhc.exe and investigate a move to sandcastle, or will it just
be more of the same issues?

Sandcastle is not equivalent to the HTML Help compiler. Sandcastle is a
mechanism of extracting an API structure into a set of HTML files, which you
can then use the HTML Help compiler to create a CHM out of.
BTW, as far as I know the compiler itself is not legally redistributable
(although it is free). Hopefully your solution takes that into account.
As for your path problem, why doesn't the automated process automatically
copy the selected HTML files into the same folder as the HHP, then do the
compile?
********************
Rob Cavicchio
.

[Rob Chandler [MVP]]

Well you could reduce the job.
Examples:
* User may select one folder to compress to a CHM (recusive to sub folders).

You just need to warn the user not to choose a base folder in the middle of
a help folder system
otherwise ..\ type links that link below the link will not work.

So in my FAR help my .hhp project file, the [FILES] section contains just
index.htm
but the compiler pulls in the entire help (HTML, JS, CSS, Images) by
following the links.

Rob

Post by Nemo
Thank you for your info on SandCastle. We do not plan to distrubute the help
compiler, the user must have it installed on thier machine and point our
application to the compiler path. Once the user does this via application
options, the functionality discussed here becomes available to the user to
generate help files. Since our system allows the user to select any
html/html files to include we can't just copy the html file to the project
directory. We would also have to parse the html/htm files to determine any
relative dependances the files had, and then copy those dependancies, and so
on. Suddenly the job of allowing a user to create the help files
automatically grows into a larger job, one that we are not ready to tackle
considering our tight deadlines.

Post by Rob Cavicchio

Post by Nemo
Thank you for your response, your answer corresponded exactly to our tests
showing all files need to be in the project directory or a sub directory
below the project directory. This causes us an issue, since we allow the
use to select the HTML/HTM files and they may be anywhere on the
disk(and
the
HTML/HTML files may have relatively referenced dependancies). Even
though
we
have a workaround for this issue, I consider it to be a very poor solution.
Since I have not been watching the help building world for a while,
should
we
abandon using hhc.exe and investigate a move to sandcastle, or will it just
be more of the same issues?

Sandcastle is not equivalent to the HTML Help compiler. Sandcastle is a
mechanism of extracting an API structure into a set of HTML files, which you
can then use the HTML Help compiler to create a CHM out of.
BTW, as far as I know the compiler itself is not legally redistributable
(although it is free). Hopefully your solution takes that into account.
As for your path problem, why doesn't the automated process automatically
copy the selected HTML files into the same folder as the HHP, then do the
compile?
********************
Rob Cavicchio
.

[Rob Cavicchio]

One other thought...I don't know if setting Flat=Yes in the compiler
options will get around the relative path problem for context Help. It
effectively flattens the entire Help system into a single folder,which
eliminates a lot of relative path issues. But it does have consequences:

(1) You cannot have two topic files of the same name (which is probably not
a good idea anyway).
(2) The compiler will fix up normal href paths, but not anything created by
a script.

Post by Rob Chandler [MVP]
Well you could reduce the job.
* User may select one folder to compress to a CHM (recusive to sub folders).
You just need to warn the user not to choose a base folder in the middle
of a help folder system
otherwise ..\ type links that link below the link will not work.
So in my FAR help my .hhp project file, the [FILES] section contains just
index.htm
but the compiler pulls in the entire help (HTML, JS, CSS, Images) by
following the links.
Rob

Post by Nemo
Thank you for your info on SandCastle. We do not plan to distrubute the help
compiler, the user must have it installed on thier machine and point our
application to the compiler path. Once the user does this via application
options, the functionality discussed here becomes available to the user to
generate help files. Since our system allows the user to select any
html/html files to include we can't just copy the html file to the project
directory. We would also have to parse the html/htm files to determine any
relative dependances the files had, and then copy those dependancies, and so
on. Suddenly the job of allowing a user to create the help files
automatically grows into a larger job, one that we are not ready to tackle
considering our tight deadlines.

Post by Rob Cavicchio

Post by Nemo
Thank you for your response, your answer corresponded exactly to our tests
showing all files need to be in the project directory or a sub directory
below the project directory. This causes us an issue, since we allow the
use to select the HTML/HTM files and they may be anywhere on the
disk(and
the
HTML/HTML files may have relatively referenced dependancies). Even
though
we
have a workaround for this issue, I consider it to be a very poor solution.
Since I have not been watching the help building world for a while,
should
we
abandon using hhc.exe and investigate a move to sandcastle, or will it just
be more of the same issues?

Sandcastle is not equivalent to the HTML Help compiler. Sandcastle is a
mechanism of extracting an API structure into a set of HTML files, which you
can then use the HTML Help compiler to create a CHM out of.
BTW, as far as I know the compiler itself is not legally redistributable
(although it is free). Hopefully your solution takes that into account.
As for your path problem, why doesn't the automated process
automatically
copy the selected HTML files into the same folder as the HHP, then do the
compile?
********************
Rob Cavicchio
.