RoboHelp X5 and XML

1
RoboHelp X5 and XML
2

• XML In Four Slides
• RoboHelps XML Features
• Demo
• Peculiarities
• Customization
• Summary Observations

3

• XML In Four Slides

4
XML Overview - 1 of 4

• Whats XML?
• Not a language but a meta-language a set of
  rules for creating other languages.
• Create custom tags or entire languages.
• Define and enforce syntax rules.
• A master format convertible to other formats -
  single-sourcing.

5
XML Overview - 2 of 4

• Three major sub-parts
• XML Content.
• DTD/schema Syntax rules.
• CSS/XSL Display and format conversion rules.

6
XML Overview - 3 of 4

• Two levels of syntax adherence
• Well-formed Follows a generic set of rules.
• Valid Follows custom rules defined in a DTD or
  schema and is well-formed.
• Adherence is mandatory, unlike in HTML.

7
XML Overview - 4 of 4

• Two types of output style control
• CSS Simple but limited.
• XSL More powerful, extensible. Consists of
• XSLT Transforms XML to other formats.
• XSL-FO Transforms XML to hard-copy.
• XPath Identifies specific elements to be
  formatted.

8

• RoboHelps XML Features

9
Three Crucial Points

• RoboHelp supports export and import but not
  native XML authoring.
• XML use is still rare and evolving in the
  RoboHelp community.
• XML itself is still evolving.

10
Export Features

• XML Output Options dialog box.

11
Export Features

• Exports entire project or topics to XHTML and
  DocBook.
• Different outputs export different files
• Project Topics and graphics, with
  (Full-Featured) or without (Content) navigation
  control files, CSS, and DHTML files.
• Topics Topics and graphics.
• Your selection depends on what you want to do
  with the exported files.

12
Some Export Notes - DocBook

• Output files are not directly viewable in a
  browser.
• Must be converted to a viewable format like HTML,
  PDF, or Postscript.
• For example

13
A File In RoboHelps Preview

14
and Exported to DocBook

15
and Displayed In IE

16
Some Export Notes - XHTML

• Output files have an HTM extension.
• Can cause problems discussed later under
  Peculiarities.
• Output files display properly formatted in a
  browser.
• Because XHTML is basically HTML, as shown in the
  next two slides.

17
Display Control In HTML

• How an HTML file calls a CSS

18
Display Control In XHTML

• How an XHTML file calls a CSS
• Note the similarity to HTMLs CSS reference.

19
Import Features

• Imports DocBook and XHTML, and raw XML with or
  without a DTD/schema or CSS/XSL.
• If a file points to a DTD/schema, you can
  validate the XML file upon import.
• RoboHelp wont import an invalid XML file or one
  with a missing DTD/schema.
• If a file doesnt point to a DTD/schema, you can
  specify one during import.

20
Some Import Notes

• When importing XML, you can
• Strip out all formatting the text flow option.
• Simulate the display of nested elements in a
  browser the tree view option.
• For example

21
Text Flow Option

22
Tree View Option

23

• Demo

24
Review of the Project to Export

• The RoboHelp XML Test project.
• Exporting project to DocBook and XHTML.
• Exporting topics to DocBook and XHTML.

25
Review of XML Topic to Import

• Sample1.xml no DTD.
• Importing as text flow.
• Importing as tree view.
• Importing with a DTD.

26

• Peculiarities

27
XHTML File Extensions

• When you export to XHTML, RoboHelp assigns an HTM
  extension to the files.
• This causes several problems
• You cant distinguish XHTML files from HTML files
  by eye.
• Its possible to import an HTML file with an HTM
  extension under the misconception that its an
  XHTML file.

28
XHTML File Extensions

• So what extension can you use?
• XHTML Good choice. No risk of confusion.
• XHT Recommended by IETF in 2000 (along with
  XML) but less familiar than XHTML.
• HTM Yes, but consider the problems.
• XML Not for XHTML files due to possible server
  confusion over whether such files are to be
  handled as application/xml or text/xml.
• XTM No. For Extensible Topic Map files.

29
Exporting Projects to XHTML

• This feature looks much like the WebHelp
  generation feature.
• But it doesnt create XHTML WebHelp.
• What seems to be the start file is simply a log
  of the output files.
• Youll need to process this output further to
  make it usable.

30
Importing XHT Files

• The built-in XHTML import handlers only recognize
  XML and XHTML extensions.
• To import other XHTML file extensions, you need
  to modify an existing handler or create a new
  one.
• Youll use the Handler Description File Editor to
  do so.

31

• Customization

32
Handlers

• Essentially scripts that import and export files
  in or to different formats.
• RoboHelp X5 has pre-defined handlers for common
  XML formats
• DocBook.
• XHTML.
• XML.

33
Handler Customization

• You can modify existing handlers or create new
  ones if you need to
• Deal with a less-common format, like DITA.
• Deal with a variant on a common format, like the
  XHT extension for XHTML files.

34
The Handler Description File (HDF)

• The HDF
• Acts like a category that contains a group of
  individual (usually related) handlers.
• Contains the control files that perform the
  actual imports and exports.

35
Handler Creation

• The HDF Editor is a separate application, so the
  process is to
• Create the handler and define its parameters in
  the HDF Editor.
• Import the HDF into RoboHelp.
• It appears in the list of HDFs in the XML Handler
  Manager and in the Handler Description field
  pulldowns for export and import.

36
XML Handler Manager
37
Some HDF Editor Options Import File

• Import handler sample General tab

38
Some HDF Editor Options Import File

• Import handler sample Advanced tab

39
Some HDF Editor Options Export Project

• Export project handler sample General tab

40
Some HDF Editor Options Export Project

• Export project handler sample Advanced tab

41

• Summary Observations

42
Summary Observations

• No pre-defined XHTML outputs yet.
• No XHTML WebHelp for example.
• Plan to do post-processing if you export out.
• Set and enforce DTD/schema referencing standards
  for validity checking on import.
• Set and enforce file extension standards for
  XHTML to reduce the need for additional import
  handlers.

43
Summary Observations

• Accept the fact that youll be working at a
  higher than normal technical level.
• Need to create handler processing files (the
  transform entry point) as DLL, EXE, XSL, or BAT
  files.
• Very little documentation.
• Almost no explanation as to why youd pick one
  over another.
• Youre in somewhat uncharted waters.

44
Thank you... Questions? Hyper/Word
Services 978-657-5464 nperlin_at_concentric.net www.h
yperword.com