Newsletter

Issue 19, 5 August 1999

ISSN 1442-8652
Editor: Jean Hollis Weber
jean@jeanweber.com
http://www.jeanweber.com

In this issue...

Feature article: Response to "Marking and Tracking Changes in Adobe Framemaker"
Resource of the week: MANTEX Newsletter
Tip of the week: "Correct spelling" or "house style"?
Follow up:
   Checklist for freelance editors revisited
   Gender-neutral writing
Subscription information

---

Feature article: Response to "Marking and Tracking Changes in Adobe Framemaker"

In issue 13 of this newsletter (24 June 1999), I published a summary of ways to mark and track changes in Adobe FrameMaker. That article is now located at http://www.jeanweber.com/howto/editfm.htm

In early July I brought this article to the attention of the FrameUsers' discussion list, and received this response from one of the "gurus" on the list. My response to Dan follows his note.

Date: Fri, 9 Jul 1999
From: Dan Emory danemory@primenet.com
Subject: Re: Marking and Tracking Changes in Frame

Jean:

Your paper, "Marking and Tracking Changes in Adobe Framemaker", is an interesting compilation, but it is incomplete.

FIRST, there are two types of change tracking, and your paper only addresses changes made during the review process. The other type involves the tracking of changes throughout the lifetime of a document, which may be many years.

The latter requires a management system capable of recording and tracking changes down to the individual paragraph level, and saving all versions in a database so that any version of any paragraph, as well as any version of the entire document, can be retrieved.

SECOND, you discuss using other word processors for preliminary writing work prior to review/edit, and then converting to FrameMaker afterwards, or converting Frame documents to RTF for review in Word, and then converting back to Frame for post-review incorporation of changes. Given the many problems in round-trip (or even one-way) conversions between FrameMaker and other word processors, as voluminously recorded on the two Framers lists, I think most enterprises would reject both of these alternatives. In particular, the problems with preservation of formats, graphics, tables, colors, variables, equations, markers, cross-references, autonumbering, and conditional text, as well as mis- translation of high-ASCII characters during such conversions makes that approach untenable.

There is only one exception I know of, and that's a product called S-Tagger from TRADOS (price is about $2500 per license, but one license would usually suffice). S-Tagger takes MIF as input, and produces RTF as output for editing in MS-Word. The RTF preserves all of the MIF formatting constructs, and they are retained when it is imported into Word, but those MIF constructs cannot be altered or deleted in Word. After editing in Word is completed, the document is saved as RTF and run back through S-Tagger to restore it to MIF. If any discrepancies are found between the original MIF and the RTF version of the MIF during the conversion back to MIF, the document is rejected. Although S-Tagger is intended for language translations, it could, in principle, be used also for conducting reviews using MS-Word.

THIRD, you overlook several useful capabilities available in FrameMaker for marking and tracking changes to facilitate the review process. For example:

1. Prior to commencement of any review process, illegal format overrides and ad-hoc formatting can be identified and fixed, and the template can be re-enforced by importing its formats back into the document with Remove Format overrides turned on. This is a vital quality assurance step that should precede the review process. I have a paper on this subject entitled "FrameMaker Template Design and Enforcement", which is available as a PDF document.
    
2. Create three FrameMaker character formats, "Was", "ShouldBe", and "Add" that are to be used exclusively by reviewers.
    
   1. The "Was" character format has Change Bar and Strikeout turned on.
       
   2. The "ShouldBe" character format has Change Bar and a color (e.g., Red) turned on.
       
   3. The "Add" character format has Change Bar and another color (e.g., Green) turned on.
       
      To change existing text, the "Was" format is applied to it, and the changed text has the "ShouldBe" format applied to it.
       
      Text that is added which does not change existing text has the "Add" format applied to it.
       
      Change bars appear in each line of the document where any of these three character formats are applied.
       
