ari@eleazar.dartmouth.edu (Ari Halberstadt) (08/24/90)
Dear Macintosh Users, I am about to post a set of free XFCNs, including source code and over 100 pages of documentation. The documentation has been specially formatted in the style of technical documentation. I would like to distribute the documentation so that the maximum number of people will be able to read it, with all of its formatting and illustrations intact. My question is, in what format should the files be distributed? I wrote the documentation in Microsoft Word 3.1. Unless told otherwise, I intend to distribute the files in Microsoft Word's Rich Text Format [RTF]. Unfortunately, even when uploading into Microsoft Word 4.0, there are some losses in the formatting commands. If the same corporation can't maintain compatability between its products, I see little reason why word processors from other manufacturers will be able to interpret the files. I have tried saving the files in MacWrite format, but this looses most of the formatting. If I manually fix up the file, I can get some improvement, but this has proven too time consuming and error-prone. Since the software is free, I will be unable to offer printed versions of the manuals. Obviously, the problem of distributing documentation for the Macintosh is very serious. There seems to be no standard which will cope with complicated formatting information. The Macintosh is supposed to be easy to use, yet it requires its users to worry about obscure file formats. This situation is reminiscent of the DOS world, a world we would like to think the Macintosh has improved uppon. Any suggestions will be appreciated. Sincerely, Ari Halberstadt ari@dartmouth.edu --
rmh@apple.com (Rick Holzgrafe) (08/25/90)
In article <23862@dartvax.Dartmouth.EDU> ari@eleazar.dartmouth.edu (Ari Halberstadt) writes: > I am about to post a set of free XFCNs, including source code > and over 100 pages of documentation. The documentation has > been specially formatted in the style of technical documentation. > I would like to distribute the documentation so that the maximum > number of people will be able to read it, with all of its > formatting and illustrations intact. My question is, in what format > should the files be distributed? I recommend MacWrite format. It's a lowest common denominator, which means it can't handle fancy formatting. But every Mac word processor I've ever seen or heard of can read it. > Unless told otherwise, > I intend to distribute the files in Microsoft Word's Rich Text Format [RTF]. > Unfortunately, even when uploading into Microsoft Word 4.0, there are > some losses in the formatting commands. Most word processors can't read RTF. If you must have Word's formatting abilities, you might as well avoid RTF and distribute in Word's native format. > Obviously, the problem of distributing documentation for the Macintosh > is very serious. There seems to be no standard which will cope with > complicated formatting information. The Macintosh is supposed to > be easy to use, yet it requires its users to worry about obscure > file formats. This situation is reminiscent of the DOS world, a world > we would like to think the Macintosh has improved uppon. Yup. There are a few widely-used standards for graphics files, but none except MacWrite for formatted text. I'd like to see something like RTF become a widely-used standard, but as you say, there isn't much hope if even the company that authored the standard can't get it right. I still think your best alternative is MacWrite. It's not powerful, but *everyone* can read it. ========================================================================== Rick Holzgrafe | {sun,voder,nsc,mtxinu,dual}!apple!rmh Software Engineer | AppleLink HOLZGRAFE1 rmh@apple.com Apple Computer, Inc. | "All opinions expressed are mine, and do 20525 Mariani Ave. MS: 3-PK | not necessarily represent those of my Cupertino, CA 95014 | employer, Apple Computer Inc."
CAH0@bunny.gte.com (Chuck Hoffman) (08/25/90)
I know this is hard to believe, but *TeachText* has a place here. Although I have used other word processors to publish things like classroom material, TeachText does just fine for things I might distribute on diskette. TeachText can include graphics, too, as I found recently in Tech Note #274, "The Compleat Guide to TeachText." Its advantages: literally everyone has it, and you can distribute your stuff in read-only format (the little newspaper icon) without actually locking the file (which can interfere with some copy and backup programs). My personal feeling is that sometimes people get carried away with turning their documentation into works of art. Keep it simple, ala' TeachText, and your users / customers will always be looking at exactly what you intended for them to see. The more "featuresome" word processors can only guarantee this if you distribute on paper - which is exactly what I use them for. -Chuck - Chuck Hoffman, GTE Laboratories, Inc. cah0@bunny.gte.com Telephone (U.S.A.) 617-466-2131 GTE VoiceNet: 679-2131 GTE Telemail: C.HOFFMAN
boris@world.std.com (Boris Levitin) (08/26/90)
In article <23862@dartvax.Dartmouth.EDU> ari@eleazar.dartmouth.edu (Ari Halberstadt) writes: >> I am about to post a set of free XFCNs, including source code >> and over 100 pages of documentation. The documentation has >> been specially formatted in the style of technical documentation. >> I would like to distribute the documentation so that the maximum >> number of people will be able to read it, with all of its >> formatting and illustrations intact. My question is, in what format >> should the files be distributed? >> [MacWrite loses much of the formatting] Help is on the way to a degree in the form of Claris's XTND technology. I've just started using On Location, which uses XTND to allow viewing of MS Word files, and most formatting is interpreted correctly (with some glaring exceptions, such as tables). If you can, distribute in MacWrite format; it is readable directly by every other word processor. If you have to use MS Word, it's not the end of the world, since Word has 50% of the market share and applications which can read its format probably have around 70% to 75% penetration. I'm noticing more and more documentation for share/freeware being distributed exclusively in Word format. Another soultion is to use Solutions International's SuperGlue II, a utility which generates a file of the image of your document. It can be read and printed without the creating application present (but it cannot be edited). SuperGlue II comes with a viewer application that you can distribute freely. Boris Levitin ---------------------------------------------------------------------------- WGBH Public Broadcasting, Boston boris@world.std.com Audience & Marketing Research wgbx!boris_levitin@athena.mit.edu ---------------------------------------------------------------------------- (The opinions expressed herein are my own and do not necessarily coincide with those of my employer or anyone else. The WGBH tag is for ID only.)