Terminology - Method 1

What's covered?

This topic describes Method 1 of implementing terminology. It gives far more control as the author dictates exactly which instance of a term will be affected. On the other hand that is what makes it more time consuming. It also limits the terms that can be changed to those covered by the author.

Please see Terminology Methods for a comparison of the two methods.

Method 1 will work with both webhelp and html help compiled into .chm files, albeit using different scripts and methods. I have described the methods separately. Click here to jump to the HTML .chm methods.

There are some issues surrounding the following features. They may or may not be of importance to you but please do read these sections before you start work.

The Table of Contents and the Index

Searching

Printing

Credits

Pete Lees	For his work on producing the scripts.
Rob Chandler	Whose script Pete Lees used for the compiled html version.
Rob Cavicchio	Whose work Pete Lees used in resolving issues with printing from a compiled .chm file.
Craig Clarke	Craig Clarke for testing the method with a compiled chm file.
John Dunne	For his method of updating the Table of Contents and Index.
Michael Long	For identifying that Step 3 needs to be undertaken in files other than those using variables if the output is a .CHM file.

All I have done is describe the technique and create the demos and downloads.

WebHelp

These steps describe implementing the method for webhelp.

Create a file using a text editor such as Notepad and enter the terms required with their default values.

varCustomer = "Customer"

varWarehouse = "Warehouse"

Save the file as global.js (or whatever name you prefer as long as the extension is .js and you amend the name elsewhere).
Click in the field below and press Ctrl C.

Display the True Code of the topic where you want Terminology to work.
Paste the code between the <head> and </head> tags.

If the topic is at a different folder level to the global.js file, you will need to amend it to show the relative path. Click here for details.
Save the first topic to which you add this script. You should see the global.js file appear in your list of baggage files. If it does not, check you have got the correct path as described in step five.
Enter the following where you want the term to be used, amending the name of the variable as necessary. If you use RH's WSYIWYG editor, the quotes around JavaScript will be removed. That's OK.

<script language="JavaScript">document.write(varWarehouse)</script>

In RH's WYSIWYG editor, you will see a red square where the variable is required. Click the Preview icon and the topic will display the variable in your global.js file.
To test the method works, open the global.js file and change the values in quotes, then view the topic again.
Generate and publish the webhelp.
Locate the copy of the global.js file in the published output and make some changes to the default values.
View the published help again and you will find the changes appear in the relevant topics.
The published output will be installed on client sites with the global.js file containing all the default values. The client can amend the global.js file at any time. Ensure they are aware of the need to keep a backup of the latest version at all times as an update of the help could overwrite this file or the folder it is in.

I have also tried the above method with web pages using FrontPage. It does not change the code. The variable will be displayed in the Preview tab but nothing will show in the Normal tab

You can use this method to insert images or create a table if required.

IMAGES

The variable will be something like varCompanylogo = "<img src='companylogo.jpg'/>" if the image is in the root of your project. The image does need to be within the project, use a relative path with forward slashes if it is not in the root. Also you need to add the image to baggage.

TABLES

Create a variable something like

varTable =

After the equals sign enter the HTML for the table you require and it works fine using the HTML from Dreamweaver 8. Use the HTML from RH and it will not work!

The HTML can be written over multiple lines so just cut and paste it from Dreamweaver starting on the same line as the variable name. Do not surround it with quotes.

HTML .chm Method A

There are two methods that can be used with compiled .chm help.

Method A contains the terms used within the .chm file. If any changes are required to the terms, the help will need to be compiled again. Click here for a mini robohelp project demonstrating this method.
Method B retains the terms in an external file so that they can be edited without the need to recompile. Click here to skip to the instructions for that method.

Method A Procedure

Create a file using a text editor such as Notepad and enter the terms required with their default values.

varCustomer = "Customer"

varWarehouse = "Warehouse"

Save the file as global.js (or whatever name you prefer as long as the extension is .js and you amend the name elsewhere).
Click in the field below and press Ctrl C.

Note that the name of the chm file (MyHelpFile.chm in this example) must be amended to whatever name you will give the compiled help. The chm filename has to be included to prevent problems when printing topics from the compiled help.

