Format Guide
Contents
Dynamic HTML
This is a basic format in terms of appearance, but it offers some desirable features as well as the flexibility to be customized for almost any implementation. Dynamic HTML is created with XHTML, CSS, and some JavaScript. Its is displayed in a single browser pane, with a simple TOC and Index generated separately from topic pages. Each page may contain navigation buttons, breadcrumbs, dropdowns, and related topics.
Dynamic help is a good starting point for people wanting a customized output format (the WebWorks.com website format is based on DHTML). It also offers simplicity and fast performance with low file size and load time. It’s good for online deployment and local installation. The downsides are that it isn’t very “pretty” out-of-the-box, it doesn’t offer a Search option, and there is no context-sensitive help.
The Dynamic HTML format can be used to produce XHTML output that conforms to XHTML 1.0 standards and uses Cascading Style Sheets that conform to the CSS1 standard. XHTML became a W3C recommendation in 2000.
When to use Dynamic HTML
Dynamic HTML is recommended for use if you need to produce output that will be published on a Web or intranet server and accessed by users with current Web browsers (i.e. Internet Explorer 4 or later , Netscape 4.x or later, Firefox 1.0 or later, etc). For the complete Dynamic HTML format guide, see DynamicHTML.
Microsoft HTML Help 1.x
HTML Help is a format which has been around for many years. It is the basic Windows help format with which most PC users are familiar. It offers a single compressed archive with a small file size, which makes it easy to distribute. You get navigation buttons and separate panes for the TOC and content. It also offers an Index and Full text search. It is based on HTML/XHTML, it uses Internet Explorer as its main viewer, and it supports popups, dropdowns, and related topics. It also supports context-sensitive help, and ePublisher automatically generates the map file (*.h) necessary for use with your application.
The benefit of using HTML Help is its simplicity and its consistency. It’s a single file, and it can be viewed on any Windows PC. It requires a separate viewer to launch a CHM on a Mac. Its weakness is in its online support—or lack thereof. Recent Windows security updates have made it impossible to directly view CHM files online or over a network. The CHM must be downloaded and launched locally. They are useful for installed apps, but are not ideal for web-based applications for this reason.
When to use Microsoft HTML Help 1.x
Microsoft HTML Help is recommend for use if you need to produce online Help for a 32-bit application that will run under Microsoft Windows 95, 98, ME, NT, 2000, or XP and you can be sure that your users have, or are prepared to install, Internet Explorer 4 or later. For the complete Microsoft HTML Help format guide, see Microsoft HTML Help.
Microsoft Reader
The Microsoft Reader format enables you to convert your source files into a single eBook that can be read with the Microsoft Reader software on handheld devices, as well as on computers that support Microsoft Reader. Projects based on the Microsoft Reader format produce a single .lit file that can be viewed using the Microsoft Reader software.
When to use Microsoft Reader
Microsoft Reader is recommended for use if you need to produce output for hand held devices that utilize Microsoft Reader software. Requirements for Viewing Microsoft Reader In order to view Microsoft Reader output files (.lit), you will need to install the Microsoft Reader software application. Microsoft Reader software is available free of charge from the Microsoft Reader Web site at http://www.microsoft.com/reader/downloads/default.asp.
Microsoft WinHelp
The Microsoft WinHelp format used to be Microsoft's standard for delivering online help for Windows-based applications. Microsoft HTML Help 1.x heventually replaced Microsoft WinHelp as Microsoft's official standard, but many companies are still delivering Microsoft WinHelp output, which is robust and stable. Like Microsoft HTML Help 1.x, the output pages and graphics produced from a Microsoft WinHelp project are compiled into a single, compressed file for delivery to end users. There are still formatting limitations, as WinHelp is based on the primitive RTF text format.
When to use Microsoft WinHelp
Microsoft WinHelp is recommended for use if you need to produce online Help for an application that will run under Microsoft Windows 95, 98, ME, NT, 2000, or XP and if you desire not to use a more modern output format. Since Microsoft WinHelp is a legacy format is no longer being developed by Microsoft, you may find that a more modern output format is often more appropriate.
Oracle Help
The Oracle Help for Java format is Oracle's Java-based online Help formats that can be used to produce the complete set of files required for an online Help system based on Oracle's Oracle Help for Java technology. Oracle Help for Java is a set of Java components and an API for developing and displaying HTML-based help content in a Java environment.
When to use Oracle Help
Oracle Help is recommened for use if you need to produce online Help for an application written in the Java programming language.
Requirements for Developing Oracle Help
In order to generate output using the Sun JavaHelp formats, you must also download and install the Java2 Platform SDK version 1.2.2 or later. You can download this software from http://java.sun.com/javase/index.jsp. In order to view a Help system in Oracle Help format, users must have a Java Virtual Machine (JVM) installed. If you need to produce online Help for a Java application, you can safely assume that a JVM will be installed on systems used to run the application. In addition, the Oracle Help components must be installed on the end user's machine.
Palm Reader
The Palm Reader format enables you to convert your source files into eBooks that can be read with the Palm Reader software on handheld devices running Palm OS and Pocket PC software, as well as on Windows and Macintosh computers. The Palm Reader template includes a preface.txt file that enables you to customize the look and feel of your final .pdb file.
When to use Palm Reader
Palm Reader is recommended for use if you need to produce output for hand held devices that utilize Palm Reader software.
Requirements for Developing Palm Reader
Before you can begin generating eBooks for Palm Reader, you must download and install DropBook, a Palm Reader utility that ePublisher Pro uses to convert generated output into a single .pdb file, as required by the Palm Reader software. You can download the DropBook utility from the eBook Reader Web site at http://www.ereader.com/dropbook/download. In order to view Palm Reader output files (.pdb), you will need to install the eBook Reader software from the eBook Reader website at http://www.ereader.com/products/ereader/pro.
The PDF format automatically creates PDF's for your individual source files, single PDF containg all source files within a group, or both.
When to use PDF
PDF is recommended for use when print quality output is a necessity.
Requirments for Viewing PDF
In order to view PDF files, insall the Adobe Acrobat Reader software on your compter. You can download the Adobe Acrobat Reader software from the Adobe website at http://www.adobe.com/products/acrobat/readstep2_allversions.html.
Simple HTML
This format is pretty self-descriptive. It is the very basic HTML necessary to reproduce most of the main formatting. There is no external CSS stylesheet; all style is defined as inline HTML. There is a basic TOC and Index, as well as navigation buttons and breadcrumbs. There are no popups or dropdowns, as JavaScript is not used.
The file footprint is small, and load time is fast. The lack of CSS means formatting is limited, and many of the options available in the Style Designer will not be transferred to the HTML output, as there are no HTML equivalents for most properties. The Simple HTML format can be used to produce HTML that conforms to the HTML 3.2 standard. The output will be compatible with most browsers on most platforms, which is the main benefit.
When to use Simple HTML
Simple HTML is recommended for use if you need to produce output that can be viewed in older Web browsers or if you need to avoid using Cascading Style Sheets, Java, and JavaScript.
Sun JavaHelp 1.1.3 & 2.0
The Sun JavaHelp formats (JavaHelp 1.1.3 and JavaHelp 2.0) can be used to produce online Help systems for applications written in the Java programming language. Sun JavaHelp uses HTML files and Cascading Style Sheets, but Sun JavaHelp is not usually displayed in a web browser. They are somewhat limited, and do not support the full list of CSS properties configurable in ePublisher. Formatting is a little quirky sometimes; some HTML elements don’t always appear the way they do in a browser. If you create Sun JavaHelp, your users will most likely view th help system in the JavaHelp viewer application or in a custom viewer application created by your application developers.
When to use Sun JavaHelp 1.1.3 & 2.0
Sun JavaHelp is recommended if you need to create online help for an application written in the Java programming language. Like many other help systems, JavaHelp includes a navigation pane on the left, with Contents, Index, and Search tabs, and a topic pane on the right, which displays the actual help topics.
Requirements for Developing Sun JavaHelp 1.1.3 & 2.0
In order to generate output using the Sun JavaHelp formats, you must download and install the Java2 Platform SDK version 1.2.2 or later . You can download this software from http://java.sun.com/javase/index.jsp. In order to a view on an online Help system in JavaHelp format, users must have the Java Runtime Environment (JRE) installed on their machines. Typically, if you are developing online Help for a Java application, it is the responsibility of the application developers to ensure that users of the application have the JRE installed.
WebWorks Help 5.0
This is one of the most popular formats, offering the most capable and aesthetic output out-of-the-box. It is based on XHTML, CSS1 & CSS2, and JavaScript, and it offers a frameset view with navigation buttons at the top, TOC on the left, and topic content on the right. It has an expandable TOC, a sorted index, full text search, and cookie-based Favorites. You can choose from multiple skins (or design your own) for a different look. It has all of the other dynamic features, such as popups, dropdowns, and related topics. It also supports context-sensitive help via a browser URL or through the WebWorks Help SDK (API), available on our Wiki.
Its main benefit is its ease of use and professional, customizable appearance. It can be deployed online or installed locally with your application. Its weakness is its heavy dependence on JavaScript, which can slow down its performance—especially when viewed over a web server—and it causes Active Content warnings in Internet Explorer when viewed locally.
When to use WebWorks Help 5.0
WebWorks Help 5.0 is recommended for use if you need to easily integrate your help system with applications written in C, C++, Java, or Visual Basic, as well as Web-based applications, which allows you to create and deploy context-sensitive help easily.
For more information, see the complete WebWorks Help 5.0 format guide.
XML+XSL
The XML+XSL format generates Extensible Markup Language (XML) data files which are formatted by an Extensible Stylesheet Language (XSL) stylesheet. This is a flexible output format that really serves as a starting point for custom targets. It provides pretty generic XML documents that are formatted by a generic XSL stylesheet. The usefulness of this format is that you can customize the XSL stylesheet such that it processes and formats the content of the XML files differently depending on things like conditions or delivery platform. It could be very useful for many implementations, but it does require knowledge of XSL and XML in order to create an XSL template that will output the content you need.
In its out-of-the-box form, it looks and behaves a lot like Dynamic HTML when viewed with a modern web browser. The basic Document.xsl turns the XML into pretty basic HTML output. It can utilize CSS and JavaScript to offer advanced styling and dropdowns. Popups are not supported by default, but I would imagine the XSL could be modified to implement that feature or any other necessary web technology. Again, it’s really just a starting point for all kinds of possible custom implementations, creating any number of formats.
When to use XML+XSL
XML+XSL is recommended for use if you need to create template rules that output specific data and perform other functions, such as sorting data and outputting data only if certain conditions exist in the XML document. You can also repurpose the data for different delivery mechanisms (for example, XML or HTML for display in a web browser or text for display on a wireless phone), by customizing the base XSL stylesheet.
