IBM Software Group
®
Context-Sensitive Help with the DITA Open Toolkit
Jeff AntleyIBM
October 4, 2007
IBM Software Group
2
Agenda
What is context-sensitive help?
How is it typically authored/sourced?
DITA to the rescue
CSH DITA specialization – the strategy
CSH DITA specialization – the technical details
Demos: Installing the cshelp plugin into DITA-OT
Authoring CSH content in DITA
Outputting Eclipse context files
Outputting draft-mode HTML (useful for technical or editorial review)
Migrating Eclipse context files to DITA
Creating HTMLHelp
IBM Software Group
3
What is context-sensitive help?
“Context-sensitive help is a kind of online help that is obtained from a specific point in the state of the software, providing help for the situation that is associated with that state….”
-- Wikipedia
IBM Software Group
4
What is context-sensitive help?(Eclipse examples)
Infopop Help view
UI assistance for working with a specific panel, window, or field Only useful within the context in which it is displayed Usually contains links to a help system (online help/information center)
IBM Software Group
5
How is CSH authored/sourced?(Eclipse example)
<?xml version="1.0" encoding="UTF-8"?><?NLS TYPE="org.eclipse.help.contexts"?><contexts> <context id="new_wizard_selection_wizard_page_context"> <description>
Choose the type of resource you would like to create.
</description> <topic label="Resources" href="concepts/concepts-12.htm"/> </context> …</contexts>
IBM Software Group
6
Problems with this type of authoring environment
Custom file formats tend to be edited in a a variety of editors – even text editors
No validation, error-checking, reusability, consistency, or separation of information from presentation
Example: hand-made nested unordered lists:
<context id="resource_view_context"> <description><b>This view</b> shows all resources in the workspace, including: - HTML files - Java files - Java source files - Class files - XML files
</description> <topic href="concepts/concepts-5.htm" label="Views"/> <topic href="reference/ref-27.htm" label="Navigator View"/> </context>
Hard to review (peer, technical, or editorial)
IBM Software Group
7
DITA to the rescue
Allows CSH to use the same tag set and tooling as other DITA-based documentation types
Consistent output when writers tag content appropriately in DITA
Source validation and error checking
Dynamic resolution of link titles to relative DITA documents
Ability to single source content using conrefs
Ability to output to a variety of formats as runtime format changes without modifying DITA source
IBM Software Group
8
CSH DITA specialization – the strategy
Enable DITA -> Eclipse context file formatNo text
Enable migration of existing Eclipse context files to DITANo text
No text
Allow DITA -> HTML outputNo text
Do not preclude specialization from being used for other output formatsNo text
No textNo textNo textNo text
IBM Software Group
9
CSH DITA specialization – the technical details
Enable DITA -> Eclipse context file format dit2context.xsl is used to transform .dita files to Eclipse context (.xml) files
Enable migration of existing Eclipse context files to DITA context2contexttemp.xsl
context2dita.xsl
Allow DITA -> XHTML output Standard DITA-OT transforms can be used
Do not preclude specialization from being used for other output formats cshelp.dtd and cshelp.mod add only minor changes from topic:
• csprolog
• csmetadata
• cswindowtitle
• cswidgetlabel
IBM Software Group
11
DEMO: Installing the cshelp plugin into DITA-OT
Prerequisite: working copy of DITA-OT
Download cshelp plugin from sourceforge.net/
Unzip cshelp.zip to your <DITA>/demo directory
Run Ant integrator build file ( ant -f integrator.xml )
IBM Software Group
18
DEMO: authoring contentcshelp/csh_sample/sample1_context.dita
<?xml version="1.0" encoding="utf-8"?><!DOCTYPE cshelp PUBLIC "-//IBM//DTD DITA CSHelp//EN" "..\demo\cshelp\dtd\cshelp.dtd"><cshelp id="csh_outer_container" xml:lang="en-us"><title>sample1_context</title><shortdesc/><csbody/> <cshelp id="s1c1"> <title>My Sample 1 Context 1</title> <shortdesc>This is an example context file.</shortdesc> <csbody> <p id="p1">Here's some additional content in a paragraph.</p> </csbody> </cshelp> <cshelp id="s1c2"> <title>My Sample 1 Context 2</title> <shortdesc>This is an example context file.</shortdesc> <csbody> <p conref="sample1_context.dita#s1c1/p1"></p> </csbody> </cshelp></cshelp>
IBM Software Group
19
DEMO: authoring contentThings to know when authoring for Eclipse output
Some highlighting and formatting elements do not output Table and simpletable
Image (only the text in the <alt> attribute or tag will display)
Object
Figure (only the text in the <desc> tag will display)
Footnote
Indexterm, indextermref
Xref
Many highlighting elements will display using the <b> (bold) tag
Monospaced text and text in text blocks will display, but not as such
Lists (ordered, unordered, and simple) are supported, but nesting beyond three levels is not; if you must use lists, it is recommended that you not nest them
IBM Software Group
20
DEMO: outputting Eclipse context files (step 1)
Set up a ditamap that points to all of the .dita files in your plugin
Example:
<?xml version="1.0" encoding="utf-8"?><!--Arbortext, Inc., 1988-2005, v.4002--><!DOCTYPE map PUBLIC "-//IBM//DTD DITA IBM Map//EN“ "..\dtd\map.dtd"><map id="my_id" title="My Title"> <topicmeta> <copyright> <copyryear year="2000"/> <copyryear year="2007"/>
<copyrholder></copyrholder> </copyright> </topicmeta>
<topicref href=“test_csh_1.dita"></topicref> <topicref href=“test_csh_2.dita"></topicref>
</map>
IBM Software Group
21
DEMO: outputting Eclipse context files (step 2)
Set properties in your Ant build file
Input ditamap (example)<property name="args.input" value="${dita.dir}${file.separator}csh_sample${file.separator}contexts.ditamap"/>
Output directory – typically will be the root folder of your plugin (example)<property name="output.dir" value="${dita.dir}${file.separator}csh_sample"/>
Custom XSL transform to produce Eclipse context format<property name="args.xsl" value="${dita.dir}${file.separator}demo${file.separator}cshelp${file.separator}xsl${file.separator}dit2context.xsl"/>
Basic transform type to use<property name="transtype" value="xhtml"/>
Output extension for Eclipse context files is “xml” <property name="args.outext" value="xml"/>
Run Ant build file (e.g., ant –f sample_csh_eclipse.xml)
IBM Software Group
22
DEMO: outputting Eclipse context files (step 3) Example output context file
<?xml version="1.0" encoding="utf-8"?>
<?NLS type="org.eclipse.help.contexts"?>
<!-- meta name="DC.Type" content="cshelp -->
<!-- meta name="DC.Title" content="sample1_context" -->
<!-- meta name="abstract" content="" -->
<!-- meta name="description" content="" -->
<!-- meta name="copyright" content="(C) Copyright IBM 2000 2007" -->
<!-- meta name="DC.Rights.Owner" content="(C) Copyright IBM 2000 2007" -->
<!-- meta name="DC.Format" content="XML" -->
<!-- meta name="DC.Identifier" content="csh_outer_container" -->
<!-- meta name="DC.Language" content="en-us" -->
<!-- All rights reserved. Licensed Materials Property of IBM -->
<!-- US Government Users Restricted Rights -->
<!-- Use, duplication or disclosure restricted by -->
<!-- GSA ADP Schedule Contract with IBM Corp. -->
<contexts>
<context id="s1c1" title="My Sample 1 Context 1">
<description>This is an example context file.
Here's some additional content in a paragraph.</description>
</context>
<context id="s1c2" title="My Sample 1 Context 2">
<description>This is an example context file.
Here's some additional content in a paragraph.</description>
</context>
</contexts>
IBM Software Group
23
DEMO: outputting draft-mode HTML
Set up separate Ant build file based on sample_xhtml.xml
Example: <target name="sample2csh_html" depends="integrate"> <ant antfile="${dita.dir}${file.separator}build.xml" target="init"> <!-- please refer to the toolkit's document for supported parameters, and specify them base on your needs --> <property name="args.input" value="${dita.dir}${file.separator}csh_sample$
{file.separator}contexts.ditamap"/> <property name="output.dir" value="${dita.dir}${file.separator}csh_sample"/> <property name="args.draft" value="yes"/> <property name="transtype" value="xhtml"/> </ant> </target>
Run Ant build file (e.g., ant –f sample_csh_xhtml.xml )
IBM Software Group
24
DEMO: outputting draft-mode HTMLExample DITA file
<?xml version="1.0" encoding="utf-8"?><!DOCTYPE cshelp PUBLIC "-//IBM//DTD DITA CSHelp//EN“ "..\demo\cshelp\dtd\cshelp.dtd"><cshelp id="csh_outer_container" xml:lang="en-us"><title>sample2_context</title><shortdesc></shortdesc><csbody><p><draft-comment><image href="images/screencap.jpg"></image></draft-comment></p></csbody> <cshelp id="s2c1"> <title>My Sample 2 Context 1</title> <shortdesc>This is another example context file.</shortdesc> <csprolog><csmetadata> <cswindowtitle>New Project Wizard</cswindowtitle> <cswidgetlabel>Panel level help</cswidgetlabel> </csmetadata></csprolog> <csbody> <p conref="sample1_context.dita#s1c1/p1"></p> </csbody> </cshelp> ….</cshelp>
IBM Software Group
26
DEMO: migrating Eclipse context files to DITA
Set up and run a batch file to process XML files using XSLs
Example:
d:\j2re1.4.0\bin\java -cp d:\xalan-j_2_5_1\bin\xalan.jar;d:\xalan-j_2_5_1\bin\xercesImpl.jar org.apache.xalan.xslt.Process -IN d:\ditaot\csh_migration\contexts_Workbench.xml -XSL d:\ditaot\demo\cshelp\xsl\context2contexttemp.xsl -OUT d:\ditaot\csh_migration\temp\contexts_Workbench.xml
d:\j2re1.4.0\bin\java -cp d:\xalan-j_2_5_1\bin\xalan.jar;d:\xalan-j_2_5_1\bin\xercesImpl.jar org.apache.xalan.xslt.Process -IN d:\ditaot\csh_migration\temp\contexts_Workbench.xml -XSL d:\ditaot\demo\cshelp\xsl\context2dita.xsl -OUT d:\ditaot\csh_migration\contexts_Workbench.dita
IBM Software Group
27
HTMLHelp
The HTML files generated with DITA can be compiled into a single HTMLHelp CHM file.
The CHM file can be programmatically launched to specific HTML documents and ID locations within the HTML documents.
HTMLHelp is no longer being updated by Microsoft
IBM Software Group
28
Finding your target in the HTML
To link to a DITA-sourced HTML file within a CHM, you need to know the file name and ID
CHMs produced with the DITA-OT will base the HTML name on the topic name; by default, myfile.dita will result in myfile.html
Topic IDs will remain the same; so, <topic id=“mything”> will result in an ID of “mything” – you can link to myfile.html#mything
Element IDs combine with the topic ID; <section id=“sect”> within the the topic with id=“mytopic” results in an ID of “mytopic__sect” in the HTML
IBM Software Group
29
Linking C code to HTMLHELP CHM files
1. Include htmlhelp header. #include "htmlhelp.h"
2. Call the HtmlHelp function in your code. HtmlHelp(GetDesktopWindow(), "ditahelp.chm::/misc.htm#vo",
HH_DISPLAY_TOPIC, 0);
3. Link with htmlhelp.lib
The header and library files are included in HTML Help Workshop.
Here is a description the HtmlHelp function from http://msdn2.microsoft.com/en-us/library/ms670169.aspx
Top Related