Determining the Output Type

There is a fine line between what is called "online output" and what is called "print-based" output. The truth is that topics in virtually any of Flare's online output types can be sent to a printer (and therefore considered "print-based"). Similarly, any of the print-based output types can be viewed electronically (and therefore considered "online"). The real distinction between online and print-based outputs has to do with their primary purpose. Online outputs are usually intended to be viewed on a screen, rather than on a printed page. The idea is to show only small pieces of content at a time and allow users to jump around to other topics or elements of the output. On the other hand, print-based output follows a more traditional format that you would find in an actual book or manual—with the pieces of the output following one after the other on pages until the end of the book (e.g., title page, table of contents, preface, chapters, index, appendixes—with page numbers, as well as header or footer content, shown along the way).

Following are overviews of each of Flare's online output types.

• DotNet Help
• HTML Help
• WebHelp
• WebHelp AIR
• WebHelp Mobile
• WebHelp Plus

About DotNet Help Output

DotNet Help is a Help output format developed by MadCap Software for Windows desktop applications. It was designed to include the best attributes of HTML Help and WebHelp, while filling the holes left behind by those formats. DotNet Help is designed specifically to support Visual Studio developers. It includes a freely redistributable viewer (MadCap Help Viewer), as well as components for the Visual Studio developer. These components can be dropped into your Flare project to facilitate context-sensitive Help, embedded Help, and features such as automated search string communication between the application and the DotNet Help documentation.

The DotNet Help output consists of a collection of files that you will distribute to users with the freely downloadable MadCap Help Viewer. The main entry file has an .mchelp extension.

DotNet Help is a good choice if:

• You need a format that supports .NET applications.
• You want to produce a customizable interface that is much more modern looking than the aging HTML Help. It will blend easily into a modern Vista environment.
• You want users to be able to select between multiple languages for the interface when viewing your output. This is possible because the freely distributable MadCap Help Viewer lets users select English, French, German, or Japanese for the interface.
• You do not want users to be burdened by the security warnings and limitations that are often encountered with HTML Help and WebHelp.
• You need to include features that are not available with HTML Help.
• You want to create embedded context-sensitive Help in a .NET application. This includes the ability to produce Dynamic Help.
• You want to include search functionality that supports wildcard searches.

Flare's online Help uses DotNet Help.

About HTML Help Output

HTML Help is an HTML-based Help format that runs on Windows 32-bit platforms and requires Internet Explorer on the end users' systems. You can use HTML Help to create Help for Windows desktop applications.

The HTML Help output consists of a single CHM file that you will distribute to users.

HTML Help is a good choice if:

• You are writing Help for a 32-bit Windows application.
• Your users will have Internet Explorer on their system.
• Your users don't have a network connection.
• You want to create output that has just one file.

Note: Your users need Internet Explorer (4.0 or later) installed and a 32-bit Windows operating system (Windows 95 or later).

About WebHelp Output

WebHelp is a Web-based Help format that can run on almost any browser or platform. You can use WebHelp to create online documentation for the Internet or an intranet, as well as for desktop applications.

The WebHelp output consists of a collection of files that you will distribute to users. The output will be displayed in the user's Internet browser window. The main entry file has an .htm extension.

WebHelp is a good choice if:

• You are writing online documentation for distribution on the Internet or an intranet.
• You want to be able to produce an output interface in various languages. This is possible through the use of language skins.
• You want the flexibility to include the online documentation in a desktop application.
• Your users have different Internet browsers on their systems.
• Your users are working on different platforms.

About WebHelp AIR Output

WebHelp AIR is a Web-based Help format that is identical to the regular WebHelp output in most ways. However, WebHelp AIR uses direct integration with Adobe AIR, which is designed to bring Web-related content to a desktop environment by taking Web files and incorporating them into a single file to be opened locally, rather than from a server. 

The WebHelp AIR output that you generate consists of a single file with an .air extension, which you distribute to users. When users access this file, they are taken through an installation process, and as a result an executable file with an .exe extension is created on their local drive and saved in their C:\Program Files directory. In other words, the output becomes its own application. The output will be displayed in the application window that is part of the AIR installation.

WebHelp AIR is a good choice if:

