lark@tivoli.UUCP (Lar Kaufman) (12/05/90)
The following report is edited for reasons of confidentiality and
fairness, and no warranty of accuracy or professional expertise is
implied or expressed; because of time limitations, there are likely
some inaccuracies. It is supplied solely for those curious about
factors that affected our decision to purchase a particular set of
documentation tools, because of requests for such information from
usenet readers. The author does not claim to be totally unbiased, and
this report is offered as my opinion only.
- Lar Kaufman 12/5/90
* WizardWare is a trademark of TIVOLI Systems, Inc.
* FrameMaker is a trademark of Frame Technology, Inc.
* Interleaf is a trademark of Interleaf, Inc.
* WordPerfect is a trademark of WordPerfect Corp.
* MS Word is a trademark of Microsoft Corporation.
* Unix is a trademark of Unix System Laboratories, Inc.
Report on the Selection of Documentation Tools
Lar Kaufman
November 13, 1990
Summary and Recommendation:
On examination of capabilities, only FrameMaker and Interleaf are
products that can meet our current and anticipated needs. The
FrameMaker package is the lower-cost and more effective solution
for our documentation requirements.
Introduction
In the interests of efficiency and brevity, this report focuses on
the two products that became the legitimate contenders for
adoption by TIVOLI - FrameMaker and Interleaf. Rather than
providing an exhaustive list all functions that are of interest in
developing documentation, I instead focus on significant contrasts
between these products. While the focus is on the FrameMaker/
Interleaf comparison, other products are mentioned in context.
A price/performance analysis is [omitted]
The report concludes with a listing of all considered products,
with summaries of their suitability for use and their limitations.
A listing of some resources and reading materials used in research
of this project is also provided. Some of these resources provide
feature-by-feature comparisons of products. These resources are
available for your examination.
The opinions of documentation professionals familiar with the
products were also solicited and considered in developing this
recommendation.
Both Interleaf and Frame have announced major release-level product
upgrades in 1Q 1991 (or earlier). I have read of these releases in
the press, and have discussed specific issues with vendor
representatives. [omission] The planned product changes
would not alter this recommendation. Some noteworthy changes are
forthcoming and are mentioned in context.
General Requirements
We want a package to produce long, complex documents in hardcopy form to
meet all anticipated documentation needs, and to produce hypertext online
documents compatible with the development of WizardWare products.
The selected tools must support formatting of equations and have effective,
easy-to-use drawing capabilities. The tools should use and support document
formatting standards that will maximize our options in selecting future
documentation tools [omission]
...such standards [imply] SGML, adopted as a document interchange standard by
OSF and SGML/CALS required for some U.S. government applications).
We want a tool for document preparation that appeals not only to professional
writers, but also to developers, general management and staff. It will
improve the efficiency of the documentation function at TIVOLI if technical
and marketing documents can be maintained in one format, with appropriate
source control.
Other considerations are compatibility with traditional documentation tools
and output in the Unix environment. Specifically, considerations for
compatibility include: emacs interface support, Word, TeX and troff input
conversion, and man page output.
Finally, the selected tools should be substantially compatible with current
and anticipated TIVOLI equipment, working environment, and software
development activities. [omission]
Comparison
A comparison between Frame and Interleaf must address general look-and-feel
issues as well as specific performance.
General
New users tend to prefer the FrameMaker user interface to that of
Interleaf. It is easier to learn. The FrameMaker interface conforms
generally to the user environment: it looks like SunView when run under
SunView, like a Mac when run on a Mac, [omission].
The Interleaf environment looks much the same regardless of the platform in
use. The FrameMaker ambiance resembles Word on the Macintosh. Frame uses
terminology that is more consistent with Unix, with files and paths selected
from a list-format window. Interleaf uses an "office' metaphor with an
iconic interface, with "cabinets," "drawers," "folders," and so forth,
rather similar to IBM's Office Vision. The Interleaf environment shows
element tags in the margin, while Frame lists the element under the cursor in
a field at the bottom of the window. Interleaf's 5-level-deep cascade-menu
user interface can irritate casual users unfamiliar with its structure.
Professional writers with extensive Interleaf experience may prefer the
Interleaf interface to FrameMaker's. Writers who like emacs will not be
particularly concerned with which GUI is used. (Both packages provide limited
emacs support, which is discussed later.)
Interleaf presents the full page to the viewer. FrameMaker does the same, but
also provides zoom support, with a zoom range from 25 - 1600 percent. This is
important for effective display on monitors of lower resolution or smaller
size, and is particularly useful in preparing effective illustrations.
Frame provides a full-featured package only (currently floating license only,
but in future with lower-cost fixed licenses available). Interleaf is bundled
in an array of packages offering different levels of features; graphics,
equation formatting, and tablemaking capabilities are only available in
options or in the graphics package or the "full" Interleaf package. The
complexity of preparing a functional mix of Interleaf packages is additionally
complicated by the need for host tuning for appropriate support - source
files, interface, etc. There is a supplemental, separately licensed,
FrameViewer tool which can be used to only read FrameMaker documents,
including online hypertext documents. (I'll touch on this again later in
this report.)
Interleaf has richer text formatting features than FrameMaker for hardcopy
output. Interleaf has better handling of multi-column formatting and some
advantages in controlling vertical spacing of text on pages that incorporate
artwork. FrameMaker, however, has quite acceptable formatting, and we do not
plan to use complex multicolumn formatting at this time.
Interleaf is also a bit faster than FrameMaker at drawing screens. However,
FrameMaker allows you to suspend pagination and turn off display of graphics
to rapidly incorporate a series of changes. The pages are reformatted when
the editing is completed. I noticed that X Window performance was
unacceptably slow on a Sun 3/80 for professional writing, so writers will
need to work in a SunView environment (or use a faster X Window host).
Key Features
There are several important differences between FrameMaker and Interleaf.
o FrameMaker has superior equation formatting and handling capabilities. In-
deed, Framemaker's equation handling is universally praised by reviewers.
The equation tool is easy to use; elements can be resized manually if the
automatic formatting is not suitable. The equation formatter can rebuild
equations to solve for any element. Equations can be actually solved, if
that is the intended usage. Using FrameMaker's live link (hyperlink)
capabilities, external values from another program, such as an SQL database,
can be plugged into an equation before solving. Interleaf's equation
formatting package is extra-cost except with the Graphics and Full packages.
o FrameMaker supports simultaneous multi-page viewing and editing.
o FrameMaker has a one-level undo function [omission]. Interestingly,
Avalon Publisher has a five-level undo function.
o FrameMaker's draw program is easier to use than Interleaf's. Interleaf's
extra-cost draw program has some superior features, however, such as a
variety of splining techniques. FrameMaker's drawing capabilities appear
to be adequate. Both Frame and Interleaf will upgrade their draw programs
to accommodate SGML and CALS requirements in future releases [omission].
It is unclear whether the Interleaf capabilities will be provided in the
Graphics or Full Interleaf packages, or only in the $60,000 CALS package.
o FrameMaker's table formatting capabilities are barely adequate, and in this
release is distinctly inferior to Interleaf's table formatting package.
Frame has scheduled tablemaking improvements for their next release. Note
that tablemaking is an option in Interleaf except with the Full package.
o SGML and CALS support. This will be important to us in developing online
documentation tools:
In theory, Interleaf has superior CALS support. They claim to have a
completely CALS-compliant package that supplies complete online documentation
functions and SGML support. However, this package requires at least three
full licenses plus a $60,000 CALS license. That means the buy-in price is
$105,000. Moreover, hypertext created with this package will not be
accessible unless you have the CALS package. This means that any hypertext
you create can only be used in-house. I was not able to get names of users
of this package and I am not sure it has actually been delivered to any
customer yet. [N.B. After it was clear that we were leaning away from
selecting Interleaf, they offered to unbundle the SGML package and offer
it separately. (SGML being our chosen vehicle to implement online docs.)]
FrameMaker was developed when the SGML ISO standard proposal was already
released, and the SGML tagging system is innate to FrameMaker. At
FrameMaker's next release, the native storage mode will be fully-compliant
SGML, simply by adding some element tags. [N.B. This is not demonstrated.]
[omission]
o Traditional tools support for the Unix work environment.
Interleaf has more conversion filters than does Frame. There are also a
number of third-party vendors that supply filters for Interleaf, and only a
few for Frame. Therefore, Interleaf should have an edge here. Both Frame
and Interleaf offer an extra-cost filter to import Word documents into their
product in the form of a DCA (document content architecture) file. This type
of conversion can only be partial, and I haven't had time to compare the
results. [N.B. FrameMaker's filter does a good job of it.]
Neither Interleaf nor Frame provide a filter for TeX, although our
Interleaf distributer claims they can locate a product to do the task or do
it themselves (at what price?).
Interleaf can name several vendors to convert Interleaf-prepared man pages
into troff man pages, while Frame cannot. However, with FrameMaker I can do
this task myself by creating my own shell script; FrameMaker supports a macro
language that I can map to convert the set of man macros. Both products'
filters can import troff files. [N.B. FrameMaker says their next release
will have bi-directional filters.]
Both FrameMaker and Interleaf support a limited emacs keyboard interface.
Frame's is more extensive and better documented: some mapped functions are
not emacs-compatible (though they are mnemonic). FrameMaker provides a
macro language to create new key definitions and assign defined functions.
Interleaf allows you to create new functions in Interlisp language, but you
must have full Interleaf to have the capability. Interleaf relies more on
cascade-menu functions selected by mouse.
o Both FrameMaker and Interleaf support only one level of revision (marked
by revision bars). FrameMaker additionally plans multiple version control.
I can create a multi-level revision control system for either package using
a shell script and common document control procedures.
o FrameMaker supports the use of text variables.
o Both FrameMaker and Interleaf support grey-scaling in illustrations and
backgrounds. FrameMaker additionally supports eight color display, with
optional color output. This will be useful in developing hyperhelp
documents on some hosts. Interleaf's advanced grey-scaling is extra-cost
except in the Graphics and Full packages.
o Interleaf better handles linking an illustration to text, while FrameMaker
better handles linking text to preceding text (preventing unwanted separation
by page breaks). Both Frame and Interleaf are faulted in their handling of
floating illustrations, but Full Interleaf handles this task better,
including easier manual correction of illustration placement.
o FrameMaker's search and replace function is case- and style-sensitive,
supports wildcard characters, and can be applied globally or in restricted
areas. Global mode also searches within illustrations. Interleaf's search
and replace function possesses none of these features beyond global search
(exclusive of illustrations).
o FrameMaker's spelling checker (130,000 words), like Interleaf's (80,000
words), is interactive. In addition, it supports multiple dictionaries - up
to 11 at once. Included are 11 foreign-language spelling and hyphenation
dictionaries. Interleaf only supports several European languages (British,
French, Spanish, and Scandinavian languages) if you have their International
edition: FrameMaker offers an International edition with a 1.5 million-word
multi-language dictionary and US/UK English spelling conversion. FrameMaker
marks text that has been checked for spelling, and does not recheck marked
text unless it is changed. This makes FrameMaker's spelling checker easier
to use as you are writing, to provide the immediate feedback that improves a
writer's spelling skills. It also speeds spelling checking on revised
documents.
o Both FrameMaker and Interleaf are available on all platforms on which we
will do software development in [timeframe omitted]. However, Interleaf is
available at different build levels on different platforms, and not all
versions are format-compatible. Frame is available on all supported
platforms in substantially the same release, with full file compatibility.
o FrameMaker's font justification algorithm is better than Interleaf's and
bounds are adjustable by the user. FrameMaker also permits manual kerning
adjustments. Interleaf's automatic kerning is superior.
o FrameMaker's character set is much larger than Interleaf's, supports
automatic fraction generation up to three levels deep, and (Zapf) dingbats.
o Interleaf's page layout capabilities are more precise than FrameMaker's, but
less adaptable (cannot be adjusted within the document). FrameMaker allows
mixing of portrait and landscape pages, while Interleaf does not. Frame
supplies a greater number and variety of style sheets, including styles
intended for online display.
o FrameMaker warns of unresolved cross-references.
o Interleaf supports anchored illustrations with in-page float.
o FrameMaker supports live links to system calls and other applications and
files, including full SQL support and linking to dedicated 3-D CAD packages
for illustration (and even animation). Interleaf supports live-link
(active-document) capabilities with its CALS package and says it will offer
the capability with Interleaf 5.0. Interleaf's promised active-document
feature is only discussed in terms of hypertext support - not data and
graphics importation.
o FrameMaker can import Interleaf documents. Interleaf says they cannot
import FrameMaker documents. (They should be able to do so using the CALS
package, by treating a Frame document as a CALS document.)
The Rest of the Story
We considered all known viable options for creating documentation. Some of
these are worthy of consideration as supplemental tools for our selections.
o Documenter's Work Bench (AT&T). This is the venerable traditional set of
Unix documentation tools: nroff, troff, eqn, tbl, pic, ptx, ms, man, etc.
It is remarkably flexible and it is easy to tinker with in Unix. Many of
the tools can be supplemented or replaced by better tools. It has several
significant failings as a documentation toolkit, however. Cross-referencing
and indexing tools are non-standard and limited. Graphics support is
negligible. [omission] The primary disqualifier, however, is that dwb
is simply too slow to use as a production tool. [omission]
Note:
4.4BSD will not provide man pages; an alternative will be developed
(probably based on TeX).
o xroff, Xviews (Image Network). This is an updated alternative to dwb.
Device-independent troff and enhancements. Provides X Windows output
formatting and device drivers for a remarkable selection of printers. Also
available to run on MS-DOS. Image Network also has developed an SGML-
to-xroff conversion tool and is interested in developing online
documentation tools based on SGML. Xroff has the same advantages and
disqualifier as dwb, although output options are better. I recommend
[omission]
o sqtroff, Author/Animator (SoftQuad) SoftQuad's sqtroff is yet another
device-independent troff. [omission] SoftQuad is one of the very first
SGML developers in North America. I was hoping for a seamless
SGML/troff/man conversion tool by now, worthy of serious consideration
(perhaps in conjunction with Xviews). Unfortunately, Author/Animator, the
WYSIWYG SGML editor/formatter is only available currently for Macintosh,
which SoftQuad identifies as a key multimedia platform. (SGML has great
potential as a multimedia/hypermedia tool.) Author/Editor for SunView and
X will not be available until 1Q 91, and the sqtroff/SGML/man conversion
tool will not be available until 2Q. [omission]
A save-disabled demo version of Author/Editor for Macintosh is
available in-house for those who would like to try it. A manual is provided.
o TeX tools. This is an appealing option, as the developers and most of
management is familiar with TeX and LaTeX. TeX is a powerful formatter,
with excellent publishing features. The problem of having no supported or
integrated package of tools can be partially addressed by using Arbor
Publisher (Arbor), formerly known as ArborText. [omission]
The potential of TeX is blunted by the high learning curve and the low
productivity rate to accomplish sophisticated production. (Much of the
formatting power of TeX cannot be harnessed from the macro packages
available, and thus working in raw TeX is necessary.) An effort
to integrate TeX tools is now taking place at the Free Software
Foundation... [omission] with excellent hypertext potential.
[omission]
o Avalon Publisher (Elan) Avalon Publisher is a bold attempt to go head-to-
head with Interleaf and Frame. It is a remarkably easy-to-use tool, well
integrated and fast, with an emacs-type keyboard interface. Unfortunately,
it is too incomplete to meet our needs. There is no equation formatting
tool, and the draw tool, while very friendly to use, has some serious
limitations. It cannot, for example, draw or letter white-on-black. Avalon
Publisher also had no filters and conversion tools, although Avalon/eroff
conversion will be available 1Q90. (eroff is yet another device-independent
troff.) I would select Avalon to use as a newsletter production tool. I was
very pleased with the user interface, but we need a more powerful and
flexible production tool. We have a save-disabled demo version of Avalon
in house, with a manual.
o Island Write/Draw/Paint (Island Graphics). Island positions its package as
a budget-priced, powerful tool set to supplement Interleaf or FrameMaker.
It doesn't have the powerful device-drivers, but it does offer a powerful
toolkit for document preparation, and emphasizes that it can import and
export between Island W/D/P and both Interleaf and FrameMaker. It offers a
nice clip-art library as an option. An earlier version of these tools was
offered by Sun as Sun Write, Sun Draw, and Sun Paint. We did not test
Island, although we have an information package. Island's strategy is to
suggest that you buy either Interleaf or FrameMaker as your master
production tool, and supplement it with multiple copies of W/D/P as an
economical way to prepare documentation. I was not taken with this
suggestion, as my experience in document conversion has shown that it is
very difficult to perform document conversion efficiently enough to
incorporate the technique as a production method. The loss of significant
formatting information is simply too great. On the other hand, Island does
offer features that encourage me to consider it as a supplemental tool:
- Island has a strong graphics focus, and can import a large number of
import formats, converting them to Frame or Interleaf form. The draw
package looks very powerful. The Paint program is unparalleled in
Frame or Interleaf [omission]
- If the document conversion and graphics importation functions are good, it
is more cost-effective to buy Island W/D/P than to buy the graphics filter
option package for FrameMaker (or Interleaf). As a bonus, you get the
ability to convert between FrameMaker and Interleaf document formats via
Island, and an overflow writing tool to use without buying another user
license.
This may be a very effective tool for creating graphics [omission]
...if we need to go beyond the draw capabilities of FrameMaker.
o Word Processors. The PC environment has produced several powerful word
processors that are sufficiently powerful to use as publishing tools. They
excel in ease-of-use and graphics handling. There are two major
word-processing packages that have been migrated from the desktop PC
environment to Unix: WordPerfect and Microsoft Word.
- WordPerfect 4.2 has been ported to a number of Unix platforms, and has a
large body of features. However, WordPerfect is [weak] when working
with large files or multi-document formatting tasks. [omission]
Also, the (shift/alt/ctrl-)function key
oriented approach to editing makes it an undesirable tool for serious
writing. WordPerfect Corporation has established its market share because
of its remarkable customer support [in the PC environment] [omission]
WordPerfect 5.0 is available for SCO Xenix only.
- Word is a more intriguing possibility. Microsoft announced a project to
migrate Word to various Unix platforms. However, when I enquired at
Microsoft about Word for Unix, I was referred to SCO. The SCO sales
representative insisted that Word for Unix was ported to Xenix for the
286 and 386 only, but it would "run fine" on SCO Unix 386. (I infer that
Word for Unix is compiled for the 286 architecture.) He was unaware of any
plans to migrate Word to Sun platforms, and could not tell me whether
X Window interfacing was supported. (I presume it is.) Unfortunately,
SCO clearly wants this product only to promote SCO Unix/Xenix sales, and
Microsoft seems indifferent to the potential Unix market.
o Miscellaneous tools. I encountered some interesting byways that we will want
to explore in the future for our needs in preparing online documentation and
context-sensitive help:
- BBN/Slate (Bolt, Berenek and Newman). An X Window based, multimedia
workstation communications program suitable for use for network e-mail,
real-time workgroup conferencing, and multimedia publishing. Currently
runs on the IBM RS/6000, Sun workstations, DECstations and VAXstations.
"It is designed... to create, edit, integrate and share on-line technical
and business information. The program can transmit multiple forms of
data, such as text, spreadsheets, business and geometric graphics, color
images, data files and voice annotation (on some workstations)." Color and
b&w PostScript output devices are supported. My guess is that this is
another SGML product, as it was developed for government and defense users
initially. Pricing is actually reasonable (for end-users) at $995, with a
volume discount. I intend to gather more information about BBN/Slate.
- Open Text Systems, of Waterloo, Ontario, markets Open Text Tools. (The
Open Text Tools were developed for the Electronic Oxford English
Dictionary project, are SGML-based tools that run on a variety of
X Window Unix platforms, and are being ported to Macintosh platforms.) The
Transduction Toolkit converts various text formats into and out of SGML
format. PAT accesses a huge (hyper)text database using a variety of
search and display features. LECTOR is a hypertext display system.
GOEDEL builds a production database with audit trails and concurrency
protection. TRUC is a structured text editor. EDITOR'S WORKBENCH
integrates PAT, LECTOR, and GOEDEL in a single package.
This stuff is remarkable, and demonstrates some of the potential of SGML.
Open Text Systems wants a lot of money for their products. It appears
that they are marketing directly to large corporations for internal
information management, rather than to application developers.
Competing and/or related information-handling and retrieval products are
available from BRS, CP International, Cuandra Associates, Excaliber, Fulcrum
Technologies, Information Dimensions, Knowledge Set, Third Eye Software,
Thunderstone, Verity, Wisdom Technologies, and Zylab. I will gather more
information about these packages for examination while preparing
recommendations for developing our online documentation system.
The Bottom Line
Raw Prices
These are the offered product prices for various products and related services.
[ Prices are omitted in consideration of vendors and VARs.]
References
These materials are available for your examination in reference to this
recommendation:
o SGML: An Author's Guide to the Standard Generalized Markup Language, Martin
Bryan, Addison-Wesley, 1988.
o Prowess on the Desktop, UnixWorld, March 1990.
o Interleaf TPS and FrameMaker In a Technical Environment, Jon Glickman and
Scott Hatch, 37th International Technical Communication Conference, Santa
Clara, CA, May 22, 1990.
o Thinking in Multimedia, UnixWorld, August 1990.
o In Search of Text, UnixWorld, August 1990.
o Nearly Perfect WordPerfect, UnixWorld, September 1990.
o Publish or Perish: Comparing Desktop Publishing Platforms, Personal
Workstation, September 1990
o Currents, Unix Review, October 1990.
o Avalon Publisher to vie with Interleaf and Frame Maker (sic), Personal
Workstation, October 1990.
o Is the Typesetter Obsolete?: High-end DTP Packages, Byte, October 1990.
o FrameMaker Now in X Window, Motif, Unix Today!, October 1, 1990.
o Report on Desktop Publishing, Seybold, October 3, 1990.
o Multimedia Communications Tool Bows, Unix Today!, Oct. 15, 1990.
o A Tailored Publishing System, Unix Today!, October 15, 1990
o The Age of Hypertext, UnixWorld, November 1990.
o [host/path omitted], A compendium of recent Usenet correspondence and
postings.
o Promotional Materials from Open Text Systems, Frame Technologies,
Interleaf, Elan Software, SoftQuad, and Island Software.
o Demonstration Software for:
o Author/Editor (Macintosh) including User's Guide
o Avalon Publisher (SPARC) including User's Guide
o Interleaf Publisher Full, Release 4.0 (SunView and X Window). With import
filter package. Documentation separately acquired from [omitted].
o FrameMaker 2.1x (SunView and X Window). No documentation other than online.
------- End of Report -------
-lar
--
Lar Kaufman I would feel more optimistic about a bright future
(voice) 512-329-2455 for man if he spent less time proving that he can
(fax) 512-329-2755 outwit Nature and more time tasting her sweetness
lark@tivoli.com and respecting her seniority. - E.B. White