[an error occurred while processing this directive]

Support

Adding Online Help

Hierarchical Navigation

Downloads

 Feedback

Table Of Contents

Adding Online Help

What's New in CWCS Online Help

Overview of Online Help

How Help Is Displayed

Understanding the Help Engine

Displaying Help Topics

Linking Context-Sensitive Help Buttons

Creating the Main Help Contents and Index

Handling Error Conditions

Summarizing the Display Process

Understanding the Search Engine

Displaying the Search Dialog Box

Searching the Files and Displaying the Search Results

Summarizing the Search Process

Understanding Mapping Files

Mapping File Conventions and Requirements

Mapping File Line Types

Sample Mapping File

Implementing Help: Engineering Tasks

Installing the Help Packages

Adding a Call to the Help Engine

Calling Help From a Java Application

Calling Help From an HTML-Based Application

Updating the Mapping File

Packaging the Help Files

Implementing Help: Writing Tasks

Selecting an Authoring Tool

Setting Up Your Authoring Environment

Setting Up the Native HTML Authoring Environment

Setting Up the XML Authoring Environment

Setting Up the FrameMaker/WebWorks Authoring Environment

Creating the Help Topic Files

Maintaining Your Help System's Mapping File

Creating the Mapping File

Defining the Main Help Page Contents and Index

Adding Search Support

Maintaining the Search Index File

Delivering Your Help System

Adding Drop-In Help Systems


Adding Online Help

CWCS uses a customized Cisco help engine to display online help. The Cisco help engine produces a help system suite, composed of one or more help systems that you can install or uninstall when you need them. When you add a new application to CWCS:

•The help system for your application is added to the help system suite.

•Your application name appears in the main help contents page and index.

•The application name is linked to your help system's default page.

The following topics describe the CWCS help engine and how to add help for your application to the help system suite:

•What's New in CWCS Online Help

•Overview of Online Help

•Implementing Help: Engineering Tasks

•Implementing Help: Writing Tasks

•Adding Drop-In Help Systems

