Output Types

There are several types of online output (Eclipse Help, EPUB, Microsoft Help 2.0, Microsoft HTML Help, Microsoft Help Viewer, JavaHelp, NetHelp) and one type of print-based output (Manual) that you can produce in Doc-To-Help. Each output type has its own set of advantages.

You can configure targets based on these output types by using the Help Targets dialog. See Editing Target Settings.

For more information on targets, see About Targets.

NetHelp is a cross-platform, browser-based output that is displayed in the user’s default browser. It is uncompiled HTML Help, so the number of files delivered for the project will depend on the number of topics in the project.

Also, NetHelp is jQuery-based. jQuery is a flexible web technology that separates content from presentation and is easy to customize.

If you need to create an output that can be hosted on your web server, but still be accessed through the application, you should create NetHelp. It produces HTML output that is browser-based and can be hosted locally or on any web server.

Following are some of the greatest benefits of using NetHelp:

  • True Separation of Content and Presentation Doc-To-Help outputs raw XML and NetHelp consumes it. NetHelp is merely the set of scripts and pages used to display and lay content out. In fact, you can use the raw XML output with your own systems. That is how we are able to create SharePoint wikis (see Publishing to SharePoint).
  • Best Looking, Most Themable The promise of jQuery UI is to deliver a standardized and easy-to-edit set of styling standards. That promise carries through to NetHelp. It ships with many of JQuery UI’s default themes and a few of our own. The icing on the cake is that it is simple to edit. You can use our theme designer, edit the CSS file directly, or use the Theme Roller found on jQuery UI’s website. See About Themes and Customizing NetHelp Themes.
  • Lightweight As already mentioned NetHelp output is only a set of CSS files and scripts. Files sizes are small and performance is fast.
  • Unique URLs With NetHelp output, URLs to every topic are displayed in the address bar. This helps search engine optimization (SEO) if you are deploying publicly. It also makes sending links to topics easy.

Note For more information on creating accessible NetHelp, see About Accessibility.

Note If no index entries are added to a project, the Index tab or panel will automatically not display in NetHelp outputs.

Note For more information on some tasks specific to the NetHelp output type, see NetHelp Target Tasks.

Following are browsers that support NetHelp:

  • Internet Explorer 9 or higher

  • Firefox 3 or higher

  • Opera 9.6 or higher

  • Apple Safari 3.1 or higher

  • Google Chrome (all versions)

Following are browsers that support the NetHelp responsive theme:

  • Desktop Internet Explorer 9 or higher

  • Mobile Platforms Android 4.0 or higher, iOS

Details

Pros

Issues

Deliverable File(s)

File Location

Uncompiled HTML; deliverable is multiple HTML files.

NetHelp can be Section 508 compliant. See About Accessibility.

Can be delivered on the web, installed locally, or both.

Delivering on the web makes a continuous publishing model possible.

The user’s web browser is the Help window.

Number of files to distribute is daunting to some.

Security issues can cause NetHelp installed locally to display an ActiveX warning, which may be solved by using the "Mark of the Web." See NetHelp Local Installation.

Multiple HTM/HTML files. Default home page is index.htm. (You can change the default page name in the Help Targets dialog.)

By default the NetHelp folder of your project.

The entire contents (including subfolders) of this folder must be included with your software application or posted on your server.

Server-side search may be enabled for NetHelp. See Search Options for NetHelp.

Note If you open or install NetHelp locally, it will not display in Chrome, IE Edge, or Opera because of  limitations with those browsers, but it will display in other browsers. NetHelp deployed on a web server will open in Chrome, IE Edge, and Opera.

The deliverable is compiled HTML Help (a single CHM file). HTML Help displays in a tripane window. Newer PC security measures can block viewing of CHM files across a network.

Details

Pros

Issues

Deliverable File(s)

File Location

Compiled HTML; deliverable is CHM file.

One file; tripane interface is easy to use.

Format is 10+ years old.

Locally installed HTML Help files (those installed on the end user’s client machine, not their server), work without issues. If you plan to install HTML Help on a server, there are security issues. See the following:

http://support.microsoft.com/kb/902225

CHM

By default, the HTML Help folder of your project.

