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

2. 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

3. 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….”online help -- Wikipedia

4. 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)

5. IBM Software Group 5 How is CSH authored/sourced? (Eclipse example) Choose the type of resource you would like to create. …

6. 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: This view shows all resources in the workspace, including: - HTML files - Java files - Java source files - Class files - XML files  Hard to review (peer, technical, or editorial)

7. 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

8. IBM Software Group 8 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

9. 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

10. IBM Software Group 10 DEMOS

11. 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 /demo directory  Run Ant integrator build file ( ant -f integrator.xml )

12. IBM Software Group 12 DEMO: authoring content Eclipse context fileCSH DITA file

13. IBM Software Group 13 DEMO: authoring content Eclipse context fileCSH DITA file

14. IBM Software Group 14 DEMO: authoring content Eclipse context fileCSH DITA file

15. IBM Software Group 15 DEMO: authoring content Eclipse context fileCSH DITA file

16. IBM Software Group 16 DEMO: authoring content Eclipse context fileCSH DITA file

17. IBM Software Group 17 DEMO: authoring content Eclipse context fileCSH DITA file

18. IBM Software Group 18 DEMO: authoring content cshelp/csh_sample/sample1_context.dita sample1_context My Sample 1 Context 1 This is an example context file. Here's some additional content in a paragraph. My Sample 1 Context 2 This is an example context file.

19. IBM Software Group 19 DEMO: authoring content Things to know when authoring for Eclipse output  Some highlighting and formatting elements do not output  Table and simpletable  Image (only the text in the attribute or tag will display)  Object  Figure (only the text in the 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

20. 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:

21. IBM Software Group 21 DEMO: outputting Eclipse context files (step 2)  Set properties in your Ant build file Input ditamap (example) Output directory – typically will be the root folder of your plugin (example) Custom XSL transform to produce Eclipse context format Basic transform type to use Output extension for Eclipse context files is “xml”  Run Ant build file (e.g., ant –f sample_csh_eclipse.xml )

22. IBM Software Group 22 DEMO: outputting Eclipse context files (step 3)  Example output context file This is an example context file. Here's some additional content in a paragraph. This is an example context file. Here's some additional content in a paragraph.

23. IBM Software Group 23 DEMO: outputting draft-mode HTML  Set up separate Ant build file based on sample_xhtml.xml Example: <!-- please refer to the toolkit's document for supported parameters, and specify them base on your needs -->  Run Ant build file (e.g., ant –f sample_csh_xhtml.xml )

24. IBM Software Group 24 DEMO: outputting draft-mode HTML Example DITA file sample2_context My Sample 2 Context 1 This is another example context file. New Project Wizard Panel level help ….

25. IBM Software Group 25 DEMO: outputting draft-mode HTML Example output

26. 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

27. 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

28. 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, will result in an ID of “mything” – you can link to myfile.html#mything  Element IDs combine with the topic ID; within the the topic with id=“mytopic” results in an ID of “mytopic__sect” in the HTML

29. 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

30. IBM Software Group 30 QUESTIONS?