Path: utzoo!utgpu!news-server.csri.toronto.edu!rutgers!tut.cis.ohio-state.edu!att!cbnews!jbr0
From: jbr0@cbnews.att.com (joseph.a.brownlee)
Newsgroups: comp.sys.mac.programmer
Subject: Re: What file format should technical documentation be distributed in?
Message-ID: <1990Aug24.122642.15472@cbnews.att.com>
Date: 24 Aug 90 12:26:42 GMT
References: <23862@dartvax.Dartmouth.EDU>
Distribution: na
Organization: AT&T Bell Laboratories
Lines: 56

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