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 --
jbr0@cbnews.att.com (joseph.a.brownlee) (08/24/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. [...] My question is, in what format >should the files be distributed? [...] > >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. [...] I'm not sure exactly what to suggest, Avi, but I agree that this is an annoying problem. As I have often stated on the net, I am a fan of WriteNow, and I generally use it over Word, which I also own (uh, license -- my wife likes Word). I do not have any version of MacWrite. It seems that the vast majority of documentation is distributed in MacWrite format, with a significant amount still distributed in Word formart, and a few distributed as raw text. Since I own Word, that format isn't a problem. Text, too, can be read by many programs. But MacWrite is another story. Perhaps it is just a deficiency in the word processors I have used, but it seems that translating to or from MacWrite always leaves me with formatting problems. If I read a MacWrite file in WriteNow, it is about 80% guaranteed that the tab settings won't even be close. If I guess, I can sometimes fix them, but I am tried of trying to fix all the distributed documentation (especially Tech/HIG Notes) to be legible. On top of that, I get spurious page feeds, and PASCAL source loses its comment strings. The sequence '(*' must be special to the translation process. Also, the headers and footers don't translate correctly. I really don't have a knowledge of RTF. I've saved some documents in that format to see what it looks like, but I have not really seen any documents distributed in that format. I must agree that this is a rather sorry state of affairs. I hate spending valuable time trying to make TechNotes or other important documents readable rather than spending that time programming the Mac! I also hate being forced into buying MacWrite just to be able to read and print documents when I don't want it for anything else. May be we need a read-only version of MacWrite ("MacRead"?). I suppose any format which tries to bridge the feature set provided by many word processors is prone to problems, but I would think that the Mac community could do better than the current status quo. -- - _ Joe Brownlee, Analysts International Corp. @ AT&T Network Systems /_\ @ / ` 471 E Broad St, Suite 1610, Columbus, Ohio 43215 (614) 860-7461 / \ | \_, E-mail: jbr@cblph.att.com Who pays attention to what _I_ say? "Scotty, we need warp drive in 3 minutes or we're all dead!" --- James T. Kirk
dorner@pequod.cso.uiuc.edu (Steve Dorner) (08/24/90)
In article <23862@dartvax.Dartmouth.EDU> ari@eleazar.dartmouth.edu (Ari Halberstadt) writes: >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. I am now distributing the manual for my Macintosh email program, Eudora, in "Glue" format. "Glue" is a chooser-level "printer" driver that saves what you print to disk, in one of several formats. Included in the "Glue" package is a FREEWARE viewer, that you can also distribute with your documentation. The viewer lets you browse or print the documentation, and also lets you Edit->Copy sections of it. The Eudora manual is 50 or 60 pages, in PageMaker, with lots of illustrations. It seems to work just fine. (If you'd like to see for yourself, anonymous ftp to ux1.cso.uiuc.edu, and look in the mac/eudora subdirectory.) Glue (actually, "SuperGlue II(TM)") is from Solutions, Inc.; it costs $60 or so from the mail-order places. While it's kind of irksome to have to pay to be able to give away documentation, it's the best solution we've found so far. [My thanks to Doug Walsten of NCSA for suggesting Glue to me.] -- Steve Dorner, U of Illinois Computing Services Office Internet: s-dorner@uiuc.edu UUCP: uunet!uiucuxc!uiuc.edu!s-dorner
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."
jmunkki@hila.hut.fi (Juri Munkki) (08/25/90)
In article <1990Aug24.143007.5915@ux1.cso.uiuc.edu> dorner@pequod.cso.uiuc.edu (Steve Dorner) writes: >Glue (actually, "SuperGlue II(TM)") is from Solutions, Inc.; it costs >$60 or so from the mail-order places. While it's kind of irksome to >have to pay to be able to give away documentation, it's the best solution >we've found so far. If you just want to distribute documentation, you might want to save the $60 and use the BatchPrint application that comes with the HPDJ (HP DeskJet) driver. The files were available from sumex-aim, but might have been removed for lack of space. If you can't find them there, you can get them from our ftp site at: vega.hut.fi 130.233.200.42 /pub/mac/finnish/deskjet/ This might also be a great way of creating an online help facility, since the application comes with source code. Just write your documents with your favorite program and print them to disk. ___________________________________________________________________________ / Juri Munkki / Helsinki University of Technology / Wind / HP S / / jmunkki@hut.fi / Computing Center Macintosh Support / Surf / 48 X / ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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.)