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 Plus
• WebHelp AIR

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 2005 developers. It includes a freely redistributable viewer (MadCap Help Viewer), as well as components for the Visual Studio 2005 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. 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. 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 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 or Windows Server 2003, as well as Microsoft Internet Information Services (IIS), ASP.NET, and Microsoft Indexing Service. 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 or Windows Server 2003.

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

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 Plus
.NET integration
Context-sensitive Help (CSH)
Embedded CSH (embed CSH in application)
Feedback statistics and reporting features
Language support for Help interface
Platform—Desktop-based
Platform—Web-based
Server—advanced features
Single output file
Main entry file extension	.mchelp	.chm	.htm	.air	.htm
Output window	MadCap Help Viewer	Microsoft HTML Help Viewer	Browser window	Application window	Browser window
Other requirements	MadCap DotNet Help Viewer	Internet Explorer		Java Runtime Environment (JRE) Adobe AIR	IIS ASP.NET MS Indexing Service

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

• PDF
• XHTML
• 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.The output appears as one long book, even if the project consists of hundreds of topics. After you generate the output directly (without going through another application, such as Word), you can view and print the 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 collection of files that you can print or distribute to users. This includes:

• A file with a .pdf extension. This is the file that contains the consolidated topic content from your project. This is the main file and the only one that you need to distribute.
• A file with an .mcbook extension. This is the main file that allows you to view the document with additional navigation in MadCap's built-in Book Viewer. It is necessary only for viewing the document in the MadCap Book Viewer. Otherwise, you do not need this file.
• A file with an .fltoc extension. This is the file that is generated if you have incorporated a table of contents into the book. It is necessary only for viewing the document in the MadCap Book Viewer. Otherwise, you do not need this file.
• A Resources folder with various ancillary files, such as style sheets and images. They are necessary only for viewing the document in the MadCap Book Viewer. Otherwise, you do not need these files.

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. The output appears as one long book, even if the project consists of hundreds of topics. You can view the XHTML output in MadCap's Book Viewer and print the output from there.

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 file with an .fltoc extension. This is the file that is generated if you have incorporated a table of contents into the book.
• 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 (as long as you have Microsoft .NET Framework 3.0 installed on your computer, which 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). The output appears as one long book, even if the project consists of hundreds of topics. After you generate the output directly (without going through another application, such as Word), you can view and print the output.

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 file with an .mcbook extension. This is the main file that allows you to view the document with additional navigation in MadCap's built-in Book Viewer. It is necessary only for viewing the document in the MadCap Book Viewer. Otherwise, you do not need this file.
• A file with an .fltoc extension. This is the file that is generated if you have incorporated a table of contents into the book. It is necessary only for viewing the document in the MadCap Book Viewer. Otherwise, you do not need this file.
• A Resources folder with various ancillary files, such as style sheets and images. They are necessary only for viewing the document in the MadCap Book Viewer. Otherwise, you do not need these files.

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	MadCap Book Viewer, browser window, or Adobe PDF Reader	MadCap Book Viewer or browser window	MadCap Book Viewer or browser window	Microsoft Word	Adobe FrameMaker

Note: The MadCap Book Viewer is simply used for viewing the output after generating it from Flare. The Book Viewer is not redistributable. However, end users can still view PDF output using a browser window or the Adobe PDF Reader, and they can view XHTML or XPS outputs from browser windows.

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.