[Omnihelp-devs] Index entries

[Glenn M. <gle...@vo...>]

Hi Jeremy,

I've been looking over OmniHelp. Great job. I haven't finished my =
evaluation, but the one thing that stuck out to me was the format of the =
.ohk file.

The documentations mentions that there are two formats. One format has a =
level followed by text that is exposed to the reader.

The other format has a level followed by a URL, followed by "the index =
of the Contents entry in tocItems, whose title is used for the link =
text."

Elsewhere you present the example from an .ohk:

  [1,"title, HTML attribute"],
  [2,"for images, assigning via marker"],
>>[3,"ae999029.htm#Xae1003420",3],
--[2,"ae999029.htm#Xae1003420",1],

The related .ohc:

  [2,"9 Using markers for HTML markup","htmlmark.htm#Xae1015982"],
  [3,"9.1 Working with FrameMaker markers","ae999397.htm#Xae1015686"],
>>[3,"9.2 Adding custom marker types","ae999029.htm#Xae999029"],

Hence, what you'll see in the index for the >> item will be "9.2 Adding =
custom marker types". What you'll see for the -- item will be "9 Using =
markers for HTML markup".=20

Unfortunately, this points out two limitations the way I see it.

[1] You are tieing the .ohk too tightly with the .ohc. The index number =
is going to be very hard to maintain. How does it know what should be =
referenced in modular systems? What if I have tools to build a master =
.ohc from several .ohc files?

[2] What if I don't want the text from the .ohc displayed in my index? =
This example is actually a really good one, because I probably would not =
want that title "9.2 Adding custom marker types" in my index without =
editing.=20

=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=


An extension to this format that would be easier to generate and =
maintain is that the third item in the .ohk entry is the plain text that =
I want displayed in the index.

  [2,"ae999029.htm#Xae1003420","adding customer markers"]
  [2,"ae999029.htm#Xae1003420","customer markers"]
  [2,"ae999029.htm#Xae1003420","markers"]
  [1,"ae999029.htm#Xae1003420","Dude, so you want some customer makers"]

I mean, in the case of FM index tokens, they can be placed into the =
output as mid-topic <a name=3D..> targets. For that matter, they can =
even have a value attribute that contains the contents of the FM index =
token (just to keep the source reference complete), such as <a =
name=3D"Xae1003420" value=3D"customer markers"></a>. Thanks to your =
help, I already have mif2go doing this.

If the source reference is complete within each owning HTML file, the =
.ohk could be generated at any point in time for whatever set of HTML =
files exists.=20

[*] It would NOT have to rely on titles from the TOC, but could have the =
entries come directly from the author as intended as index tokens.

[*] It would NOT have to be re-exported from the source (FM), but could =
actually recombine and re-use existing HTML (like from two manuals.)

Which leads me to another question. Who does the ordering and =
alphebetization of the index? Is the .ohk supposed to be in order from =
the onset, or does the OmniHelp do that later?

=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D

I'll be looking into this more, as well as the underlying HTML and =
javascript. If I find ways to contribute and improve the deliverables, =
I'll do the work and submit the work.

Thanks for doing getting this project more than off the ground.

Glenn