• You want all of the features and benefits available with WebHelp.
• You want to be able to distribute a single file, as opposed to multiple output files.
• You want users to store and open the output locally, rather than from a server, such as a website.
• You want to create output that has just one file.
• You want users to be able to install the file not only in Windows, but in a Macintosh and Linux environment as well.

In order for you and your end users to take advantage of this output, both you and they must perform additional installations.

• Java Runtime Environment installation (you) As the individual compiling the output, you need to install the Java Runtime Environment (JRE) before generating output.

  You can download the JRE from http://java.sun.com/javase/downloads/index.jsp.

• Adobe AIR installation (you and end users) Anyone who wants to view the generated WebHelp AIR output needs to install Adobe AIR first. This means that both you and your end users must run this installation.

  You can download Adobe AIR from http://get.adobe.com/air/.

About WebHelp Mobile Output

WebHelp Mobile is an output type that lets you deploy Web-based, XHTML output to mobile devices. WebHelp Mobile maintains an easy and intuitive interface that fits on a very small screen. The Home page in WebHelp Mobile output contains navigation links to access the various panes that you can include: TOC, Index, Glossary, Search, Favorites, Browse Sequences.

The WebHelp Mobile output consists of a collection of files that you distribute to users by placing them on a Web server. End users then use their mobile device to open those files, just as they would open any website. The output will be displayed in the user's mobile browser. The main entry file has an .htm extension.

WebHelp Mobile is a good choice if:

• Your end users are on the move and need to be able to access your documentation on their mobile devices.
• You want to be able to produce an output interface in various languages. This is possible through the use of language skins.
• Your users are working on different mobile platforms. Some of the major platforms supported are iPhone, Windows Mobile, and Blackberry.

Note: Some older mobile browsers do not support certain features (e.g., DHTML, search), whereas newer mobile browsers do support them. Other features, such as "mouse over," are not supported in either older or newer mobile browsers.

example

Let's say you want to create WebHelp Mobile output so that end users can see your documentation on their cell phones. In the skin associated with the target, you specify that the output should include a TOC, an index, a glossary, and search. After generating the output, the home page might look something like this:

About WebHelp Plus Output

WebHelp Plus is a Web-based Help format that is identical to the regular WebHelp output in most ways. However, WebHelp Plus is designed to work on a Web server running Windows XP, Windows Server 2003, Windows Server 2008, Windows 7, or Windows Vista. It also uses Microsoft Internet Information Services (IIS) and ASP.NET. To provide faster search, WebHelp Plus uses Microsoft Indexing Service (for Windows XP and Windows Server 2003) or Windows Search (for Windows Server 2008). The benefit of publishing WebHelp Plus output is that you and your users can take advantage of some advanced features, including searching of non-XHTML content, faster server-side search, and automatic runtime merging. See About Advanced Server Features in WebHelp Plus.

The WebHelp Plus output consists of a collection of files that you will distribute to users by publishing output to a Microsoft IIS Web server. The output will be displayed in the user's Internet browser window. The main entry file has an .htm extension.

WebHelp Plus is a good choice if:

• You want all of the features and benefits available with WebHelp.
• You want users to experience faster searches in your output.
• You want non-XHTML files (e.g., PDFs, Excel spreadsheets) to be included in searches that users perform in your output (even if those non-XHTML files are not part of your project).
• You want to automatically merge the output for multiple Flare projects so that they appear as one large Help system to end users.
• You publish your output to a machine running Windows XP, Windows Server 2003, Windows Server 2008, Windows 7, or Windows Vista.

Output Type Comparison Table—Online Output Types

Following are the various online output types available, with the distinguishing features of each.

	DotNet Help	HTML Help	WebHelp	WebHelp AIR	WebHelp Mobile	WebHelp Plus
