Re: [docbook-apps] How to encode HTMLHelp topic alias: <?dbhh topicname="some_title"topicid="42"?>

[Jirka Kosek <jirka@kosek.cz>]

Taro Ikai wrote:

> You'd mentioned that it is autogenerated (by XSL?) when the corresponding
> element does not have an id. I'm not clear what you mean by the 
> 'corresponding 
> element'? Given:
> 
>   <?dbhh topicname="abc" topicid="123"?>
> 
> Do you mean I should have something like the following in the same 
> document?
> 
>   <chapter><para id="123">...</para></chapter>

No, you must always put <?dbhh?> inside chapter or section or similar 
DocBook element which creates one topic (HTML file). <?dbhh?> and 
topicname and topicid defined inside it are automatically attached to 
containing topic.

> Do you mean that if I don't have a target element with the corresponding 
> attribute, XSL would generate and add the name attribute like <a 
> name="...">
> in the output .html file

This anchor is placed in every generated HTML file anyway.

> This is probably the wrong place to point it out, but WebWorks Publisher
> that my group has been using to extract content out of FrameMaker 
> puts '#' and a number after it in the alias header file which gets 
> included 
> by .hhp file. For example:
> 
>   menu_help_contents = menus133.htm#1001719

HTML Help compiler is unable to deal with fragment identifiers at this 
level. There is additional code in stylesheet which in fact will remove 
fragment identifier from HTML filename.

> 0) What is the granularity of a navigation by topic in HTML Help?
>    Can we use a topic to go to a specific position on a page? Or
>    can we only go to the top of a page (.html file) that includes the
>    topic marker? I'm beginning to get the feeling that topic = .html file.

Context sensitive help (which is using contex.h and alias.h) can go just 
to the start of topic (HTMML page). Other links created by link or xref 
can go anywhere in your document.

> 1) So what is fragment identifier? context.h and alias.h seem enough to 
>    locate the .html file within .chm file. Does fragment identifier
>    do anything to locate a position within the .html file?

Yes exactly. See HTML specification for definition of fragment identifier.

> 2) If fragment identifier locates a specific position within a page
>    for a topic, how am I to use it?

Unfortunatelly AFAIK with context sensitive help there is no way.

> So context.h is to be used by a C++ app that wants to call the 
> HTML Help topics by topic name? And we must carefully assign
> unique numbers by hand to the topicid attribute in <?dbhh> PIs?

Yep, and you should also synchronize your topicnames with application 
developers.

> I guess the reason to hardcode the topicid in <?dbhh> PI is to prevent
> unwanted recompilation in the C++ project each time the topic id changes?
> Otherwise, I don't see any reason to predispose the association between 
> topicname and topicid in Docbook XML. It is strictly for building HTML
> Help.

It is easy. Developer can use topicname constant when referencing to 
some help topic. Internally this constant must be number, you must have 
mapping table somewhere which will map topicnames to some topicids. 
Placing topicname and topicid in a same place allows you to easily 
synchronize them. And please don't ask me why this works this way. I 
would change many things in HTML Help system if I could.

					Jirka

-- 
-----------------------------------------------------------------
   Jirka Kosek  	
   e-mail: jirka@kosek.cz
   http://www.kosek.cz

S/MIME Cryptographic Signature