EPUB stands for "electronic publication" and is standard of the International Digital Publishing Forum (IDPF). This target is designed specifically for EPUB readers.

Details

Pros

Issues

Deliverable File(s)

File Location

EPUBs are readable on a variety of devices, including Nooks. The content display adjusts for the device, as well as the device settings.

You can create interactive, portable books that can be read on multiple devices.

Doc-To-Help supports the latest specification, EPUB 3.0, as well as 2.0.1.

Dynamic content is not supported, but the content will be displayed.

EPUB

By default, the EPUB folder of your project.

You must add your EPUB to your reader (such as Calibre) in order to view it.

To set the default EPUB reader in Doc-To-Help, go to File > Tools > Options. In the  Options dialog, select the Viewers button and choose the EPUB reader executable.

Note Many devices don't support Cascading Style Sheets or only support them partially, so your EPUB display can vary depending on the device.

Note Doc-To-Help’s EPUB target was tested with the following readers:

Note Dynamic content is not supported in EPUBs, but the content will be displayed as follows:

  • Popups and Glossary Terms will be opened in the current window.
  • All content in Collapsible Sections (created with the Collapsible Section button) will be displayed (just as it would in Manual Targets).
  • Topic links that were specified to open in secondary windows will open in the current window instead.
  • Keywords with multiple entries and Groups don’t open in a popup when clicked, but instead link to the Index, where those Keywords and Groups are displayed, along with the list of topics included in each. (The Index can be renamed in the Theme Designer. See Using the Theme Editor.)

Note Expanding Text and Dropdown Text (both created with the Inline Text button) may be displayed or hidden in EPUBs. The option you prefer can be set in the Help Targets dialog using the Show expanding text and Show dropdown text check boxes. The hidden portion of inline text will always remain hidden.

The deliverable is Help for the Eclipse environment.

Details

Pros

Issues

Deliverable File(s)

File Location1

Help target for the Eclipse development environment. Eclipse was released by IBM in the early 2000s.

An Eclipse Help system is a plug-in for Eclipse. This plug-in supports a table of contents, index, search, and context-sensitive Help .

Eclipse Help is compatible with all browsers, but the Eclipse SDK must be installed on the same server as the Help system.

Eclipse Help does not support opening topic links in secondary windows.

Multiple files

See the following (search on "User Assistance Support"):

http://help.eclipse.org/indigo/index.jsp

By default, the Eclipse folder of your project.

To view Eclipse Help, you must have the Java Runtime Environment (JRE) and Eclipse installed (either the 32 or 64-bit versions). To view Eclipse Help using the View button for your target, you must have 32-bit Eclipse installed. Eclipse is available for download from:

http://eclipse.org/downloads/

1After installation, the location of the eclipse.exe file should be set in the Doc-To-Help Options dialog through File > Doc-To-Help Options.Click the Viewers tab to set the location of the eclipse.exe file.

The deliverable is Help for Java applications.

Details

Pros

Issues

Deliverable File(s)

File Location

Java Help 1.1.3 is supported, as well as JavaHelp 2.0

JavaHelp software was developed to provide a standard Help solution for pure Java applications.

JavaHelp software was released in April 1999, and is currently in release 2.0.

While there is no "standard" viewer, JavaHelp uses components from the HotJava browser for its display.

Multiple files; deliver the entire JavaHelp folder (its default name) in your project directory.

By Default, the JavaHelp folder of your project.

To view a JavaHelp HelpSet, you must have the necessary files installed on your machine.

Note To build and view JavaHelp, you must first install the necessary files from Oracle.

Do the following:

  1. Install the Java Developer Kit (JDK).
    The JDK6 for Windows x86 and Windows x64 are available at:
    http://www.oracle.com/technetwork/java/javase/downloads/index.html   

  2. Download and unzip the JavaHelp files from https://mirror.its.dal.ca/freebsd/distfiles/javahelp2_0_05.zip.

    MadCap Software is not responsible for content or applications from a third-party site.

  3. Update your Environment Variables to tell your machine where to find the Java files.
    Go to Control Panel > System > Advanced Settings. The System Properties dialog will open.
    On the Advanced tab click the Environment Variables button. These variables need to be added or changed under System variables:

    • JAVA_HOME
      Value: C:\Program Files [or Program Files (x86)]\Java\jdk1.6.0 (use the location of your JDK installation)

    • JAVAHELP_HOME
      Value: C:\Program Files [or Program Files (x86)]\Java\jh2.0 (use the location of your jh2.0 directory)

    • JHHOME
      Value: C:\Program Files [or Program Files (x86)]\Java\jh2.0 (use the location of your jh2.0 directory)

    • Path
      This one will already exist, so edit it and append ;C:\Program Files [or Program Files (x86)]\Java\jdk1.6.0\bin (use the location of your JRE\bin directory)
      (Note: semicolons separate multiple paths)

As noted above, the exact file paths will vary based on Java version numbers and where you have JavaHelp and the JDK installed on your machine.

This target is only used to create Help for .NET components. Projects are integrated with Microsoft® Visual Studio 2010 and above.

See the following for MHV resources:

Details

Pros

Issues

Deliverable File(s)

File Location

Help target for those developing Help for Visual Studio 2010 and above only.

Deliverable can be the reference documentation only, or Doc-To-Help can be used to add narrative text.

Resembles Microsoft MSDN collection and uses some of the same underlying technology

Format can only be included in Help for Visual Studio 2010 and above.

HelpContentSetup.msha and <target base name>.mshc

The MSHC is a zip file containing all of the Help content.

By default, the MSHelpViewer folder of your project.

To specify the version of the Microsoft Help Viewer to use when viewing Microsoft Help Viewer Targets, in Doc-To-Help, go to File > Tools > Options. In the  Options dialog, select the Viewers button and choose the correct version of the viewer. (Options available depend on your Visual Studio installation.)

Note In order to create and view Microsoft Help Viewer files you must install Visual Studio 2010 or greater. Other properties are set in the Help Targets dialog.

This target is only used to create Help for .NET components. These projects are integrated with Microsoft® Visual Studio 2002-2008.

Details

Pros

Issues

Deliverable File(s)

File Location

Help Target for those developing Help for Visual Studio 2002-2008 only.

Deliverable can be the reference documentation only, or Doc-To-Help can be used to add narrative text.

Resembles Microsoft MSDN collection and uses some of the same underlying technology

Format can only be included in Help for Visual Studio 2002-2008.

Programmers who distribute .NET components can integrate Help 2.0, because the .NET tools include the run-time components necessary to view Help 2.0 Help systems.

.HxS (topic files), .HxC (project file), .HxF (include file), .HxT (table of contents). .HxA (attributes), .HxK (index)Your deliverables may vary based on your application.

For more on Microsoft Help 2.0 redistributables, see:

http://msdn.microsoft.com/en-us/library/bb165722(VS.80).aspx

By default, the MSHelp folder of your project.

Note To create and view .HxS, or Help 2.0, files, you must install Visual Studio.NET and VSHIK (Visual Studio Help Integration Kit).

The Namespace and Parent Namespace are set in the Help Targets dialog.

To build Help 2.0, Doc-To-Help also needs to know the locations of the Help 2.0 executable files. By default, Doc-To-Help assumes the following:

C:\Program Files\Microsoft Help 2.0 SDK\HxComp.exe

C:\Program Files\Microsoft Help 2.0 SDK\HxReg.exe

C:\Program Files\Common Files\Microsoft Shared\Help\dexplore.exe

You may have to create folders if they do not already exist.

Print-based output doesn't have to be printed, although it can be. With Doc-To-Help, you can generate Microsoft® Word files (DOC or DOCX), and PDF (portable document format) files. Either format can be sent to a printer, or provided as an online document. If you don’t want your file altered, it is best to provide it as a PDF.

For more information on some tasks specific to the Manual output type, see Manual Target Tasks.

Details

Pros

Issues

Deliverable File(s)

File Location

Can be online (PDF), hard-copy, or both.

Hardcopy Familiar format and navigation.

Online Same familiar format, but no printing cost.

Can create links to websites, video/audio files, etc.

Searchable

Hardcopy Can become obsolete quickly.

Printing and delivery costs.

Customers may not work in an environment where they can access manual.

DOC and/or PDF

By default, the Manual folder of your project.