This is the mail archive of the docbook-apps@lists.oasis-open.org mailing list .


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

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


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

Attachment: smime.p7s
Description: S/MIME Cryptographic Signature


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]