You also need to include this script in the first topic that appears under a book in the table of contents, even though that topic does not have a variable in it. You might consider it easier to install this script reference in every topic in the help using a multi file find and replace tool. That will avoid problems if you rearrange the TOC without thinking about this. Click here for help with the search and replace.

You need to look at the code in your topics but potentially you could search for this string

</head>

and replace it with this string in all topics in the help.

<script language="JavaScript" src="ms-its:MyHelpFile.chm::/global.js"></script>

</head>

<script language="JavaScript" src="ms-its:MyHelpFile.chm::/global.js"></script>
Display the True Code of the topic where you want Terminology to work.
Paste the code between the <head> and </head> tags.
The same script is used regardless of the level of the topic. You do not need to amend the path.

Enter the following where you want the term to be used, amending the name of the variable as necessary. If you use RH's WSYIWYG editor, the quotes around JavaScript will be removed. That's OK.

<script language="JavaScript">document.write(varWarehouse)</script>

In RH's WYSIWYG editor, you will see a red square where the variable will appear in the compiled help. The Preview function will not show the variable, neither will it display a red square. Instead it will report an error for every term that you have inserted using this method. Your other text will still display. You can only see the variables in the compiled help.
Add global.js file to your baggage files. Assuming the file is in the root folder for your project, right click on Baggage Files and select New Baggage File.
Generate and test the help. You will need to repeat this step for each different global.js file that is created.

You can also use this method to insert images.

HTML .chm Method B

As explained under Method A, if you want the user to be able to amend the terms without the need for recompiling you need to follow the steps here. Click here for a mini robohelp project demonstrating this method.

Method B Procedure

Create a file using a text editor such as Notepad and enter the terms required with their default values.

varCustomer = "Customer"

varWarehouse = "Warehouse"
Save the file as global.js (or whatever you prefer as long as the extension is .js and you amend the name in the terminology2.js script referred to later). The file can be saved wherever you want but a copy of it must be in the same folder as the .chm file.

An additional script is required for this method. This is contained in the file terminology2.js and contains lines to find the location of the .chm file and then construct a link on the fly to the global.js file which must be in the same folder as the .chm file. The file you need is included in the download.

To reference the script contained in the terminology2.js file, click in the field below and press Ctrl C. Go to the True Code view of the topic where the method will be used and paste the clipboard into the <head> section.

<script language=JavaScript src="ms-its:MyHelpFile.chm::/terminology2.js"></script>

Note that the name of the chm file (MyHelpFile.chm in this example) must be amended to whatever name you will give the compiled help. The chm filename has to be included to prevent problems when printing topics from the compiled help.

You also need to include this script in the first topic that appears under a book in the table of contents, even though that topic does not have a variable in it. You might consider it easier to install this script reference in every topic in the help using a multi file find and replace tool. That will avoid problems if you rearrange the TOC without thinking about this. Click here for help with the search and replace.

You need to look at the code in your topics but potentially you could search for this string

</head>

and replace it with this string in all topics in the help.

<script language="JavaScript" src="ms-its:MyHelpFile.chm::/global.js"></script>

</head>
The same script is used regardless of the level of the topic. You do not need to amend the path.

When you save the topic, terminology2.js will appear in your baggage files.

A bug in X5 may prevent the javascript file being added to the Baggage. Click here for details of the workaround.

Please note that this file is different from earlier versions and is not the same as the terminology.js file used in other methods in this topic.

Enter the following where you want the term to be used. If you use RH's True Code editor, the quotes around JavaScript will be removed. That's OK. Amend varWarehouse to whichever variable you want here.

<script language="JavaScript">document.write(varWarehouse)</script>

In RH's WYSIWYG editor, you will see a red square where the variable will appear in the compiled help. The Preview function will not show the variable, neither will it display a red square. Instead it will report an error for every term that you have inserted using this method. Your other text will still display. You can only see the variables in the compiled help.
Compile the help.
Copy the global.js file to the same folder as the compiled help and then open the help. You can now see the topics with default values for the variables.
Close the help and make some changes to the global.js default values. View the help again and you will find the changes appear in the relevant topics.
The .chm file will be installed on client sites with the global.js file containing all the default values. The client can amend the global.js file at any time. Ensure they are aware of the need to keep a backup of the latest version at all times as an update of the help could overwrite this file or the folder it is in.