3. Each change described in step 2 above could have attached to it a comment marker or comment conditional text that identifies the reviewer, and contains any relevant explanations for the change. Comment markers or comment conditional text (including the reviewer's name) can also be inserted at places where no change or addition was made, but a comment is required.
    
   The approach described in steps 2 and 3 is certainly superior to the use of Frame's Document Compare utility, which remains problematic even in V5.5.6.
    
4. At the completion of the review phase, step 1 is repeated to remove any illegal formatting introduced during steps 2 and 3.
    
5. In the post-review phase, the presence of a change bar signals to the person(s) responsible for evaluating and incorporating the changes that a change has been made, and the three character formats described in step 2 visually indicate what was done. Any associated comment markers or comment conditional text provides additional information that may be needed to evaluate each change. The process is as follows:
    
   1. If a change to existing text is accepted, the text having the "Was" character format is deleted, and the text having the "ShouldBe" character format is converted to the default paragraph format.
       
   2. If a change to existing text is rejected, the text having the "Was" character format is converted to the default paragraph format, and the text having the "ShouldBe" character format is deleted.
       
   3. If text having the "Add" character format is accepted, the "Add" character format is converted to the default paragraph format.
       
   4. If text having the "Add" character format is rejected, it is deleted.

At the completion of these steps, all change bars should have disappeared.

A global search on comment markers or comment conditional text should also be conducted to assure that all comments have been addressed. Then, the comment markers or comment conditional text is deleted.

FOURTH, you omit any mention of the even more powerful revision tracking and change processing capabilities of FrameMaker+SGML (FM+SGML). FM+SGML could enforce and greatly facilitate the methodology described in steps 1-5 above, and information about the changes that were actually made to each paragraph could be permanently recorded in an element attribute. Another element attribute could be used to record changes that are not the result of the review process, but which may be vital to a comprehensive review (e.g., changes made as a result of Engineering Change Orders (ECO's) and similar change directives). This attribute would allow reviewers to determine whether the document reflects the most current configuration of the system being documented.

Dan Emory, Dan Emory & Associates
FrameMaker/FrameMaker+SGML Document Design & Database Publishing
Voice/Fax: 949-722-8971 E-Mail: mailto:danemory@primenet.com
10044 Adams Ave. #208, Huntington Beach, CA 92646

My reply:

Dan,

I very much appreciate the time you've taken to respond so thoroughly to my paper for editors on marking and tracking changes in FrameMaker. Some of the incompleteness you noted was deliberate, given my audience (which I didn't define in the extract that I published), but some was my lack of knowledge and experience.

Your paper, "Marking and Tracking Changes in Adobe Framemaker", is an interesting compilation, but it is incomplete.

FIRST, there are two types of change tracking, and your paper only addresses changes made during the review process.

Yes, the other type of change tracking was outside the scope of this paper for editors.

SECOND, you discuss using other word processors for preliminary writing work prior to review/edit, and then converting to FrameMaker afterwards

Many publishing environments do not do formatting or insert tables, figures etc until after the text is finalised, at which point the Word file is imported into Frame, PageMaker, Quark, or some other program, so the method is viable in those circumstances. But when I rewrite this paper, I'll make the point more explicitly about problems if that's not the case (that is, if formatting has been done in Word).

converting Frame documents to RTF for review in Word, and then converting back to Frame for post-review incorporation of changes. Given the many problems in round-trip (or even one-way) conversions between FrameMaker and other word processors

I'll be a bit more emphatic in suggesting that conversion isn't such a good idea, especially converting back to FM.

THIRD, you overlook several useful capabilities available in FrameMaker for marking and tracking changes to facilitate the review process. For example

Most of what you've said here I didn't know, or didn't know very well. Thank you! This is very helpful.

FOURTH, you omit any mention of the even more powerful revision tracking and change processing capabilities of FrameMaker+SGML (FM+SGML).

Yes, that was outside the scope of this paper, but good reference material for another paper!

Thank you again.

---

Resource of the week: MANTEX Newsletter

The MANTEX Newsletter is produced monthly by Dr Roy Johnson of MANTEX Information Design in the UK. roy@mantex.co.uk http://www.mantex.co.uk

It is a mixture of short reviews of books and other resources, miscellaneous tips, and promotional material for Dr Johnson's books, courses, and consulting services. The short reviews have pointers to full reviews stored on the mantex Web site.

I find the newsletter useful in bringing to my attention a lot of topics (particularly related to the UK and Europe) that I would not otherwise have noticed. Here's the content of the August 1999 issue, to give you an idea of what's included:

• Web-based teaching materials
• DTP Journal - 'Design Tutor'
• Writing Guides - 'Managing Research'
• PalmPilots - cheapest prices
• Writing Guides - 'Writing at University'
• Win95 Alt+Tab tip
• Teaching European Literature and Culture
• 'Writing the Information Superhighway'
• 'Envisioning Information'

---

Tip of the week: "Correct spelling" or "house style"?

Don't assume that what a writer has written is "wrong" just because it doesn't meet the conventions used in the publications you edit. Many spelling, punctuation, and terminology discrepancies are legitimate differences in conventional usage. You can tactfully point out "this doesn't match the company style" without saying "this is wrong."

(My favorite example comes from the days when I was editing scientific research papers written by Australians for publication in USAmerican journals. Many journals were quite happy to accept papers written in "British" English, but some were not. One day a researcher came in with a letter from a copy editor who had written, "The correct spelling of metre is meter." I helped the researcher compose a response: "No, the _American_ spelling of metre is meter. Your journal is quite entitled to enforce American spelling conventions, but don't tell us that international spelling is not correct.")

---

Follow up 11: Checklist for freelance editors revisited

Date: Thu, 29 Jul 1999 16:42:37 -0400
From: A Waddingham Waddingham@compuserve.com
Subject: [tenews] Technical Editors' Eyrie Newsletter No. 18, 29 July 1999

Sorry, Jean, having reread the original instructions again, I realised I missed the point about tabs and alignments. The client's instructions will remove tabs but it's not necessary to modify your Normal template doing it. My original point still stands, that it's better to use a customised editing template than change your Normal one. Just wanted to get that straight for the record. Thanks

Client's instructions:

I wrote:

Anne Waddingham

---

Follow up 12: Gender-neutral writing (Issue 15)

Several people wrote with more sources of information on how to succeed at gender-neutral writing, but only one source mentioned begins to provide an answer to the original question: where to get data to support or refute the assertion that one should write that way in the first place.

That source is "The Handbook of Nonsexist Writing for Writers, Editors and Speakers" by Casey Miller and Kate Swift, now out of print. (My copy was published by Harper & Row, 2nd edition, 1988, ISBN 0060962380.) Although this book is (not surprising- ly) almost entirely about why you should use gender-neutral language, it does contain references to studies regarding, among other things, people's (especially children's) perceptions when they hear or read masculine or feminine nouns and pronouns.

kai contributes,

A web search using dogpile.com on "gender neutral language books" yielded some results, among them: http://www.stetson.edu/departments/history/nongenderlang.html (Editor's note June 2003: page not found.)

In addition, Lyn Dupre has a section on "Gender-Specific Words" in her book Bugs in Writing, and the issue is addressed in Nagle's Handbook for Preparing Engineering Documents.

---

© Copyright 1999-2001, 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.

---