For more information about the Cisco help system, refer to the Cisco Online Help support website (http://wwwin-olh-support.cisco.com/index.html). This website provides access to templates, APIs, and many process documents, including:

•EMBU Help System (Client/Web Server) 2.0 System Functional Specification, EDCS-126498

•Online Help System for CMF 2.3 System Functional Specification, EDCS-238093

•Creating Cisco Online Help Using FrameMaker and WebWorks, ENG-104742

•Creating Online Help Using Native HTML, EDCS-298882

•Creating Online Help Using XML, EDCS-357012

•Guidelines for Writing Single-Sourced Manuals, ENG-70452

•Editing Guidelines for Writing Documentation, EDCS-280677

Note The Cisco help system no longer supports authoring in RoboHelp. Authors creating online help for CiscoWorks applications should convert existing RoboHelp projects to native HTML, using the methods detailed in EDCS-298882.

What's New in CWCS Online Help

This release of CWCS uses Cisco help system version 2.0, which incorporates the following major changes from version 1.0:

•The help system supports the Cisco UE/UII look and feel. This includes access to PDF files and Glossary topics as topics within the help system, rather than links from banner buttons.

•The table of contents and index display using HTML and Javascript only.

•The banner navigation elements display using HTML tables instead of gif files.

Overview of Online Help

Cisco help consists of:

•Help window layouts defined by several special HTML files.

•A help engine that:

–Links context-sensitive help buttons to the appropriate topic.

–Creates a master table of contents and index for the installed help systems.

–Provides information required by the search engine.

–Handles error conditions.

•A search engine and search index files that support full-text searches across one or all installed help systems.

•Special mapping files that match help tags in your application to help topics.

The following topics describe these components:

•How Help Is Displayed

•Understanding the Help Engine

•Understanding the Search Engine

•Understanding Mapping Files

How Help Is Displayed

The Cisco help engine displays help files in a separate browser window.

To organize the content of a suite of help systems, the help engine creates a top-level help page that contains links to the help system for each installed application. Figure 17-1 shows an example of the Main Help Window for a help system suite.

Figure 17-1 Help Suite: Main Page Layout

For this top-level page in a help suite, the help window contents and functions are as follows:

•The Banner frame contains two navigation links on the far right:

–The Main link reloads the master table of contents page with its associated default topic, closing any open folders in the contents tree.

–The About link displays the "Using Help" topic.

•The Contents frame provides access to the contents, index and search functions for the help system suite. The Contents frame contains three tabs:

–The Contents tab contains entries for all installed help systems, in expanding and collapsing folders (represented by book icons). The contents are organized by product suite or other groups. This organization helps users quickly find the help for an application in the suite.

–The Index tab contains a link to the first index page of each installed help system. These entries are organized alphabetically, by application name. Each application index entry takes you to an alphabetized list of links to all the topics in the selected help system.

–The Search tab loads a search page in the Topic frame. You can search the individual help system or all the help systems in a help system suite.

•The Topic frame contains the actual help information. The default topic for the master help system is "Using Help."

These frames are created by a file called index.html. For a help system suite, there is one index.html file per help system as well as a master, or main, index.html file.

The look of individual pages with only one help system is nearly identical to Figure 17-1. The only differences are:

•The Contents tab contains entries only for the single help system topics.

•The Index tab contains alphabetized links to all the topics in the help system, rather than to the first page of the index for each help system.

Understanding the Help Engine

The Cisco help engine is a customized Java application that displays help topics in a separate browser window. This help engine:

•Displays help topics associated with the navigation tree entries in the CWCS desktop

•Links context-sensitive help buttons to the appropriate topic

•Creates a master table of contents and index for all installed help systems

•Handles error conditions

The following topics describe these help engine functions:

•Displaying Help Topics

•Linking Context-Sensitive Help Buttons

•Creating the Main Help Contents and Index

•Handling Error Conditions

•Summarizing the Display Process

Displaying Help Topics

The Cisco help engine uses the following behaviors to display help topics associated with the navigation tree options in the CWCS desktop:

•If the user clicks the desktop Help button and no folder or task is selected, the help engine displays the Main Help page (see the "How Help Is Displayed" section). This page displays the "Using Help" page in the Topics frame and a list of all installed help systems in the Contents frame.

•If the user clicks the desktop Help button and selects a folder in the navigation tree, the help engine displays the first page for that help system (usually the overview) in the Topics frame. The Contents frame contains the contents for that application's help system.

The first page of a help system also appears when you select Help from the toolbar (where the application has toolbar), then chooses the option for this application.

•If the user selects a task in the navigation tree, the help engine displays the help page for that task in the Topics frame. The Contents frame contains the contents for that application's help system.

Linking Context-Sensitive Help Buttons

To support context-sensitive help, each dialog box requires a link to its associated help topic. Therefore, for each dialog box, the engineer must add an engineering tag to the code. Mapping files correlate these engineering tags to corresponding help file paths. Mapping files are described in the "Understanding Mapping Files" section.

Note Each application, regardless of whether the writer creates the help topics using a Native HTML project or a FrameMaker file, must have a separate mapping file. These mapping files must be located in a special directory at run time (see the "Packaging the Help Files" section).

When the user opens the help system from a context-sensitive link, such as a Help button on a dialog box, the help engine creates a URL to display the topic specified in the mapping file.

Creating the Main Help Contents and Index

The Cisco help engine creates the master table of contents and index files for the installed help systems.

The help engine reads special DROPIN and DROPINPLACE lines in each mapping file. Using this information, it creates a top-level help page that contains links to the help files for all installed applications, including in-house and third-party drop-ins. If no DROPIN or DROPINPLACE lines are present in any mapping files, the help system does not create the top-level help page.

Related Topics

•Understanding Mapping Files

•Adding Drop-In Help Systems

Handling Error Conditions

The Cisco help engine handles context-sensitive links when the target file is not available. The Cisco help engine reads all the mapping files, looking for a match to the engineering tag sent by the application.

•If no match for the engineering tag is found, the Cisco help engine loads a standard error page in the Topic frame.

•If a match is found for the engineering tag, but the index.html file for the help system is missing, the engine displays the help topic anyway, using a default index.html file and the help topic filepath.

Summarizing the Display Process

Figure 17-2 illustrates the process the Cisco help engine API uses to display the help topics.

Figure 17-2 Help API Process Overview

Understanding the Search Engine

The search engine allows the user to search all files in the help system or the help files for a single help system. The search engine consists of several parts, discussed in the following topics:

•Displaying the Search Dialog Box

•Searching the Files and Displaying the Search Results

•Summarizing the Search Process

Displaying the Search Dialog Box

When the reader clicks the Search button in the banner frame, HelpSearchServlet.java displays the search dialog box in the topic frame. Figure 17-3 shows a sample search dialog box.

Figure 17-3 Sample Search Dialog Box

Mapping files define the scope of the search for each help system. A special SEARCH line in each mapping file defines:

•The search scope list displayed in the search page. For example, in Figure 17-3, the search scope is "CiscoWorks Common Services".

•The search index files to be searched when the user selects that entry. The search engine reads the search index files instead of opening, reading, and closing every topic file in a help system. Each line in the search index file contains the text in one topic file.

Note Each application must have a separate search index file. These search index files must be located in a special directory at run time (see the "Packaging the Help Files" section).

Related Topics

•Understanding Mapping Files

•Maintaining the Search Index File

Searching the Files and Displaying the Search Results

After the user has entered the search parameters, HelpSearchServlet.java looks for matches in the search index files and displays the results. Figure 17-4 shows a sample search results page. When the user clicks a link in the search results page, the search engine displays the associated help topic.

Figure 17-4 Sample Search Results Page

Summarizing the Search Process

Figure 17-5 illustrates the process the search engine uses to find and display its results.

Figure 17-5 Search Process Overview

Understanding Mapping Files

Mapping files are an integral part of the help display process. The Cisco help engine API uses mapping files to:

•Display help topics associated with navigation tree entries in the desktop

•Link context-sensitive help buttons to the appropriate topic

•Create a master table of contents and index for the help system suite

The search engine also depends on mapping files to define:

•The entry in the search scope list that is displayed in the search dialog box

•The search index files to be searched when the user selects that entry

The following topics contain more information about mapping files:

•Mapping File Conventions and Requirements

•Mapping File Line Types

•Sample Mapping File

Mapping File Conventions and Requirements

The conventions shown in Table 17-1must be used by all mapping files for the Cisco help engine API to work properly:

Table 17-1 Mapping File Conventions

File Name

Because all mapping files are installed in a single directory at run time, each mapping file must have a unique name. Use the following naming convention:

productSubsystem.hlp

where:

•product is the product acronym

•Subsystem is the subsystem name or acronym

•.hlp is the required file extension

Example: CRMDevws.hlp

Runtime Location

The Cisco help engine looks for mapping files in the following runtime location:

NMSROOT/htdocs/help/mappingfiles

where NMSROOT is the directory in which the product was installed.

Guidelines

All mapping files must follow these conventions:

•Each tag entry must be contained within one line.

•Tags must be unique across all installed mapping files.

•The tag and filepath must be separated by at least one blank space.

•The filepath must include all directories under /help; the /help directory is assumed by the Cisco help engine.

•The # indicates a comment line.

•Level names and order# fields must be contained within double quotes.

•Level names and order# fields cannot contain embedded double quotes.

•Filepath must be preceded by a backslash (/). The top-level "/help" directory is assumed.

•DROPIN, DROPINPLACE, SEARCH, and SEARCHALL keywords must be left-justified.

•If the application is available from the desktop navigation bar, the engineer must add the help tag to the application registry file.

•At run time all mapping files must be installed in the ../help/mappingfiles directory.


Mapping File Line Types

Table 17-2 summarizes the available mapping file line types. These line types allow you to:

•Implement context-sensitive help

•Add an entry to the main help contents

•Determine the order of the entries in the main help page contents

•Define the entry in the search scope list

•Define the search index files to be searched

•Define the text for searching "all" help systems

Table 17-2 Mapping File Line Types 

Line Type
Description

Tag/helpfile

The tag/filepath pair used to implement context-sensitive help.

tag /filepath

where:

tag is a help tag name. It must be unique among all installed mapping files.

/filepath is the path name of the HTML file. The Cisco help engine assumes the top-level directory is /help.

Comment

# <any text>

DROPIN

Adds an entry to the contents in the main help page.

DROPIN, "level 1 name" [,"level x name"] [...] [, /filepath]

where:

level x name defines a contents structure (books and pages; books can contain other books or pages)

/filepath is the path name of the HTML file that corresponds to the last entry in the list. If /filepath is not present, level x name is added to the contents but no link is created.

The number of level x name entries in the DROPIN line determines the location of the link in the contents hierarchy. Use DROPIN lines to add a link in the main help page contents to your help system when the order in which the help system entry appears in the list of book entries is not important.

You can put DROPIN lines anywhere in the file, but it is best to put them before any tag/filepath pairs.

DROPINPLACE

Forces the last level x name entry to the top or end of the list in the main help page contents.

DROPINPLACE, "order#", "level 1 name" [, "level x name"] [...] [, /filepath]

where:

order# is the order in which these entries appear. For details on how the help system uses this value to order the main help page contents, see the "Defining the Main Help Page Contents and Index" section.

level x name defines a contents structure.

/filepath is the path name of the HTML file that corresponds to the last entry in the list. If /filepath is not present, level x name is added to the contents but no link is created.

Use DROPINPLACE lines to force book or page entries for a help system to appear in a specific location in that book in relation to other entries at the same level.

You can put DROPINPLACE lines anywhere in the file, but it is best to put them at the top, before any tag/filepath pairs, for easy access.

SEARCH

Defines the entry in the search scope list that is displayed in the search page and the search index files to be searched when the user selects that entry.

SEARCH, "search scope", "app.sch"[, "app.sch"...]

where:

search scope is the name you want to appear in the search drop-down box. If this field is not present, the search results page displays "Unknown" in the application name column for any hits to this help system.

app.sch is the name of the search index files you want the search utility to look at when the user selects this option. You can specify multiple search files. For example, if you want to search your help topics and the glossary, make sure there is a search index for the glossary, then add that filename to this line. For example:

SEARCH, "Management Connection","mngconnect.sch", "glossary.sch"

SEARCHALL

Special line that defines the text to search "all" help systems.

SEARCHALL "all_name"

If SEARCHALL is not specified in any installed mapping file, the search engine uses the default text "All."


Sample Mapping File

Example 17-1 shows a typical mapping file.

Example 17-1 Sample Mapping File 

###################################################

# MyApp Manager Mapping file (MyAppmgr.hlp)

# for context-sensitive help.

#

# Last modified 02/31/2004

#

# Copyright (c) 1997-2004 by Cisco Systems, Inc.   

# All rights reserved   

###################################################

########################

# Top-level TOC entry

########################

DROPIN,"Server Configuration","Administration","Process Management",/myappmgr/index.html

SEARCH,"Process Management", "myappmgr.sch"


#-------------------------

# TOP-LEVEL FOLDER

#-------------------------

# This is for the MyApp Server > Administration > Process Management

procmgr_folder /myappmgr/myappmgr_overv.html


#------------------------

# PROCESS ADMIN OPERATIONS

#------------------------

#  this page would start a single process or system

myapp_mgr_start_processes /myappmgr/ad_procs_start.html


#  this page would stop a single process or system

myapp_mgr_stop_processes /myappmgr/ad_procs_stop.html


#  this page would display myapp.log with selected process

myapp_mgr_myapp_log


#  this page would display the status of processes

myapp_mgr_process_status /myappmgr/ad_procs_status.html


#  this page would display process properties

myapp_mgr_process_report /myappmgr/ad_procs_detail.html


#-------------------------- EOF -------------------------#

Implementing Help: Engineering Tasks

Implementing help for a new application typically requires effort on the part of both the development engineers and the writers. These tasks must be performed by the engineer:

1. Installing the Help Packages—The online help and search engine class files must be installed in the classpath. You can do this by installing the appropriate CWCS help engine packages.

2. Adding a Call to the Help Engine—Each code module that creates a dialog box with a Help button must include a call to the Cisco help engine servlet.

3. Updating the Mapping File—The engineer must help the writer keep the mapping file current.

4. Packaging the Help Files—For the Cisco help engine API to work, help files must be installed in predetermined locations in the runtime environment.

Installing the Help Packages

CWCS supplies the help and search engine class files as part of the pxhlp (Windows) and CSCOhlp (Solaris) packages. To install the Help system, include these packages in your install. If performed correctly, the following files should appear in your classpath: 

com\cisco\nm\help\ClientServerHelpAPI.class

com\cisco\nm\help\ConfigReadWrite.class

com\cisco\nm\help\CvHelpApiIf.class

com\cisco\nm\help\DataHandler.class

com\cisco\nm\help\HelpCache.class

com\cisco\nm\help\HelpCacheServlet.class

com\cisco\nm\help\HelpConstants.class

com\cisco\nm\help\HelpEngine.class

com\cisco\nm\help\HelpSearch.class

com\cisco\nm\help\HelpSearchServlet.class

com\cisco\nm\help\HelpTree.class

com\cisco\nm\help\HelpTreeNode.clas

com\cisco\nm\help\ListenerServlet.class

com\cisco\nm\help\PopHelp.class

com\cisco\nm\help\PostSearch.class

com\cisco\nm\help\PreSearch.class

com\cisco\nm\help\SearchHelpServlet.class

com\cisco\nm\help\ServerHelpEngine.class

com\cisco\nm\help\ServerSearchEngine.class

com\cisco\nm\help\SystemUtils.class

For a complete list of required files, see the pxhlp.bom file in the ClearCase VOB for the version of CWCS you are using.

Adding a Call to the Help Engine

The following topics describe how to call the Cisco help engine:

•Calling Help From a Java Application

•Calling Help From an HTML-Based Application

Calling Help From a Java Application

Use the Java class ClientServerHelpAPI summarized in Table 17-3 to start the help system from your Java application. Each code module that creates a dialog box with a Help button must include a call to this servlet.

Table 17-3 ClientServerHelpAPI Summary

Name
ClientServerHelpAPI
Description

Wraps the Cisco help engine call into a convenient API. This version starts the help system only from a web server-based Java applet. Starts the help system only if the applet passed is not null and the parameter is valid. This API does not work when run as a "file://" call.

Parameters
Syntax
Action

TAG=some_help_tag

Opens a browser window and displays the correct help context.

TAG=DEFAULT

Displays the help system's top-level table of contents.

URL=some_url

Opens a browser window and displays the URL "some_url", where some_url is a complete valid URL. (See java.net.URL for information on URL formatting.) Typically used to display third-party help systems.

All other parameters

Throws an exception and does not display the help system.

Example

For each code module that creates a dialog box with a Help button, add the import statement and the call to the servlet: 

import com.cisco.nm.help.ClientServerHelpAPI;

...

public class MyApplet extends Applet

{

...


public handleHelp(...)

{

    		    ...

    		    try{

                  			ClientServerHelpAPI.launchHelp(getApplet(),

                  "<parameter>");

    		    }catch(MalformedURLException e){}

    		     catch(Exception e){}

    		    ...

    		  }

  ...

}

Calling Help From an HTML-Based Application

Use the JavaScript function pophelp to start the help system from your HTML-based application. This function exists in the parent window (the CWCS desktop). Each HTML dialog box that includes a help button must include a call to this function.

Table 17-4 Pophelp Function Summary

Name
pophelp
Description

Wraps the Cisco help engine call into a convenient API. This version starts the help system from a web server-based HTML application. This API does not work when run a a "file://" call.

Parameters
Syntax
Action

TAG=some_help_tag

Opens a browser window and displays the correct help context. If no help tag is passed, displays the top-level table of contents for the help system.

TAG=DEFAULT

Displays the help system's top-level table of contents.

All other parameters

Displays the help system's top-level table of contents.

Example

(all on one line): 

<input type="button" name="_Help" value="Help" 
onclick="parent.pophelp('TAG=some-help-tag');">
Function Listing

If you cannot access the CWCS desktop version, add this code to your HTML file. Note that the path /CSCOnm? may change depending on how your web server is configured. 

<SCRIPT LANGUAGE="JavaScript">

<!-- 

function pophelp(tag) {

     if(!tag) {

         tag = "DEFAULT";

     }

     window.open("/CSCOnm/servlet/com.cisco.nm.help.ServerHelpEngine?tag=" + tag,

         "HelpSystem",

         
"toolbar=yes,location=no,directories=no,status=yes,menubar=yes,resizable=yes,scrollbars=y
es,width=700,height=575");

}

//-->

</SCRIPT>


Updating the Mapping File

To implement context-sensitive help, the engineer must work closely with the help writer. Although the writer typically creates and maintains the mapping file, the engineer is responsible for:

•Inserting the engineering tags into the source code.

•Adding the engineering tags to the application registry files.

•Notifying the writer of any new dialog boxes. Each new dialog box requires adding an engineering tag/filepath pair to the mapping file for that application.

•Notify the writer of any changes to existing tags (for example, deleted dialog boxes).

Note All engineering tags must follow the conventions described in the "Mapping File Conventions and Requirements" section.

Packaging the Help Files

The required runtime structure, shown in Figure 17-6, includes all help systems and any shared help resources.

Figure 17-6 Required Help Runtime Structure

Table 17-5 describes each directory and lists the required files that should be installed in each directory.

For a complete list of required files, see the pxhlp.bom file in the ClearCase VOB for the version of CWCS you are using.

Table 17-5 Help System Runtime Structure  

Directory
Description, Path, and Required Files

Help root directory

The top level of the help structure.

Path: NMSROOT/htdocs/help, where NMSROOT is the directory in which the product was installed.

Required files: 

config.js

errorfile.html

helpconfig.txt

ind.js

index.html

nav.html

pophelp.html

toc.js

toolbar.html

utils.js

shared

Contains all resources that are shared globally across all help systems.

Path: NMSROOT/htdocs/help/shared

Required files: 

ban.html

banner.html

before_login.html

cco_login.html

content.css

content_ns.css

cw2000.html

footer.html

global.css

global_ns.css

global_ns_sol.css

help_tips.html

ind.html

index.html

indexframe.html

leftframe.html

login.html

menu.html

menu.js

more_info.html

nav.html

pdf_gloss.js

ref_help.html

searchframe.html

sel_dev.html

sel_opt.html

sel_url.html

shared.hhc

shared.hhk

sp.html

style_1.css

sync.js

toolbar.html

tree.js

utils.js

WebHelp.jar

WHIEInd.htm

WHIEToc.htm

WHnonIE4.css

graphics

Contains graphics that are shared globally across all the products.

Path: NMSROOT/htdocs/help/graphics

Required files: 

Admin.gif

caution.gif

CiscoLogo.gif

gloss.gif

gloss_over.gif

help.gif

help_over.gif

main.gif

main_over.gif

Operators.gif

pdf.gif

pdf_over.gif

search.gif

search_over.gif

bg_vert_dash.gif

blank.gif

blank_minus.gif

blank_plus.gif

book_c_sel.gif

book_closed.gif

book_o_sel.gif

book_open.gif

footer_left.gif

help_doc.gif

help_doc_mo.gif

help_doc_sel.gif

hlp_bg.gif

hlp_bg_nml.gif

hlp_bg_sel.gif

hlp_bg_lt.gif

hlp_bg_lt_nml.gif

hlp_bg_lt_sel.gif

hlp_bg_rt.gif

hlp_bg_rt_nml.gif

hlp_bg_rt_sel.gif

img_vert_green.gif

join.gif

joinbottom.gif

jointop.gif

lgo_cisco.gif

line.gif

minus.gif

minusbottom.gif

minusonly.gif

minustop.gif

plus.gif

plusbottom.gif

plusonly.gif

plustop.gif

spacer.gif

vert_top.gif

mappingfiles

Contains the mapping files for all installed help packages.

Path: NMSROOT/htdocs/help/mappingfiles

Additional required files:

shared.hlp

search

Contains the search index files for all installed help packages.

Path: NMSROOT/htdocs/help/search

Additional required files: 

CMFshared.sch

PreSearch.html

search.html

search.sch

SearchTemplate.html

searchtips.html

app1, app2, ...

Contains the help files for each application. Any images that are only referenced by this application are stored in the images subdirectory for that application.

Path: NMSROOT/htdocs/help/appname

Notes:

•Be sure to install and deinstall the help for the application or device package with the application or device.

•If you are installing an upgrade, there may not be a one-to-one correspondence to the old help files. Be sure your install program deletes the target directory first to ensure that no old files are left on the system.


Implementing Help: Writing Tasks

Implementing and maintaining online help typically requires that the writer perform these tasks:

Step 1 Selecting an Authoring Tool—Cisco help was designed to allow writers to use any native HTML editor (such as HTML Help Workshop), FrameMaker/Webworks, or an XML editor (like XMetal) as their authoring application.

Step 2 Setting Up Your Authoring Environment—Using a directory structure that closely resembles the runtime directory will make testing and delivering the help system easier.

Step 3 Creating the Help Topic Files—The Cisco writer's guides contain procedures for creating help topics in both authoring environments.

Step 4 Maintaining Your Help System's Mapping File—All help systems must have a mapping file. If one does not exist, the help writer must create one. If new dialog boxes are created, the mapping file must be updated.

Step 5 Maintaining the Search Index File—Any time the contents of your help system change, you must update the search index file to reflect these changes.

Step 6 Delivering Your Help System—Depending on the authoring environment, some cleanup tasks may be required.

Selecting an Authoring Tool

Cisco help was designed to allow for more than one authoring method. You can use any of the following methods to create online help:

•Native HTML Authoring: Writers use a native HTML authoring tool, such as HTML Help Workshop, to create topics, contents, and index, save to HTML, then convert to Cisco Online Help format. Writers using a native HTML authoring tool should download the following document from the Cisco Online Help support website: Creating Online Help Using Native HTML, EDCS-298882.

•XML Authoring: Writers use an XML authoring tool, such as XMetal, to create topics, contents, and index, save to XML, then convert to Cisco Online Help format. Writers using an XML authoring tool should download the following document from the Cisco Online Help support website: Creating Online Help Using XML, EDCS-357012.

•FrameMaker/WebWorks Authoring: This method permits "single-source" authoring. Writers create text in FrameMaker using the Cisco corporate online help FrameMaker templates.These documents can be printed as manuals for the product and posted to Cisco.com and the documentation CD. Then the writer creates HTML help using Quadralay's WebWorks Publisher and a custom WebWorks template, and includes the output in the product as online help. Writers using the FrameMaker/WebWorks authoring method should download the following documents from the Cisco Online Help support website:

–Creating Cisco Online Help Using FrameMaker and WebWorks, ENG-104742

–Guidelines for Writing Single-Sourced Manuals, ENG-70452

Note Authoring in RoboHelp is no longer supported. Authors should convert existing RoboHelp projects to native HTML and then use the native HTML authoring process, as explained in EDCS-298882.

Setting Up Your Authoring Environment

The structure of your local writing environment is determined by the authoring tool you have selected. These topics describe the recommended environment for each authoring tool:

•Setting Up the Native HTML Authoring Environment

•Setting Up the XML Authoring Environment

•Setting Up the FrameMaker/WebWorks Authoring Environment

Setting Up the Native HTML Authoring Environment

Use the instructions in the following document to set up your writing environment: Creating Online Help Using Native HTML, EDCS-298882.

When your environment is set up, (typically, on your local machine), it should look like Figure 17-7.

Figure 17-7 Local Native HTML Writing Environment

Each of the subdirectories under the main help directory contains specific files:

•shared—Contains resources shared globally across help systems, such as the login and Using Help topics and style sheets.

•graphics—Contains all graphics shared globally across help systems, such as the gifs used in the banner frame.

•search —These subdirectories are not required in a typical local writing environment unless you have also downloaded the help or search engine files and are using them to test your help files. They do, however, allow you to keep the mapping and search index files separate from your topic files and reflect the runtime environment:

–mappingfiles—Contains the mapping file for this help package.

–search—Contains the search index file for this help package.

•appname—where appname is the name you are using for this help system. Contains the help files for this application. Any images that are only referenced by this application are stored in the images subdirectory.

If you are working on help for more than one application and therefore have more than one native HTML project, you can add application subdirectories for each help system and share the other subdirectories (search, shared, graphics, and so on). In this case, your search and mappingfiles subdirectories will contain one .sch and one .hlp file for each help system.

Setting Up the XML Authoring Environment

Use the instructions in the following document to set up your writing environment: Creating Online Help Using XML, EDCS-357012.

When your environment is set up, (typically, on your local machine), it should look like Figure 17-7.

Figure 17-8 Local XML Writing Environment

Each of the subdirectories under the main help directory contains specific files:

•shared—Contains resources shared globally across help systems, such as the login and Using Help topics and style sheets.

•graphics—Contains all graphics shared globally across help systems, such as the gifs used in the banner frame.

•search and mapping files —These subdirectories are not required in a typical local writing environment unless you have also downloaded the help or search engine files and are using them to test your help files. They do, however, allow you to keep the mapping and search index files separate from your topic files and reflect the runtime environment:

–mappingfiles—Contains the mapping file for this help package.

–search—Contains the search index file for this help package.

•appname—where appname is the name you are using for this help system. Contains the help files for this application. Any images that are only referenced by this application are stored in the images subdirectory.

If you are working on help for more than one application and therefore have more than one XML project, you can add application subdirectories for each help system and share the other subdirectories (search, shared, graphics, and so on). In this case, your search and mappingfiles subdirectories will contain one .sch and one .hlp file for each help system.

Setting Up the FrameMaker/WebWorks Authoring Environment

Use the instructions in the following document to set up your writing environment: Creating Cisco Online Help Using FrameMaker and WebWorks, ENG-104742.

When your development environment is set up (typically, on your local machine), it should look like Figure 17-9.

Figure 17-9 Local FrameMaker/WebWorks Writing Environment

Each of the subdirectories under the main help directory contains specific files:

•shared—Contains resources shared globally across help systems, such as the login and Using Help topics and style sheets.

•graphics—Contains all graphics shared globally across help systems, such as the gifs used in the banner frame.

•search and mappingfiles—These subdirectories are not required in a typical local writing environment unless you have also downloaded the help or search engine files and will be using them to test your help files. They do, however, allow you to keep the mapping and search index files separate from your topic files and reflect the runtime environment:

–mappingfiles—Contains the mapping file for this help package.

–search—Contains the search index file for this help package.

•Output—Contains the help files for this application. Any images that are only referenced by this application are stored in the images subdirectory.

Store your FrameMaker source files, WebWorks template file (wdt), and illustrations in the top-level help directory. When you run WebWorks, it will automatically copy your help topics and supporting files to the Output subdirectory.

Caution If you are working on help for more than one application, do not try to share the subdirectories (search, shared, graphics, and so on). If you try to share subdirectories, WebWorks will overwrite the Output directory each time you run it. Instead, set up a separate directory structure for each help system.

Creating the Help Topic Files

Use these manuals to help you create your help topics:

•Native HTML authors: Creating Online Help Using Native HTML, EDCS-298882.

•XML authors: Creating Online Help Using XML, EDCS-357012.

•FrameMaker/WebWorks authors: Creating Cisco Online Help Using FrameMaker and WebWorks, ENG-104742, and Guidelines for Writing Single-Sourced Manuals, ENG-70452.

In addition, use these guidelines when working in your local authoring environment:

•Native HTML and XML authors: Before testing or delivering your files, run the Cisco Online Help Generator to convert your files into Cisco Online Help.

•FrameMaker/WebWorks authors: The Output subdirectory (see Figure 17-9) will contain all the files you need for your online help. FrameMaker/WebWorks authors do not need to run the Cisco Online Help Generator.

Note Authoring in RoboHelp is no longer supported. Authors should convert existing RoboHelp projects to native HTML and then use the native HTML authoring process, as explained in EDCS-298882.

Maintaining Your Help System's Mapping File

Mapping files require either inputs from both the engineer and the writer, or an agreement that the writer will create the engineering tags in the mapping file and the engineer will add these tags to the source code.

The following topics describe how to create and maintain your mapping file:

•Creating the Mapping File

•Defining the Main Help Page Contents and Index

•Adding Search Support

Creating the Mapping File

Note If you are using FrameMaker and WebWorks, follow the instructions for inserting markers to create a mapping file in Creating Cisco Online Help Using FrameMaker and WebWorks, ENG-104742. You can download a copy from the Cisco Online Help support website.

If you are using Native HTML or XML authoring, follow this procedure to create a mapping file for your help system:

Step 1 Create the mapping file manually using a text editor. You can download a template from the Cisco Online Help support website.

Step 2 Name your mapping file. The file name must be unique and use the .hlp suffix. Follow the naming conventions described in the "Mapping File Conventions and Requirements" section.

Step 3 Add a tag/filepath pair for each dialog box that has a Help button. Follow the conventions described in the "Mapping File Conventions and Requirements" section.

Step 4 Add a DROPIN or a DROPINPLACE line to define the entry for your help system in the main help contents. For more information about these tags, see the "Defining the Main Help Page Contents and Index" section.

Step 5 Add a SEARCH line to define the entry in the search scope list and the search index files to be searched when the user selects that entry. For more information about implementing search, see the "Adding Search Support" section.

Step 6 If you are using the NMTG ClearCase processes, run the BOM file creation utility, createbom.exe, to add the mapping file to the BOM.

If you are not using the NMTG ClearCase processes, copy the mapping file to the following runtime directory:

NMSROOT/htdocs/help/mappingfiles

where NMSROOT is the directory in which the product is installed.

Defining the Main Help Page Contents and Index

The Cisco help engine reads the DROPIN and DROPINPLACE lines in the mapping files to create the Main Help page index and contents.

•The index contains links, in alphabetic order by application, to the default page of each installed help system.

•The Main Help page contents can have multiple levels, represented by expanding and collapsing folders represented by book icons. The Cisco help engine, by default, alphabetizes the contents entries in each level.

Figure 17-10 shows the contents for a sample Main Help page.

Figure 17-10 Main Help Page Contents

Although the order of the index entries is fixed, the writer can determine the order in which the contents entries appear.

The DROPIN and DROPINPLACE lines in the mapping files determine the entries that appear in the main help contents and their relative locations. The following topics discuss these special lines:

•Adding Contents Entries in the Default Order

•Adding Contents Entries in a Specific Order

Adding Contents Entries in the Default Order

Use DROPIN lines to add a link in the Main Help page contents to your help system when the order in which the help system entry appears in the list of book entries is not important.

Note You can put DROPIN lines anywhere in the file, but it is best to put them before any tag/filepath pairs.

The DROPIN line requires this syntax:

DROPIN, "level 1 name" [,"level 2 name"] [...] [, /filepath]

The number of level name entries in the DROPIN line determines the location of the link in the contents hierarchy. The following examples illustrate different ways to use the DROPIN line:

Example 1

DROPIN,"Server Configuration","Desktop",/CWCS/index.html

Because this DROPIN line contains two entries, "Server Configuration" and "Desktop," the Cisco help engine will create a book called "Server Configuration" that contains the page, "Desktop."

Example 2

DROPIN,"Server Configuration","Administration","Basic Administration",/admin/index.html

This DROPIN line contains three entries: "Server Configuration," "Administration," and "Basic Administration." The Cisco help engine will create a book called "Server Configuration" that contains a second book called "Administration." The book "Administration" will contain the page, "Basic Administration."

Example 3

DROPIN,"Resource Manager Essentials","24-Hour Reports","Software Upgrade Report", /swim/sw_hist_24hr.html

(all on one line)

You can also create a book in the contents that contains links to topics from many different help systems. This DROPIN line creates a book in the "Resource Manager Essentials" book called "24-Hour Reports" and adds the page, "Software Upgrade Report" to this book. Other help systems that must add an entry to the "24-Hour Reports" book can add a similar line to their mapping files. For example, in its mapping file, the Syslog help system adds the report "Syslog Messages" to the "24-Hour Reports" book:

DROPIN,"Resource Manager Essentials","24-Hour Reports","Syslog Messages", /syslog/sa_uinfo.html

(all on one line)

Note Because the file names in these examples are not index.html, the report will appear in the right frame instead of replacing the entire window; the top-level contents will remain in the left frame.

Related Topics

•Understanding Mapping Files

•Adding Contents Entries in a Specific Order

Adding Contents Entries in a Specific Order

Use the DROPINPLACE keyword to force book or page entries for a help system to appear in a specific location in that book in relation to other entries at the same level.

Note You can put DROPINPLACE lines anywhere in the file, but it is best to put them at the top, before any tag/filepath pairs, for easy access.

The DROPINPLACE line requires this format: 

DROPINPLACE,"order#","level 1 name"[,"level 2 name"][...][, /filepath]

The Cisco help engine applies the order# field to all entries at the same tree level. The order number default value is 999. Order numbers lower than 999 will appear before book and page entries that use the default. Order numbers higher than 999 will appear after book and page entries using the default. Table 17-6 illustrates this logic.

Table 17-6 Order Number Logic

Order Number
Location

1

First in list

2

Second in list

3...

Third in list ...

999

Default level when no DROPINPLACE tag is used

1000

Third to last in list

1001

Second to last in list

1002...

Last in list ...


Use these guidelines when adding a DROPINPLACE line to your mapping file:

•To force entries to the top of the list, assign the order# field values 1, 2, 3...

•To force entries to the bottom of the list, assign values greater than 999.

•The Cisco help engine applies the order number to the last entry in the list of level names. In this example, the order number "1" applies to the "Using Campus Manager" entry:

DROPINPLACE, "1", "Campus Manager", "Using Campus Manager", /CMcore/UGuide/index.html

(all on one line)

•The Cisco help engine applies the DROPINPLACE order numbers to all entries in a book at the same level.

•To control the order of the top-level book entries, add another DROPINPLACE line to any mapping file. For example, the following line will ensure that the "Server Configuration" book always appears first in the list of top-level books:

DROPINPLACE, "1", "Server Configuration"

(all on one line)

•If more than one DROPINPLACE line per tree level contains the same order number, those names will be displayed in alphabetic order.

The order number you use determines the location of your link. The following examples illustrate different ways to use the DROPINPLACE line:

Example 1

User guides should appear at the top of the entries for a product suite. To add the user guide for Campus Manager, add the following line to the Campus Manager user guide mapping file:

DROPINPLACE, "1", "Campus Manager", "Using Campus Manager", /CMcore/UGuide/index.html

(all on one line)

The number 1 tells the Cisco help engine to place the "Using Campus Manager" entry at the top of the Campus Manager contents entries.

Example 2

To move the 24-Hour Reports book to the bottom of the Resource Manager Essentials list, add the following line to the RMcore mapping file:

DROPINPLACE, "1001", "Resource Manager Essentials", "24-Hour Reports"

(all on one line)

The number 1001 tells the Cisco help engine to place this entry at the bottom of the list of Resource Manager Essentials entries (books and pages). Because this is a book in the contents, a filepath is not required.

Related Topics

•Understanding Mapping Files

•Adding Contents Entries in the Default Order

Adding Search Support

To implement search for a new help system:

Step 1 If you are using the Native HTML or XML authoring tools to create online help, you will need to convert it to a Help project using the Cisco Online Help Generator tool. See the Creating Cisco Online Help Using Native HTML or Creating Cisco Online Help Using XML documents for details on the conversion.

Step 2 If you are using the WebWorks authoring tool to create online help, the search index file is created as part of the WebWorks project. See "Creating the Initial WDT" section for your help engine in the Creating Cisco Online Help Using FrameMaker and WebWorks document if you want to customize your search parameters.

The new search index file has an .sch file extension. The default name is your mapfile name; for example, avmgr.sch.

Step 3 Ensure you move the search index file to the search directory.

Step 4 If you are using NMTG Clearcase processes, ensure the BOM file is where it should be at runtime (default is install_path/help/search).

If you are not using the NMTG ClearCase processes, copy the search index file to the following runtime directory:

NMSROOT/htdocs/help/search

where NMSROOT is the directory in which the product is installed.

Step 5 Ensure the SEARCH line is in the mapping file.

For example, the search line for the Availability help system would look like this:

SEARCH,"Availability","avmgr.sch"

In this example, when the user selects Availability from the search scope list, the search engine looks at the Availability search index file.

Related Topics

•Understanding Mapping Files

•Maintaining the Search Index File

Maintaining the Search Index File

When the contents of your help system change, you must update the search index file to reflect these changes. Each authoring tool updates the search index file by re-reading all the help topics for your application and replacing the old file with a new search index file.

To update the search index file:

Step 1 If you are using native HTML or XML, regenerate your help files with your authoring tool. Then use the Cisco Online Help Generator to convert the regenerated files.

Step 2 If you are using WebWorks, you need to regenerate your output.

Step 3 Ensure you copy the search index file to the search directory to replace the old file.

Delivering Your Help System

When you deliver your files—whether that means adding them to ClearCase or copying them directly to the build machine or putting them in a location that the build engineer can access—you should understand the help runtime environment requirements.

When you copy your files, follow these guidelines. Refer to Figure 17-6 for the help runtime directory structure, and Figure 17-7, Figure 17-9 and Figure 17-8 for the local development directory structures.

•Copy the contents of your help topic directory (appname or Output), including the images subdirectory, to the help appname runtime directory.

Note FrameMaker/WebWorks authors—do not name the runtime directory "Output." The runtime directory name must be unique.

•Copy your mapping file (.hlp) from your mappingfiles directory to the corresponding help runtime directory.

•Copy your search index file (.sch) from your search directory to the corresponding runtime directory.

•Unless you are setting up the shared and graphics directories, do not copy any files from your local system to these help runtime directories.

Adding Drop-In Help Systems

"Drop-in help" refers to online help for in-house or third-party products that are not part of the CiscoWorks software release, but for which access from the main help window is required. For example, a customer who wants access to HP OpenView online help can add this functionality to the installed help system.

Merging in-house and third-party drop-in help into the main help system requires, at a minimum:

•Supplying a help system that can be viewed in a web browser (HTML-based help)

If possible, rename the first page of the drop-in help system to index.html. If the first page uses this name, the Cisco help engine replaces the main help page with the drop-in help system. If the first page is not called index.html, the drop-in help system appears in the right frame of the help window.

•Supplying a mapping file

Even if the drop-in help system does not supply context-sensitive help or uses a different method, you must supply a mapping file that contains a DROPIN line. This line defines the location of the link to the help system in the main help page contents and index (see the "Updating the Mapping File" section.

Note The user still has access to the drop-in help system's existing context-sensitive help even if a link is not added to the main help page.

•Asking the engineer to add the HELPURL tag to the application registry file for the drop-in application. This allows the user to select the application task from the desktop navigation tree and click Help to directly access the help system for that task without browsing the main help page.

The HELPURL tag in the application registry file accepts either a tag or a filepath. For drop-ins, enter the filepath for the help system in this field.

[an error occurred while processing this directive]