Newsletter

Issue 38, 18 July 2000

ISSN 1442-8652

Editor: Jean Hollis Weber
jean@jeanweber.com
http://www.jeanweber.com

In this issue...

Feature article: Editing glossaries
Draft chapters of Editing Online Help now on Egroups
Follow up: Lorem Ipsum for dummies
Tools roundup
    Macro Magic -- open PDF files from help files
    Cascading style sheets -- Style Master
    Validation tool for HTML and XML code
    RenameIt -- renaming a batch of files
    FAR -- Tables of Contents for web-based help
    List Buddy -- fix corrupted lists in Microsoft Word
Contributors wanted
Advertisement: Electronic editing book
Advertising policy
Subscription information

---

Feature article: Editing glossaries

Traps for the unwary are common in technical writing. In my 25 years of editing, I've seen a lot of things that have slipped by writers and reviewers.

Once I edited the glossaries for a set of 12 books for a mainframe software product. I assume from the appalling state of these glossaries that someone put them together in a hurry (possibly using some computerized tool to extract the entries from a master glossary or dictionary) and didn't have time to edit the result.

I used one of the glossaries as a bad example for an editing class, because it included every mistake I could think of.

Here's my checklist of things to look for when editing a glossary:

• Are the entries in alphabetical order? This sounds obvious, but some of the related questions are not so obvious. For example, how do you handle the alphabetising for:
  • Entries that start with a numeral or a character such as & or %
     
  • Phrases (Does "lead time" come before or after "leading"? That is, are spaces significant?)
     
  • Hyphenated words (similar question to the spaces in phrases)
     
  • Capital and lower case letters (some computerized sorting systems distinguish between the two; is that what you want?)

  There are no hard-and-fast rules to provide answers to these questions, but you (or your company) need to decide what rules you are going to follow, and then make sure you follow them.
   

• Are there any duplicate entries? How about entries that are almost the same and should be condensed into one?
   
• If large capital letters are used to separate groups of entries, are all the necessary ones there and in the correct places? Are any present that should not be there, because there are no entries that start with that letter?
   
• Are all cross-references ("see", "see also" and "contrast with") also in the glossary? Readers will be annoyed if they try to "see" an entry that isn't there.
   
• Are all the terms in the glossary actually used in the book, or in another definition? (You might have a policy of including entries that are not in the book, but are in another book in the same set. That's your choice; but be sure that irrelevant entries haven't crept in.)
   
• Are words capitalized consistently? Check especially the entries for abbreviations or acronyms, and the fully spelled-out definitions.
   
• If cross-references are given in a different font (for example, italics or bold), are all of them correctly done?
   
• Are all abbreviations and acronyms treated the same way? (In the glossaries I was editing, the abbreviation is spelled out in one entry, and a second entry defines the spelled-out term. The spelled-out entry has the abbreviation in parentheses after the term. There are other correct ways of doing this; just be sure your glossary is consistent.)
   
• Are the definitions suitable for this book and its audience? Check especially for terms that have multiple definitions, some of which might be irrelevant in this context. (In the glossaries I was editing, some of the definitions applied to the operating system on which the product was used, but other definitions applied only to a different operating system!)
   
• What should be in the introduction to a glossary, when and why? Do you need to acknowledge the source of your definitions? Should you tell your readers what the glossary covers, and what it doesn't cover? (For example, in a book about an accounting system, you might choose to include computing terms, but not accounting terms, unless the accounting terms are used in a non-standard way in the book. You could reasonably assume that the readers of the book are familiar with accounting, but not necessarily familiar with computers.)

Back to top

---

Draft chapters of Editing Online Help now on egroups

The original information in this section is now obsolete, so I have replaced it with current information.

In October 2000 I published Editing Online Help.

A contents listing and information on formats and now to get copies are here.

Payment instructions are here.

Back to top

---

Follow up: Lorem Ipsum for dummies

Ivana assai@effect.net.au wrote:

