Creating HTML Help

[Jonathan Wood]

Greetings,

I'm trying to get up to speed on HTML help. What I'm finding are outdated
tools and poor documentation.

Can anyone help me with any of the following:

1. I use Visual Studio. The wizards will automatically generate HTML help
files for me but they use uppercase tags, which the Visual Studio editor
warns me are invalid in XHTML. Does anyone know why this is?

2. I couldn't find information on why each help topic includes the <a
name=""></a> tag. What does this do, and why does it seem to duplicate the
association already defined in the [ALIAS] section of the project file?

3. I couldn't find anything on HTMLDefines.h. Is this regenerated to include
my own symbols or what exactly?

Thanks!

Jonathan

[Rob Chandler [MVP]]

Hi Jonathon

Post by Jonathan Wood
Greetings,
I'm trying to get up to speed on HTML help. What I'm finding are outdated
tools and poor documentation.

I agree. HH was done at a time before XHTM and XML became popular.
VS only offers XHTML syntax check right? And HH is ANSI which
is another reason why we really need a new general app help system.

Post by Jonathan Wood
1. I use Visual Studio. The wizards will automatically generate HTML help
files for me but they use uppercase tags, which the Visual Studio editor
warns me are invalid in XHTML. Does anyone know why this is?

I noticed the other day when I opened a HTML file in VS 2005 it
seemed to be stuck in XHTML validation mode. Most help authors
would use Dreamweaver, FrontPage, MS Expression Web etc.
I guess programmers are more XHTML XML based for the tighter syntax.

Post by Jonathan Wood
2. I couldn't find information on why each help topic includes the <a
name=""></a> tag.

Interesting.

Post by Jonathan Wood
What does this do, and why does it seem to duplicate the association
already defined in the [ALIAS] section of the project file?

Maybe just trying to be consistant. Dunno.

Post by Jonathan Wood
3. I couldn't find anything on HTMLDefines.h. Is this regenerated to
include my own symbols or what exactly?

I haven't used the Wizard you talk about. But usually you include a H and
ALI
file to define context IDs in external files.
http://helpware.net/htmlhelp/how_to_context.htm

Sorry I'm not much help. Send me an example if you like. I'm currently using
VS2005
on XP and VS2008 on Vista.
Rob

Post by Jonathan Wood
Thanks!
Jonathan

[Jonathan Wood]

Post by Rob Chandler [MVP]

Post by Jonathan Wood
I'm trying to get up to speed on HTML help. What I'm finding are outdated
tools and poor documentation.

I agree. HH was done at a time before XHTM and XML became popular.
VS only offers XHTML syntax check right?

That appears to be the case, yes.

Post by Rob Chandler [MVP]
And HH is ANSI which
is another reason why we really need a new general app help system.

Well, as long as we're using IE components, it must be supporting Unicode
now, right? I mean, HTML Help Workshop probably doesn't, but the rendering
components surely must?

Post by Rob Chandler [MVP]
I noticed the other day when I opened a HTML file in VS 2005 it
seemed to be stuck in XHTML validation mode. Most help authors
would use Dreamweaver, FrontPage, MS Expression Web etc.
I guess programmers are more XHTML XML based for the tighter syntax.

Right. Well, I actually use a very powerful tool for my Web development and
that tool is Visual Studio. <g> So it just seemed a bit strange that it
seems to fall a little flat when it comes to HTML Help.

Post by Rob Chandler [MVP]

Post by Jonathan Wood
2. I couldn't find information on why each help topic includes the <a
name=""></a> tag.

Interesting.

Post by Jonathan Wood
What does this do, and why does it seem to duplicate the association
already defined in the [ALIAS] section of the project file?

Maybe just trying to be consistant. Dunno.

Yeah, I've had a chance to play with this some more. It doesn't seem needed.
Perhaps it was just there to document what the ID of that topics was, and
they didn't like using HTML comments.

Post by Rob Chandler [MVP]

Post by Jonathan Wood
3. I couldn't find anything on HTMLDefines.h. Is this regenerated to
include my own symbols or what exactly?

I haven't used the Wizard you talk about. But usually you include a H and
ALI
file to define context IDs in external files.
http://helpware.net/htmlhelp/how_to_context.htm
Sorry I'm not much help. Send me an example if you like. I'm currently
using VS2005
on XP and VS2008 on Vista.

I appreciate that. I've had a rough couple of days but seemed to have worked
through most of the issues.

Thanks!

Jonathan

[Rob Cavicchio]

Post by Jonathan Wood
Well, as long as we're using IE components, it must be supporting Unicode
now, right? I mean, HTML Help Workshop probably doesn't, but the rendering
components surely must?

