About the automatic table of contents

[Gloops]

Hello everybody,

I spent much time browsing the forums about this protestation of the
HTML Help Workshop compiler :

HHC6000: Error: An internal file could not be created. Make certain
there is enough disk space on the drive where you are compiling your file.
HHC5007: Error: Fatal navigational compilation error. This is likely the
result of an invalid contents (.hhc) file.


Among answers I got, there was an error in the register, some
applications had to be reinstalled but we did not know exactly which
ones, a security update forbids to access UNC paths whereas I had no UNC
paths at all in my project.

My machine is very well installed, there is no error on it and there are
30 GB free on the disk.

The explanation is much more simple. I had written a help file with
brief pages as is recommended, so I did not need to divide each into
parts, and I did not use the H1 to H9 tags. I intended to obtain an
automatic table of contents based on the TITLE tag in the head of each
page, and HTML Help Workshop is unable to do that. The unpleasant point
is not that it is unable to do that, but that it is unable to tell you
it. I do not see any reason why an internal file could not be created,
just because the user inserted no H1 tag in his pages.

So, I replaced <p style="text-align:center;font-size:20px">Title of the
page</p>

by <H1>Title of the page</H1>

and the table of contents is nicely generated.

It is possible to modify the style of H1 in the style sheet.

You may have to pay attention with the accentuated characters, if you
have &agrave; in a title you get is as is in the table of contents,
instead of it being replaced by à, as it is on the page.

[Gloops]

Oh, but ... well, one precision. I saw somewhere on the microsoft sites
(I do not remember whether it was microsoft of msdn), that somebody
spoke about a TOC entry to point to somewhere inside a page, so he told
it was necessary to insert an <a name=""> target, but ... I only could
implement that by hand.

I do not find the page again, so I am not able to say whether that can
be done in an automatic table of contents.

If not, it seems the idea could be to automatically generate the toc,
and then uncheck the automatic generation and load the toc in the Html
Help Workshop UI. Not sure I am able to tell you the precise procedure,
but I did it this afternoon, and could start from an automatically
obtained toc, and modify it by hand.

That being said, you have to pay attention to have a correct syntax for
the <H1> tags (with no attributes) in all your pages before generation
of the toc, otherwise your toc will not show all the pages, and you have
either to complement it by hand, or to delete it and generate it again
after correction of the errors.

So, about pointing to inside a page from an automatic toc, if somebody
knows how to do that ?

[Rainer H. Rauschenberg]

On 2015-12-17, Gloops <glo...@zailes.invalid.org> wrote:
> Le 17/12/2015 06:16, Gloops a écrit :

>> The unpleasant point is not that it is unable to do that, but that it
>> is unable to tell you it.

HTML Help is an unfinished product with some features not completely
implemented. You have to be happy to see an error, even if it's wrong,
and not only a crash.

> Oh, but ... well, one precision. I saw somewhere on the microsoft sites
> (I do not remember whether it was microsoft of msdn), that somebody
> spoke about a TOC entry to point to somewhere inside a page, so he told
> it was necessary to insert an <a name=""> target, but ... I only could
> implement that by hand.
>
> I do not find the page again, so I am not able to say whether that can
> be done in an automatic table of contents.

I don't think so. As far as I remember a totally valid handcrafted
TOC-entry pointing to an <a name=""> target lead to a compiler warning
or even error, although everything worked fine and a fully working chm
was created. To avoid the error the majority of MVPs voted for letting
the TOC-entry point to a dummy-page which instantly reloads (via
meta-tag or javascript) itself with the intra-page-target.

[Gloops]

Le 29/12/2015 23:35, Rainer H. Rauschenberg a écrit :
> On 2015-12-17, Gloops <glo...@zailes.invalid.org> wrote:
>> Le 17/12/2015 06:16, Gloops a écrit :
>
>>> The unpleasant point is not that it is unable to do that, but that it
>>> is unable to tell you it.
>
> HTML Help is an unfinished product with some features not completely
> implemented. You have to be happy to see an error, even if it's wrong,
> and not only a crash.

:)

Right that there is much less urgency, seen from the user point of view,
to produce a brand new version of Word each year.

Right also that many users are happy not to have to pay for the html
help product. Except by the time they have to spend on it.

>
>> Oh, but ... well, one precision. I saw somewhere on the microsoft sites
>> (I do not remember whether it was microsoft of msdn), that somebody
>> spoke about a TOC entry to point to somewhere inside a page, so he told
>> it was necessary to insert an <a name=""> target, but ... I only could
>> implement that by hand.
>>
>> I do not find the page again, so I am not able to say whether that can
>> be done in an automatic table of contents.
>
> I don't think so. As far as I remember a totally valid handcrafted
> TOC-entry pointing to an <a name=""> target lead to a compiler warning
> or even error, although everything worked fine and a fully working chm
> was created. To avoid the error the majority of MVPs voted for letting
> the TOC-entry point to a dummy-page which instantly reloads (via
> meta-tag or javascript) itself with the intra-page-target.
>

Oh, so I was lucky.

I had several phases like that, where I was sure it was not possible to
obtain what I wanted, let it on the side for a few days, looked at it
again and saw immediately what I had to do.

I wonder whether it would be useful to spend time to write and publish
one guide more about Html Help Workshop, or let the next user come here
and ask questions, and see whether someone comes back to answer him, or
whether he finds himself after the time it takes to see things from a
new point of view.

[Gloops]

Le 29/12/2015 23:35, Rainer H. Rauschenberg a écrit :

> I don't think so. As far as I remember a totally valid handcrafted
> TOC-entry pointing to an <a name=""> target lead to a compiler warning
> or even error, although everything worked fine and a fully working chm
> was created. To avoid the error the majority of MVPs voted for letting
> the TOC-entry point to a dummy-page which instantly reloads (via
> meta-tag or javascript) itself with the intra-page-target.
>

Oh I remember ... You are right, at a moment I had to choose between
avoiding a compilation error, or obtaining a fully working chm file.

So, I obtained a chm with a toc, for that I had to correct the toc when
I wanted pages to have link targets inside them. For the moment being,
if there is a main to obtain that with an automatically generated toc,
with or without error messages at the compilation, we do not know how.

[Gloops]

Le 29/12/2015 23:35, Rainer H. Rauschenberg a écrit :

> I don't think so. As far as I remember a totally valid handcrafted
> TOC-entry pointing to an <a name=""> target lead to a compiler warning
> or even error, although everything worked fine and a fully working chm
> was created. To avoid the error the majority of MVPs voted for letting
> the TOC-entry point to a dummy-page which instantly reloads (via
> meta-tag or javascript) itself with the intra-page-target.
>

Oh I remember ... You are right, at a moment I had to choose between
avoiding a compilation error, or obtaining a fully working chm file.

So, I obtained a chm with a toc, for that I had to correct the toc when
I wanted pages to have link targets inside them. For the moment being,

if there is a mean to obtain that with an automatically generated toc,