"The Lorem Ipsum dummy text included in your newsletter dated the 7th of January, is one of the imposters to the throne. My classicist friends tell me that it actually contains a number of raunchy (if not down right naughty) typos! The correct version of this text can be located at:

http://www.geekbeat.com/lorem.htm (Editor's comment Dec. 2003: could not locate this file.)

My comment: I had no idea of the origin of the lorem ipsum text, so this web page was a real eye-opener. Is it true?

Back to top

---

Tools roundup

Most of these I haven't tried, so this is not a list of recommendations, but people on various lists have recommended them. I pass them along in case someone might find them of interest.

Macro Magic -- open PDF files from help files

The new Macro Magic II demo-tutorial is available at:

http://www.wwwinnovations.com/resources/tips/macro_magic.html

Here's what the owner, Stephen Brownstein duenorth@aol.com says about it:

"Learn how HLP and CHM files can open PDF files at specific pages... nothing to buy, no third-party tools, no DLLs, no extra files to ship, no Adobe plug-ins, no bookmarks...... and it's authoring tool-independent.

"Also learn how to communicate with (send keystrokes to) other programs and create tutorials. Plus... see a neat trick for printing popups."

Cascading style sheets -- Style Master

The trial version of Style Master has an excellent cascading style sheet (css) tutorial. Find it here:

http://www.westciv.com/

Validation tool for HTML and XML code

The World Wide Web Consortium (W3C) offers an online validation service. This is great for testing your HTML and XML code. The service is free and available at:

http://validator.w3.org/

RenameIt -- renaming a batch of files

You might find this free tool useful when you need to rename a batch of files. http://www.helpmaster.de/free/filehandling.htm#RenameIt

(Editor's note October 2000: the Helpmaster site (previously a .com) is being reorganised. Many files and features, including RenameIt, have not been ported to the new site yet.)

While you're at the Helpmaster site, browse around to see what else they have to offer.

FAR -- Tables of Contents for web-based help

A shareware product that provides table of contents functionality for web-based help files or other information. Internet Explorer 4/5 users see a Microsoft HH expandable TOC and Netscape users are directed to a static HTML TOC (exported from .HHC file).

For more info on FAR, see: http://www.helpware.net/FAR/index.html

List Buddy -- fix corrupted lists in Microsoft Word

Jeff Hall eonsol@cix.co.uk says,

"Listbuddy is free from http://listbuddy.eon-solutions.co.uk/ or through http://www.eon-solutions.com/ (100kb). It consists of an installation program which installs a Word template. The template should be installed as a global add-in using "Tools|Templates|Add". Once activated, a ListBuddy toolbar will appear which allows you to run the analyser on any document."

Back to top

---

Contributors wanted

I'm looking for people to contribute some articles, or tips, or short notes about almost anything related to editing, to this newsletter. If you have something relevant to share, please send it to me! I'm sure the readers would appreciate some contributions about different working styles, materials and clients.

Back to top

---

Advertisement: Electronic editing book

Electronic editing: Editing in the computer age
by Jean Hollis Weber
Published by WeberWoman's Wrevenge
248 pages
ISBN 0646380370

A quick start guide for editing students, experienced editors making the switch from paper to online, and anyone who needs to write or edit electronically.

Available in both downloadable electronic (PDF) and printed forms. For details on ordering a copy, see
http://www.jeanweber.com/books/e-edit.htm#order

or send e-mail to e-edit@jeanweber.com

Back to top

---

Advertising policy

If you have a product or service of interest to editors, I'll be happy to consider including a short advertisement, for a modest fee. Contact me for details.

---

© Copyright 2000, Jean Hollis Weber. All rights reserved.

You may forward this newsletter (in whole or in part) to friends and colleagues, as long as you retain this copyright and subscription information, and do not charge any fee.

Subscription information

This newsletter is no longer being published.

Privacy statement

I do not sell, rent, or give my mailing list to anyone.

---