After using FrameMaker for a while, it becomes apparent there are a couple of features needed to improve it's use as an on-line documentation system. This document discusses some of these limitations and solutions which have been developed.
Currently, it is typical for an individual or small group of people to author a document and then publish it. Publication typically involves sending out a small e-mail message with a pathname to the file. But this method has some problems. Often, readers of your document will use Maker to view the document instead of Viewer. The first person to open the document locks the file so that you, the author, can not make additional changes. This also means that a reader may accidently modify the document.
In this paper, I propose a change in policy to avoid these problems. The author and reader should have separate copies of these files. The author's copy would remain a read-write document and the readers' copy would be a a `View-Only' document. View-only documents have a number of advantages. Any number of users may read a View-only document. As the name suggests, View-only documents can not be accidently modified by readers. Hyperlinks and cross-references are also live in View-only documents.
The proposed solution adds an additional level of hierarchy to existing document tree. An example may be the best way to explain this change.
Let's say that up until today, you wrote a document in /home/SuperProject/doc/specification.doc. Using the proposed policy, a new directory is added. Within this document, I will call this directory SANDBOX, but the name is arbitrary. Inside SANDBOX is another copy of specification.doc. The new copy, in the SANDBOX directory, is the read-write copy which is edited by the authors. The other copy which is in the doc directory becomes the published View-only file. This simple change reduces the impact on previously published documents. Only the authors need to know of the new document location. The readers can continue to use the previously published document pathname.
Later in this document, I will review some tools which have been developed to assist in publishing Frame documents.
Another feature which is needed is some type of version control for Frame documents. It would be useful to be able to track changes in documents. Although Frame allows the insertion of change bars which readers find useful. But they are only useful if you clear them on a regular basis, or else the whole document becomes a change bar over time. Version control should give the authors the ability to track changes over time as well as possibly revert to an older version of a document.
The reason we don't do version control on existing Frame document has to do with the nature of Frame document and the limited abilities of the common version control software. Most version control tools (i.e. RCS, and SCCS) work on text files. They minimize the disk space requirements of storing all previous revisions of a file by tracking only the differences between successive revisions. But they are tuned for text files which are edited by humans. Frame uses a binary format which can not be compared (or at least not efficiently) by version control software.
Version control software also has the ability to do keyword expansion on text files. This expansion can mean automatic insertion of information known to the version control software inside files. These keywords typically include revision numbers and modification date. But keyword expansion is not available on binary files.
Frame supports another format called MIF [1]). Because it is a line- oriented, human-readable format, version control software can work with it reasonably well. What is needed is some tools to automate the conversion of Frame binary files into MIF and then running the necessary version control software.
The FMCONTOL tools are a series of shell scripts which can automate the Version Control and Publication tasks. Most authors will only need to access one or possibly two of these scripts.
Within the P.O.S. group, you can access the FMCONTROL tools by adding /pos/gen/exe/bin to your PATH.
fmpublish file...
file is a Frame document or book. Multiple files may be specified.
fmpublish will probably be the most commonly used script from the FMCONTROL suite. During it's execution, it will utilize many of the other FMCONTROL scripts. An author of a document will run fmpublish anytime a new version of a document is ready for readers to consume. In addition to creating a View-only copy of the file in the parent directory, fmpublish will log the event and changes using the fmcheckin command. The View-only copy is deposited in the parent of the current working directory. The read-write copy in the current working directory is unaltered. The view-only copy will also have keywords expanded. (See the man pages for sccs-get for a list of keywords which will be expanded.)
fmpublish can also operate on Frame books. A Frame book is a collection of Frame documents. fmpublish will publish all the Frame documents which are in the book as though you have typed them all into the command line.
The book file itself is not published. Only the documents referenced inside the book are published. This is required because Frame does not support View-only books.
fmpublish does not support publishing documents which do not reside inside the current working directory. These are considered `external' documents by fmpublish. If a book references an external document, that document is dropped from the list of documents to be published.
One other limitation is that fmpublish will not publish any files if one of them is locked by another Frame session.
Because the tool is only a series of shell scripts, it can be a little slow. During the running of the program, a series of information messages will displayed. Important messages will be prefixed with either the words WARNING or ERROR
First example shows how to use fmpublish if your directory still has the older setup and does not contain separate directories for the authors and readers.
% cd /home/SuperProject/doc
% mkdir SANDBOX
% cp *.doc *.book SANDBOX
% cd SANDBOX
% fmpublish specification.doc
This second example shows what is needed to publish new or changed documents to the readers directory
% cd /home/SuperProject/doc/SANDBOX
% fmpublish specification.doc project-overview.book
fmcheckin file...
file is a Frame document of book. Multiple files may be specified on the command line.
This script will convert the existing Frame binary files into MIF format and then check-in the MIF files using SCCS commands. fmcheckin is automatically called by fmpublish during it's normal operation. Like fmpublish, fmcheckin supports Frame documents and books. All files referenced by a book, which reside in the current working directory, will be checked-in. fmpublish will prompt the user for one comment which will be stored with the changes for all the files.
Unlike fmpublish, fmcheckin can check-in both a book and the files it references.
% cd /home/SuperProject/doc/SANDBOX
% fmcheckin specification.doc
fm2mif and mif2fm are two scripts which convert between Frame binary and MIF formats. The names of generated MIF files are the same as the source file with an added .mif suffix. Frame binary files generated by mif2fm have the .mif suffix removed.
This represents the only naming rule required by the FMCONTROL tools. Although it is standard practice to name Frame documents and books with .doc and .book extensions, these practices are not enforced by the FMCONTROL tools. The tools rely on the Unix file command and the proper magic file supplied by Frame Technologies.
It is expected that users will not need to use the fm2mif and mif2fm commands very often. They are called by fmpublish and fmcheckin.