Unicode topic files will display in the topic pane of HTML Help. But they
won't be parsed for search data or for the correct titles to display when
you navigate to them in the TOC, etc. For English you can use UTF-8 topic
files and it doesn't matter because the characters are the same. But for
other languages you might run into problems.

Post by Jonathan Wood
Right. Well, I actually use a very powerful tool for my Web development
and that tool is Visual Studio. <g> So it just seemed a bit strange that
it seems to fall a little flat when it comes to HTML Help.

Unfortunately, this is not surprising. For years now, Microsoft has been
saying that they will not make any further enhancements to HTML Help other
than to plug security holes. So basically they are ignoring it. It's still
quite a good system in my opinion, but I think you have to go outside of MS
tools if you're looking for something that will help you author it well.


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

[Jonathan Wood]

Post by Rob Cavicchio

Post by Jonathan Wood
Well, as long as we're using IE components, it must be supporting Unicode
now, right? I mean, HTML Help Workshop probably doesn't, but the
rendering components surely must?

Unicode topic files will display in the topic pane of HTML Help. But they
won't be parsed for search data or for the correct titles to display when
you navigate to them in the TOC, etc. For English you can use UTF-8 topic
files and it doesn't matter because the characters are the same. But for
other languages you might run into problems.

This really surprises me. Especially now that WinHelp is no longer even
distributed with Windows. I noticed that HTML Help Workshop is almost 10
years old. I don't understand why there is not more effort to keep Windows
help stronger.

Anyway, thanks for passing that along.

Post by Rob Cavicchio
Unfortunately, this is not surprising. For years now, Microsoft has been
saying that they will not make any further enhancements to HTML Help other
than to plug security holes. So basically they are ignoring it. It's still
quite a good system in my opinion, but I think you have to go outside of
MS tools if you're looking for something that will help you author it
well.

Can I get a little clarification? Is the lack of Unicode support in the TOC
due to HTML Help Workshop, or Windows? If the former, then I understand what
you are saying.

Thanks.

[David Webber]

...I noticed that HTML Help Workshop is almost 10 years old. I don't
understand why there is not more effort to keep Windows help stronger.

I suspect that Windows Help *has* become stronger sort of automatically,
because the rendering engine is more powerful. I have just been going
through mine (written, originally, something like 10 years ago) and
"rationalising" the styles with cascading style sheets (and a bit of
improved JavaScript) and just about all the improvements HTML itself has
undergone, work fine within the compiled HTML environment.

But as you're finding HTML help Workshop is a different matter.

I worry about Microsoft's direction too, as I find HTML help idea to be very
good. There's a lot that doesn't need fixing, and scope for a lot of
customised improvements (as things are) via libraries of JavaScript.

Dave

[Jonathan Wood]

Yeah, I can see your comments about HTML improving. I know I have a lot of
flexibility there with regards to CSS, etc.
--
Jonathan Wood
SoftCircuits Programming
http://www.softcircuits.com

Post by David Webber

...I noticed that HTML Help Workshop is almost 10 years old. I don't
understand why there is not more effort to keep Windows help stronger.

I suspect that Windows Help *has* become stronger sort of automatically,
because the rendering engine is more powerful. I have just been going
through mine (written, originally, something like 10 years ago) and
"rationalising" the styles with cascading style sheets (and a bit of
improved JavaScript) and just about all the improvements HTML itself has
undergone, work fine within the compiled HTML environment.
But as you're finding HTML help Workshop is a different matter.
I worry about Microsoft's direction too, as I find HTML help idea to be
very good. There's a lot that doesn't need fixing, and scope for a lot of
customised improvements (as things are) via libraries of JavaScript.
Dave
--
David Webber
Author of 'Mozart the Music Processor'
http://www.mozart.co.uk
For discussion/support see
http://www.mozart.co.uk/mozartists/mailinglist.htm

[Rob Cavicchio]

Post by Jonathan Wood
Can I get a little clarification? Is the lack of Unicode support in the
TOC due to HTML Help Workshop, or Windows? If the former, then I
understand what you are saying.

It's the compiler and the Help Viewer. You might think of the Viewer as
consisting of two components: (1) the embedded IE window, and (2) everything
else-the navigation pane (TOC, index, etc.), the buttons along the top, and
so forth. It's this "everything else" part that does not support Unicode.
This code hasn't changed since the days of Windows 95/98 support, and those
weren't Unicode operating systems.

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

[Jonathan Wood]

Post by Rob Cavicchio
It's the compiler and the Help Viewer. You might think of the Viewer as
consisting of two components: (1) the embedded IE window, and (2)
everything else-the navigation pane (TOC, index, etc.), the buttons along
the top, and so forth. It's this "everything else" part that does not
support Unicode. This code hasn't changed since the days of Windows 95/98
support, and those weren't Unicode operating systems.

Wow, that's hard to believe--or understand.