Sunday, May 20, 2007

Indexing the obvious

Spent a bit today creating an initial keyword index file for the C/C++ docs. Nothing special, simply a reordering of the reference and task XML file contents so that a user can type in a few high level terms like "view" and "preferences" and see a complete list concerning C/C++.

Noticed some changes in how indexes are interpreted and displayed, both good and bad. The good includes much better resolving of the entry titles so you can leave the title attribute out and if the path shows up in the TOC it uses the name shown there. The bad is that it uses the 'title' attribute instead of the 'label' attribute used by the TOC file. This means any line copied from one file to the other has to have a single attribute changed or removed just to make it work. Do we really need two attribute names for essentially the same action, naming an href page?

For example, in the TOC file an entry shows as (minus the topic attribute):
label="Selecting Views and Editors" href="reference/cdt_u_views.htm"

But in the index file is has to read:
title="Selecting Views and Editors" href="reference/cdt_u_views.htm"

or, the new solution:

Either way, you can't just copy and paste. You have to do some editing to replace or remove the extraneous attribute. Hint, maybe in a future release we could make both work for a bit and then slowly deprecate one of them (sorry 'title' we don't need you anymore).

Its also still unclear to me how one controls what is shown when the Index tab is clicked in the Help window. Pre-3.3 if the keyword entry included several 'title' entries, then the keyword appeared with a tree control, hiding the sub-entries under the common name. In 3.3 the sub-entries are always shown and there is no tree control on the keyword. This reduces the number of main entries that can be shown in the index list and forces one to click previous and next buttons to cycle through them a page at a time, no simple scrolling allowed.

Now I know a lot of people are familiar with horizontal scrolling but, I'm sorry, that's simply a UI abomination to me unless its a large image. Lists of items should not force me to scroll in the horizontal direction. Up and down is fine, but horizontal? Was the list getting too large to hold in memory? I've no idea but the click, click, click instead of taking advantage of the mouse's scroll wheel seems like a step backward.

Anyway, even with the above issues it was easy and fast to create the index file and link it into the Index view of the Help window. Hopefully more people will add their own links to the file so that the C/C++ docs will have a kick-butt useful index.

No comments: