IBM Software Group ® Context-Sensitive Help with the DITA Open Toolkit Jeff Antley IBM October 4,...

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>This view 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

10

DEMOS

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

12

DEMO: authoring content

Eclipse context file CSH DITA file

IBM Software Group

13



IBM Software Group

14



IBM Software Group

15



IBM Software Group

16



IBM Software Group

17



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> Here's some additional content in a paragraph. </csbody> </cshelp> <cshelp id="s1c2"> <title>My Sample 1 Context 2</title> <shortdesc>This is an example context file.</shortdesc> <csbody> </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 (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"?><!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"?>



























<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">  <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><draft-comment><image href="images/screencap.jpg"></image></draft-comment></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> </csbody> </cshelp> ….</cshelp>

IBM Software Group

25

DEMO: outputting draft-mode HTMLExample output

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

IBM Software Group

30

QUESTIONS?

IBM Software Group ® Context-Sensitive Help with the DITA Open Toolkit Jeff Antley IBM October 4,...

Documents

Transcript of IBM Software Group ® Context-Sensitive Help with the DITA Open Toolkit Jeff Antley IBM October 4,...