Terminology - Method 2
What's covered?This topic describes Method 2 of implementing terminology. It is much easier to set up but catches all instances of the word defined which may or not be an issue. It also allows the customer to format the replacement word and optionally add bubble text with a fuller description. You pays your money... Please see Terminology Methods for a comparison of the two methods. Click here if you have not seen the demo. Seeing that first makes it easier to understand the method! |
Credits
Before anyone thinks I have got clever with javascript, my thanks to my colleague Tony Harris who is the person you really have to thank. In addition to his own work, he has used some scripts written by others, please do not remove their credits from the relevant files. My work was in describing the method and setting up the demo.
What the Author Does
- These procedures cover set up for one topic which you should try first in a test project.
- You can use multi file find and replace tools to make the changes to existing projects. For new projects, you could put the various lines into a template.
- The method can be employed in chosen topics or all topics, it's up to you.
- The set up is the same for webhelp and compiled CHM help with one exception covered below.
The basic steps are
- Insert the references to the javascript files.
- Add an onLoad event.
- Amend the stylesheet(s).
- Generate your help.
Here's the detail.
- Save the javascript files in the root of your project. Click here to download them.
- Click inside the box below and press Ctrl + C
- Paste this script into your topic between the head tags <head> and </head>
- If the topic is at a different folder level to the javascript files, you will need to amend it to show the relative path. Click here for details.
- Save the file and make
sure the four javascript files now appear in your baggage files.
If they do not it is probably because of a bug in RoboHelp X5. The simplest method of working around this is to edit the rhbag.apj file. With the project closed, open the file in a text editor such as Notepad and copy / paste an existing section. Replace the name of the baggage file with the files you want to add to the baggage. - Click inside the box
below and press Ctrl + C
- Go to the true code view of the topic and select the <body> tag. Press Ctrl + V so that it is replaced by the tag in 5 above.
- Click inside the box
below and press Ctrl + C
- Open your style sheet(s) in Notepad or a style sheet editor and go to a new line at the end of the file. Press Ctrl + V to paste in these additional styles.
Note that you need to disable these additional lines when producing Printed Documentation from RoboHelp. This simply requires that you open the style sheet in Notepad or your style sheet editor and add /* where indicated. Don't forget to remove the comment tag afterwards.
- Now just generate your help and it will not appear any different to how it did before and there will be no terms that change. That's because the customer does the rest of the work!
- The only exception is if your output is compiled CHM help. For customers who want to take advantage of this method, when they have completed their part of the work, they will supply you with an addKeywords.js file. Temporarily save your blank one outside the RH project and compile using the customer's file. Then restore your blank file for future use.
What the Customer Does
Pretty much everything else!
Of the four javascript files used, addKeyword.js is the only one that is edited. The raw file is shown below and as you can see, it includes instructions for its completion. The customer locates that file and edits it in a text editor such as Notepad. Do emphasise to the customer they must not use Word or other such programs.
After the screenshot, I have included some examples and explained them.
Worked Examples
These will be a single line in your text editor, they may be wrapped in this topic depending on the size of the window.
- keywordsHelp.addKeyword("accounts","accounting","",true,"color : blue;");
- keywordsHelp.addKeyword("company","firm","<p><font color=red>A type of organisation</font></p>",false,"font-weight : bold; color:red;");
- keywordsHelp.addKeyword("software","programs","<p>They will run on <b>Windows</b> operating systems</p>",false,"");
- keywordsHelp.addKeyword("software","","<p>They will run on <b>Windows</b> operating systems</p>",false,"color : blue;");
Example 1
This is telling the javascript to search for the string accounts. The parameter true is telling the search that it is case sensitive so it will not find Accounts. The replacement term is accounting and it will be formatted blue. No bubble text help has been defined.
Example 2
This is telling the javascript to search for the string company and replace it with the term firm. The replacement term will be formatted red, perhaps to indicate bubble text help is available and in this instance, that has also been formatted red. The search would find both company and Company and change the string to firm for both. To keep case sensitivity there, you would create two searches, both case sensitive, and have company replaced by firm and Company replaced by Firm.
Example 3
This is much the same as the previous example except that no formatting has been defined for the replacement string. The replacement will thus appear as defined for the default in addKeywords.js. The customer can change the default if they so wish.
Example 4
Here nothing has been defined for the replacement string so the searched word will not change. However, its appearance will change as defined, in this case to the default colour, and bubble text would be available. This can be used where the customer is happy with the word but wants to add some information. For example, they might wish to add notes about their products so that Petrol has bubble text indicating "This product is highly inflammable".
Other Considerations for the Customer
- Above all, the customer needs to be aware that this method will capture EVERY instance of the words they define.
- They must be aware it is their responsibility to keep a copy of the addKeyword.js file safely backed up outside the structure for the help. If you ever delete all the help when upgrading the product, the customer might get a tad upset if there is no backup copy available.
- There is an element of staff training as to what the different formats mean. You cannot cover this in your help as each customer will define things in a different way.
Donations
If you find the information and tutorials on my site save you time figuring it out for yourself and help improve what you produce, please consider making a small donation.
Topic Revisions
Date |
Changes to this page |
| 07 Mar 2005 | Amended to deal with a problem when producing Printed Documentation if using this method. The additional lines in the style sheet need to be disabled while producing printed documentation. See Instruction 8 under What the Author Does. |
| 29 Jan 2005 | New topic. |