IBM Software Group ContextSensitive Help with the DITA
® IBM Software Group Context-Sensitive Help with the DITA Open Toolkit Jeff Antley IBM October 4, 2007
IBM Software Group 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: 4 Installing the cshelp plugin into DITA-OT 4 Authoring CSH content in DITA 4 Outputting Eclipse context files 4 Outputting draft-mode HTML (useful for technical or editorial review) 4 Migrating Eclipse context files to DITA 4 Creating HTMLHelp 2
IBM Software Group 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 3
IBM Software Group 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) 4
IBM Software Group 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> 5
IBM Software Group 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 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) 6
IBM Software Group DITA to the rescue § Allows CSH to use the same tag set and tooling as other DITAbased 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 7
IBM Software Group CSH DITA specialization – the strategy § Enable DITA -> Eclipse context file format No text § Enable migration of existing Eclipse context files to DITA No text § Allow DITA -> HTML output No text § Do not preclude specialization from being used for other output formats No text No text 8
IBM Software Group CSH DITA specialization – the technical details § Enable DITA -> Eclipse context file format 4 dit 2 context. xsl is used to transform. dita files to Eclipse context (. xml) files § Enable migration of existing Eclipse context files to DITA 4 context 2 contexttemp. xsl 4 context 2 dita. xsl § Allow DITA -> XHTML output 4 Standard DITA-OT transforms can be used § Do not preclude specialization from being used for other output formats 4 cshelp. dtd and cshelp. mod add only minor changes from topic: • • 9 csprolog csmetadata cswindowtitle cswidgetlabel
IBM Software Group DEMOS 10
IBM Software Group 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 ) 11
IBM Software Group DEMO: authoring content Eclipse context file 12 CSH DITA file
IBM Software Group DEMO: authoring content Eclipse context file 13 CSH DITA file
IBM Software Group DEMO: authoring content Eclipse context file 14 CSH DITA file
IBM Software Group DEMO: authoring content Eclipse context file 15 CSH DITA file
IBM Software Group DEMO: authoring content Eclipse context file 16 CSH DITA file
IBM Software Group DEMO: authoring content Eclipse context file 17 CSH DITA file
IBM Software Group DEMO: authoring content cshelp/csh_sample/sample 1_context. dita <? xml version="1. 0" encoding="utf-8"? > <!DOCTYPE cshelp PUBLIC "-//IBM//DTD DITA CSHelp//EN" ". . democshelpdtdcshelp. dtd"> <cshelp id="csh_outer_container" xml: lang="en-us"> <title>sample 1_context</title> <shortdesc/> <csbody/> <cshelp id="s 1 c 1"> <title>My Sample 1 Context 1</title> <shortdesc>This is an example context file. </shortdesc> <csbody> <p id="p 1">Here's some additional content in a paragraph. </p> </csbody> </cshelp> <cshelp id="s 1 c 2"> <title>My Sample 1 Context 2</title> <shortdesc>This is an example context file. </shortdesc> <csbody> <p conref="sample 1_context. dita#s 1 c 1/p 1"></p> </csbody> </cshelp> 18
IBM Software Group DEMO: authoring content Things to know when authoring for Eclipse output § Some highlighting and formatting elements do not output 4 Table and simpletable 4 Image (only the text in the <alt> attribute or tag will display) 4 Object 4 Figure (only the text in the <desc> tag will display) 4 Footnote 4 Indexterm, indextermref 4 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 19
IBM Software Group 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“ ". . dtdmap. dtd"> <map id="my_id" title="My Title"> <topicmeta> <copyright> <copyryear="2000"/> <copyryear="2007"/> <copyrholder></copyrholder> </copyright> </topicmeta> <topicref href=“test_csh_1. dita"></topicref> <topicref href=“test_csh_2. dita"></topicref> </map> 20
IBM Software Group 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}dit 2 context. 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) 21
IBM Software Group 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="sample 1_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="s 1 c 1" 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="s 1 c 2" title="My Sample 1 Context 2"> <description>This is an example context file. Here's some additional content in a paragraph. </description> </contexts> 22
IBM Software Group DEMO: outputting draft-mode HTML § Set up separate Ant build file based on sample_xhtml. xml Example: <target name="sample 2 csh_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 ) 23
IBM Software Group DEMO: outputting draft-mode HTML Example DITA file <? xml version="1. 0" encoding="utf-8"? > <!DOCTYPE cshelp PUBLIC "-//IBM//DTD DITA CSHelp//EN“ ". . democshelpdtdcshelp. dtd"> <cshelp id="csh_outer_container" xml: lang="en-us"> <title>sample 2_context</title> <shortdesc></shortdesc> <csbody> <p><draft-comment><image href="images/screencap. jpg"></image></draft-comment></p> </csbody> <cshelp id="s 2 c 1"> <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="sample 1_context. dita#s 1 c 1/p 1"></p> </csbody> </cshelp> …. </cshelp> 24
IBM Software Group DEMO: outputting draft-mode HTML Example output 25
IBM Software Group DEMO: migrating Eclipse context files to DITA § Set up and run a batch file to process XML files using XSLs Example: d: j 2 re 1. 4. 0binjava -cp d: xalan-j_2_5_1binxalan. jar; d: xalan-j_2_5_1binxerces. Impl. jar org. apache. xalan. xslt. Process -IN d: ditaotcsh_migrationcontexts_Workbench. xml -XSL d: ditaotdemocshelpxslcontext 2 contexttemp. xsl -OUT d: ditaotcsh_migrationtempcontexts_Workbench. xml d: j 2 re 1. 4. 0binjava -cp d: xalan-j_2_5_1binxalan. jar; d: xalan-j_2_5_1binxerces. Impl. jar org. apache. xalan. xslt. Process -IN d: ditaotcsh_migrationtempcontexts_Workbench. xml -XSL d: ditaotdemocshelpxslcontext 2 dita. xsl -OUT d: ditaotcsh_migrationcontexts_Workbench. dita 26
IBM Software Group 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 27
IBM Software Group 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 topic with id=“mytopic” results in an ID of “mytopic__sect” in the HTML 28
IBM Software Group Linking C code to HTMLHELP CHM files 1. Include htmlhelp header. 4 #include "htmlhelp. h" 2. Call the Html. Help function in your code. 4 Html. Help(Get. Desktop. Window(), "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 Html. Help function from § http: //msdn 2. microsoft. com/en-us/library/ms 670169. aspx 29
IBM Software Group QUESTIONS? 30
- Slides: 30