General
.NET integration		.	.	.	.	.
Main entry file extension	.mchelp	.chm	.htm	.air	.htm	.htm
Output window	MadCap Help Viewer	Microsoft HTML Help Viewer	Browser window	Application window	Mobile Web browser	Browser window
Platform	Desktop	Desktop	Web	Desktop	Mobile Web	Web
Single output file	.		.		.	.
Special requirements	MadCap DotNet Help Viewer	Internet Explorer	.	Java Runtime Environment (JRE) Adobe AIR	.	IIS ASP.NET MS Indexing Service
Accessibility (e.g., Section 508, WCAG)
Accessibility supported	.	.
Context-sensitive Help (CSH)
CSH supported				.
Embedded CSH supported
Feedback statistics and reporting features
Feedback supported				.	.
Search results		.		.	.
Generated content
Breadcrumbs
Browse sequences
Concept links
Glossaries
Indexes
Keyword links
Mini-TOCs
Related topics links
Relationship links
Scripts
Shortcut controls	.		.	.	.	.
TOCs
Topic toolbars
Language support
Content—display in any left to right language
Output interface—display in any left to right language	.	.
Output interface—display English, French, Japanese, or German	Possible with Help Viewer (end user selects language)	.	.	.	.	.
Master pages
Master pages supported
Merging output
Merge output supported
Merge output at runtime	.	.	.	.	.
Multimedia
Audio					If mobile browser supports it
Movies					If mobile browser supports it
Search
Search supported
Include/exclude topics in search		.			Only supported in newer mobile browsers
Search filter sets		.			.
Search non-XHTML files				.	.
Stop words		.			Only supported in newer mobile browsers	Uses indexing service
Synonyms		.			Only supported in newer mobile browsers
Wildcard searches supported		.	.	.	.	.
Skin settings
About box	.
Accordion titles	.	.			.
Browser settings	.	.		.	.
Caption for output window	.
Elements (e.g., tabs, accordions)—specify default element	.				.
Elements (e.g., tabs, accordions)—specify which to include
Feedback user profile				.	.
Index—binary	.		.	.	.	.
Index—include bookmarks in index entries	.		.	.	.	.
Language skins	.
Navigation links in standalone topics	.	.			.
Navigation pane settings	.				.
Preview skin for output type				.
Size/position—specify					.
Styles	Only some styles (e.g., Feedback, toolbar) are supported.	Only some styles (e.g., Feedback, toolbar) are supported.
TOC—binary	.		.	.	.	.
TOC—synchronize with topics					.
Topic toolbar custom settings					Limited settings
Target settings
Accessibility warnings	.	.
Characters and spaces—replace with underscores
Content folder—omit from output					.
DOCTYPE declaration					Standard mobile DOCTYPE always used
File extensions—custom	.	.
Images—pre-compile resized
Images—Web-safe
Language—select for output interface	.	.
Mark of the Web	.	.		.	.
Master page
Skins—generate all
Startup topic					.
Style sheet medium

Following are overviews of each of Flare's print-based output types.

• Adobe PDF
• XHTML
• Microsoft XPS
• Microsoft Word
• Adobe FrameMaker

About PDF output

Short for "Portable Document Format," PDF is an open file format created by Adobe. PDF files represent two-dimensional documents in a device-independent and resolution-independent fixed-layout document format. You can generate PDF output from your project directly, or you can generate a PDF while simultaneously building FrameMaker or Word output.

PDF is a good choice if:

• You want to use a format with which most end users are familiar.
• You want users to be able to view the book online, as well as print it.

PDF output consists of a file with a .pdf extension that you can print or distribute to users.

You can also set PDF options in the Target Editor. These options let you specify the way that images, document properties, the initial view, and security are handled in the output. See Specifying PDF Options.

About XHTML output

XHTML is a browser-based output type that consolidates project content in an XML file. It can be viewed online or printed.

XHTML is a good choice if you need an "intermediary" format for your large, custom, enterprise level proprietary systems. You can easily transform Flare-authored content into your own system. By creating the single file output, you can feed it into your own parser/transform and convert all of the Flare content to your internal formats. This is part of the flexibility that allows Flare to be integrated into just about any tool chain or work flow. If you do not have a situation like that, you may find one of the other formats to be a more suitable option for you.

XHTML consists of a collection of XHTML files that you can print or distribute to users. This includes:

• A file with an .htm extension. This is the XHTML file that contains the consolidated topic content from your project.
• A file with an .mcbook extension. This file is used to display the chapters in the MadCap Book Viewer.
• A Resources folder with various ancillary files, such as style sheets and images.