You can also use this method to insert images.

The variable will be something like varCompanylogo = "<img src='c:/images/company_logo.jpg/'>"

The path must be absolute and use forward slashes.

Table of Contents and Index

Any terms in the TOC and Index will retain the values you have used when creating the project. I quote a posting from John Dunne re changing the terms here:

"I got a result by editing whtdata0.xml and whidata0.xml for the TOC and the Index respectively. You can edit using Notepad. Test first for snags. Large Indexes and TOCs may have several additional files (whidata1 whidata2 etc)."

The only observations I would add are:

This method would allow the client to edit the TOC and Index but only for webhelp.
As with the creation of the terminology file, you are reliant on the client's ability to make these changes.
If the help is updated, the client would have to redo the changes in the new wh* files.

Searching

The topic contains something like "varCustomer".

The user sees the term defined in the terminology file, this may be Customer, Client, Punter etc.

Whatever the term is, it does not exist in the topic so it will not be found by a search.

Printing

.chm Topics

If your output is a compiled .chm file users can choose to print either the topic or the heading and its subtopics. There is no such option with webhelp.

If you have previously visited this page and used the scripts available prior to 12 November 2004, attempting to print the heading and it subtopics would have caused an error. These issues have now been resolved with very many thanks to Pete Lees and Rob Cavicchio.

Printed Documentation

There remains an issue though with printed output from the Printed Documentation option under Single Source Layouts. Quite simply nothing will be printed wherever a variable would appear in the online help. The solution here is to create a copy of your project using Windows Explorer and follow the steps below to produce a document using the default terms. Whilst in theory the procedure could be replicated any number of times to produce a different document for each customer, in practice I think you might find that rather time consuming. You have to sell these procedures on the basis that your client can have their own terminology in the online help but not in any printed manual.

The steps are:

Create a copy of the project using Windows Explorer. Use the copy for the following steps.
Open the global.js file in a text editor so that you have a list of all the variables in your project.
Open a multi file find and replace tool. One is shipped with RH and from what I understand it is more satisfactory in X5. I use FAR as it covers other requirements that I have.
Search for the script that finds the variable in the online help, as per this example
<script language="JavaScript">document.write(varWarehouse)</script>
and replace it with the default term - Warehouse.
Repeat this for each variable.
When you have replaced each script with the default term, you can produced you document in the normal way.

Date	Changes to this page
14 Mar 2006	Ability to use this method to insert images or create a table in webhelp added.
08 Mar 2005	Instruction 3 amended for both methods of using terminology with .CHM output.
29 Jan 2005	Introduction amended to fit with introduction of Method 2. The instructions for using the method have not been changed, other than renaming the two methods for chm help to Method A and Method B.
20 Jan 2005	Instructions re amending relative path revised to recommend using a forward slash.
28 Dec 2004	The printing issue with Method 2 for .chm files has been resolved. Very many thanks to Pete Lees and Rob Cavicchio for their work on that. All I do here is describe how it works. The fact that it works is thanks to those two gentlemen.
24 Nov 2004	Topic rewritten to make it easier to follow. There does remain a printing issue with one of the two methods for compiled .chm files. That has been documented.
12 Nov 2004	The script for use with compiled .chm output has been amended to resolve a printing issue. A new section has been added to cover producing printed documentation.
25 Oct 2004	New step 6 inserted into webhelp method. This should help ensure you have correctly added the script and deal with a possible conflict between the demo project if used with RH X5.
27 Aug 2004	Code to be added between <head> tags placed in a Form Element to make it easy to add it to the clipboard. Tip added to identify how to amend the path to the javascript file. Thanks to Rick Stone for suggesting these changes.
23 Aug 2004	Various changes to script for .chm method to make method clearer. Reference added to the X5 bug that may affect the terminology.js file being added to the baggage.
07 Aug 2004	Download added containing mini project showing how script is added. Correction made to a couple of references to the WYSIWYG editor which should have referred to the True Code editor.
10 May 2004	Information about editing the TOC and Index added. Information about Searching added.