RE: [dita-help] Thoughts on CSH

["Matthew Ellison" <matthew@ellisonconsulting.com>]

Hi Tony

It struck me on reading your CSH implementation scenarios
(http://wiki.oasis-open.org/dita/Implementation_Scenarios) that it makes no
mention of the Alias file.  Often the mapping of developer ID (numeric) to
html topic file is done in a two-stage process where the number is mapped to
a string in the map file, and the string is mapped to a topic file in the
Alias file.  This suits a scenario where the developer chooses arbitrary map
numbers, and the Help author is able to change topic filenames at will --
what needs to match is the context strings that both use.

None of your options seem to cater for the scenario where the map file
(including context strings and map IDs) is provided by the developer.  It
would not be easy to pull this information into the Ditamap or topics -- I
envisage a scenario where the Map file is maintained separately (with
context strings that are independent of the "URLS" of the Help output) but
the Alias information is stored either in the Ditamap (preferred?) or the
topics.  Communication between Help author and application developer would
be required in order to ensure that context strings match between Map file
(provided by developer) and context strings within DITA source files.

Hope this helps progress the discussion.  Sorry I can't be at the meeting
this week.

Cheers,

-Matthew

-----Original Message-----
From: Tony Self [mailto:tself@hyperwrite.com] 
Sent: 18 June 2009 14:00
To: dita-help@lists.oasis-open.org
Subject: [dita-help] Thoughts on CSH 

Greetings colleagues

I've been going back through the earlier discussion about storing context
ids in the ditamap or topic, and window definitions in the ditamap, and have
been trying to distil the discussion into some possible changes. (I've
posted links to the original spec change proposals at the bottom of this
e-mail; you will need to log on to the OASIS site to get to them.)

The context id proposal suggested a new <help> element in the topicmeta. A
better name for the element might be <help-context>. That <help> or
<help-context> element should also contain an id attribute (in addition to
the proposed help-id and help-string attributes). 

The CSH spec change has to provide for three options:

. context hooks stored in the topic
. context hooks stored in the map
. context hooks stored in an intermediate (external) file

During processing, the necessary map/alias/header/cshelp files would be
produced from whatever resource was available.

There would need to be some "cascade" rules, to cope with a scenario where
context hooks found in more than one location (eg, in both the map and the
topic). The "cascade" should be:

. Context Hook in intermediate (external) file overrides...
. any context hook specified in the map, which overrides...
. any context hook specified in the topic.

Rather than create a new element, the <help-context> element could actually
be a reworked resourceid element, since that element was originally
introduced to DITA for the purposes of containing context ids.

The window spec change suggested a new <help-window> element. A better name
for the element might be <window>, or perhaps <ui-window>, because the
window definitions will have applicability beyond Help systems. The new
element should have an id attribute, in addition to the other attributes
proposed. 

Amongst the "next steps" that we should be working on are these two:

. Develop Use Cases for the workflow scenarios of the programmer providing
the Help author with map/alias files, and the Help author providing  the
programmer with the same.

. Develop Use Cases for coding the context hooks at the topic level, at the
map level, and coding externally from DITA.


Let's discuss these points both here on the e-mail list, and also at the
upcoming Friday teleconference.

Regards

Tony Self




Links:
http://www.oasis-open.org/apps/org/workgroup/dita-help/download.php/28362/di
ta-proposal-csh1.html
http://www.oasis-open.org/apps/org/workgroup/dita-help/download.php/28370/di
ta-proposal-csh-win.html
http://wiki.oasis-open.org/dita/Implementation_Scenarios







---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that
generates this mail.  Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php