Oct 97 MacTech Online
Volume Number: 13
Issue Number: 10
Column Tag: MacTech Online
MacTech Online
by Nicholas C. "nick.c" DeMello <online@mactech.com>
Building a Better ReadMe
You just finished your latest program and realized that the average user will never
discover three of the new features on their own (or at least not appreciate the
advantage of those features without a little explanation). That same user will find out
that your program is incompatible with seven shareware system extensions that you
couldn't accommodate, and that user will send you e-mail about each one --
separately. It's time to create your release notes (creatively titled "ReadMe"). This
column lists a few online resources to make building your ReadMe just a little easier.
Keep it Simple
Most release notes are distributed as documents of the type "ttro" and creator "ttxt
-- SimpleText read-only documents. Originally, TeachText, SimpleText is that small
text editor that gets added to your hard disk with every Apple software installation.
Various groups at Apple enhanced TeachText to make it a better vehicle for their
particular technologies. In 1995, a half dozen of these "enhanced" versions of
TeachText were combined to form SimpleText, which can now create styled text,
display colored text, play QuickTime movies, drag and drop text editing, convert text to
speech, record sounds, play sounds, and has limited support for QuickDraw 3D.
Notice I said "display colored text" -- not create it. The easiest way to add colored text
to your ReadMe files is with Alessandro Levi Montalcini's SimpleText Color Menu
utility. This utility can modify a copy of SimpleText by installing two new menus.
Features in the new menus allow you to colorize text, search, search and replace, store
a default text style, and gives you the option of opening read only documents as editable
text.
Pictures can be added to your SimpleText documents with a resource editor. Open the
document with ResEdit or Resorcerer and save your pictures as 'pict' resources
(number them 1000 and up) into the resource fork. Then, open the document with
SimpleText and enter a non-breaking space (option-spacebar, the ASCII character
$CA) where you want each picture to appear. SimpleText will draw 'pict' ID 1000
horizontally centered on the screen. The top of the picture will begin where the first
non-breaking space appears. SimpleText will display 'pict' ID 1001 at the second
non-breaking space and so on. Because SimpleText is a text editor, it will only allocate
enough space on the screen for the non-breaking space character (not the picture),
you will have to add sufficient white space to make sure the picture doesn't overlap
text. Apple's Technote 1005 (by Bryan Stearns, revised by Mark Cookson), "The
Complete Guide to SimpleText," provides a detailed description of fine art of importing
'pict' resources into SimpleText documents.
Download PICTify by Scott A. Johnson to help you collect those 'pict' resources. PICTify
is a system extension which allows you to grab screen shots (cropped as you take them
or of the whole screen). In addition to being able to take screen shots with menus down,
PICTify has a feature to allow you to grab only the contents of the foremost
window--ideal for taking quick pictures of dialog boxes. Best of all, PICTify allows
you to save your images as either pict files or 'pict' resources.
SimpleText is not able to save documents as 'ttro'--but that is how Apple recommends
you distribute your release notes. There are a number of utilities for changing file
types, but I'm particularly fond of a freeware utility called "TEXT <-> ttro." It toggles
files dropped on it between "TEXT" and "ttro" types, and causes the finder to
immediatley update the icon (something many type utilities fail to do).
SimpleText
ftp://swupdates.info.apple.com/Apple.Support.Area/Apple.Software.Updates/
US/Macintosh/Utilities/SimpleText_1.3.sea.hqx
Alessandro Levi Montalcini, author of SimpleText Color Menu
http://persoweb.francenet.fr/~alm/
Technote 1005: The Complete Guide to SimpleText
http://gemma.apple.com/dev/technotes/tn/tn1005.html
Scott A. Johnson's PICTify
ftp://mirrors.aol.com/pub/info-mac/gst/grf/pictify-15.hqx
TEXT <-> ttro by Laurence Harris
ftp://mirrors.aol.com/pub/info-mac/text/text-to-ttro.hqx
Beyond SimpleText
SimpleText isn't your only choice for creating distribution documents. Mark Wall's
feature rich DOCMaker is the standard for creating stand-alone, self-running
document files. DOCMaker allows you to add hypertext, pop-up graphics,
startup-splash screens with sound, and even lets you import RTF files. It's overkill
for a ReadMe, but when you find it's time to start including a manual with your
application, this is the right tool.
Marco Piovanelli is the author of the WASTE (WorldScript-aware Styled Text Engine)
library. This powerful text editing engine has been incorporated into many text
editors, and appropriately enough into Marco's own answer to SimpleText. Piovanelli's
scriptable Style editor lets you paste graphics from your clipboard within styled and
colored text, then save those documents as stand-alone self-running documents, as
read-only SimpleText, RTF, or your choice of over a dozen word processing formats.
DocMaker 4.8 by Mark Wall of Green Mountain Software
http://www.hsv.tis.net/~greenmtn/
Marco Piovanelli's Style (also the WASTE -- WorldScript-aware Styled
Text Engine -- Library)
http://www.kagi.com/authors/piovanel/
These and other links are available at the MacTech URL database
http://www.mactech.com/magazine/urls/.