If you want to make XHTML output accessible for others, you need to include all of the files in the output mentioned in this list. Otherwise, when they view the output, certain elements (e.g., images) might be missing from the pages.

About XPS output

Microsoft's XML Paper Specification (XPS) is a document format with a markup language that is a subset of XAML for Windows Presentation Foundation. XPS is an alternative to Adobe's Portable Document Format (PDF). You can generate XPS output from your project directly. Make sure you have the latest version of Microsoft .NET Framework installed on your computer. This is a free download from microsoft.com. Alternatively, you can generate XPS output while simultaneously building Word 2007 output (by installing a free add-in download from Microsoft).

XPS is a good choice if:

• You want to create output in a smaller file size than you would get from Adobe PDF.
• You want users to be able to view the book online, as well as print it.
• You want to take advantage of the benefits provided by XPS, such as better print quality, easy file sharing, and enhanced security.

XPS output consists of a collection of XPS files that you can print or distribute to users. This includes:

• A file with an .xps extension. This is the file that contains the consolidated topic content from your project. This is the main file and the only one that is essential. This is the file that you would provide to a printer or distribute to end users.
• A Resources folder with various ancillary files, such as style sheets and images.

If you want users to download an XPS document from a server (e.g., from a website), you need to enable the server to do this by registering the MIME types and file extensions. See Registering MIME Types and File Extensions for XPS Output.

About Microsoft Word Output

Word is an output type where the generated project is exported to Microsoft Word in one of the following formats: XML (default), DOC, DOCX, XPS, PDF. However, you can also create PDF or XPS output directly, without going through Word.

Note: Unless you specify otherwise, the Word target will create files with an .xml extension only. If you want to use one of the other formats see Specifying DOCX Output Via Microsoft Word, Specifying XPS Output Via Microsoft Word, and Specifying PDF Output Via Word or FrameMaker.

Note: Flare supports Microsoft Word 2003 and newer versions.

Note: To create output in DOCX or XPS format, you need to have Microsoft Word 2007 installed. Also, Word 2007 allows you to create PDF files from Word without needing to have the Adobe Distiller installed.

About Adobe FrameMaker Output

FrameMaker is an output type where the generated project is exported to Adobe FrameMaker in one of the following formats: BOOK, FM, PDF. However, you can also create PDF output directly, without going through FrameMaker.

Note: Unless you specify otherwise, the FrameMaker target will create BOOK or FM files only. If you want to create a PDF file from your Flare project, see Specifying PDF Output Via Word or FrameMaker.

Note: Flare supports FrameMaker 7.0 and newer versions.

Output Type Comparison Table—Print-based Output Types

Following are the various print-based output types available, with the distinguishing features of each.

	PDF	XHTML	XPS	MS Word	FrameMaker
Primary benefits	Familiar to many users	Good for large, custom, enterprise level systems	Smaller file size than PDF Better print quality Easy file sharing Enhanced security	Work with output in Word	Work with output in FrameMaker
Main entry file extension	.pdf	.htm	.xps	.xml (default)	.fm or .book
Output files necessary to distribute	.pdf file only	All files generated	.xps file only	All files generated	All files generated
Program used to view output	Browser window or Adobe PDF Reader	Browser window	Browser window	Microsoft Word	Adobe FrameMaker

Darwin Information Typing Architecture (DITA) file content is supported in Flare. DITA is an XML-based markup language with its own schema for authoring, producing, and delivering technical information. It is a standard of the Organization for the Advancement of Structured Information Standards (OASIS), and it consists of a set of design principles for creating "information-typed" modules at a topic level and for using that content in various delivery modes.

DITA allows companies (especially larger ones) to maintain better consistency throughout its documentation by establishing structural rules and standards for all of its authors to follow. The idea is that writers will spend more of their time authoring content, rather than worrying about the presentation of that information.

In Flare you can generate output that produces DITA files. When you build this type of output, a DITA map file is generated, with multiple DITA files in it. The XHTML tags are converted to DITA elements. In other words, although it is considered an "output" from the standpoint of the Flare process, the end result is actually a collection of "source" files, which you can later use in another tool (or import back into Flare) to produce the final output.