Re: [dita-help] Context-Sensitivity

[Deborah_Pickett@moldflow.com]

Alan Houser <arh@groupwellesley.com> wrote on
28/03/2008 11:10:34 AM:
> > 1. You might want two (or two hundred) different contexts to
point 
> > to the same topic. You'd have to invent elements just to attach
an 
> > ID to, which is what you'd be doing anyway if you were to use
> > <resourceid> or some other element that is customarily
used for hooks. 
> Even if I have two hundred different contexts
that point to the same
> topic, why would I need more than one "hook"? Can't multiple
GUI 
> contexts reference the same ID? Even in conventional help authoring
> tools, I would not create more than one MapID for any given topic.

I think that you and I are looking at this with different
amounts of indirection in mind.  My perspective is a high-level one:
the context that an application might be able to express may be limited
by the development environment that created the application.  For
example, it's traditional in Windows C++ programming for a context ID to
be nothing more than a 16-bit integer.  I assume that the value of
that ID is outside the control of the documentation team (at my company,
that is the case).

I am looking at it from the perspective of a mapping
application context ID ---> URL of topic (including
fragment reference)
which is a many-to-one relationship.  The application
context ID is magical to the application developer, and the URL of the
topic is magical to the documenter.  (By "magical" I mean
that it is a string with intrinsic meaning.)

I think that you are looking at it from the perspective
of two mappings
application context ID ---> hook ---> URL of
topic (including fragment reference)
where the first mapping may be many-to-one, and the
second mapping is one-to-one.  The hook need not be magical to either
the application developer nor the documenter; it need only be guaranteed
to be unique with respect to other hooks.

Please correct me if I am putting words in your mouth.

There's probably no point me elaborating until I am
sure about our starting assumptions.

> > 2. The id attribute is used for other purposes
too (such as the 
> > target for an <xref>).  How would you distinguish
IDs-as-hooks from 
> > IDs-not-as-hooks?  If it's by the content of the attribute,
then 
> > turning an existing non-hook ID into a hook-ID would mean changing
> > the attribute value, which would break other links to that element.

> I don't see how this distinction is important.
The ID is a label. It
> can be used to associate cross-references with their targets, to 
> associate GUI contexts with topics, or both. I don't see how the 
> role of the ID affects its possible value.
> Let me know what I'm missing.  :-)

(Again, assuming that I can't control the application
context ID.)  At some point, the DITA processor will have to trawl
through the topics and maps that contribute to the output, and produce
a file(s) that the help system and application both use.  The DITA
processor cannot know if an application will ever generate a particular
application context ID, so it must assume that all contexts mentioned are
potentially needed.  If this trawling uses the id attribute then the
file(s) will necessarily contain entries that have nothing to do with context-sensitive
help, unless the trawling can distinguish ids that do and don't participate
in context-sensitive help (hence my remark about the id value).  At
best this produces useless entries.  At worst, it may produce entries
that conflict with or mimic real entries.  If those entries speak
directly of application context IDs (my assumption) then the application
may wrongly invoke the help system.  I agree that this may not be
a problem if there is an intermediate hook-level stage of indirection.

I've tried to express this in small, refutable pieces,
so let me know where we diverge.

-- 
Deborah Pickett
Information Architect, Moldflow Pty Ltd, Melbourne
Deborah_Pickett@moldflow.com