All DatabasesMacTech Vol 08-1992
SoftPolish
Volume Number: 8
Issue Number: 6
Column Tag: Jörg's Folder
Polish Your Application
SoftPolish™ - a quality checker to help put the shining touch on your
application
By Jörg Langowski, MacTutor Regular Contributing Author
No, contrary to what you might think, looking at my family name and my
involvement with Forth, I’m not writing about how to translate your favorite C++
program into reversed Polish notation. This time we pronounce ‘polish’ with a short ‘o’
like in ‘soft’. Language Systems, the guys who brought you LS Fortran for MPW, have
just recently started to ship SoftPolish, a software quality improvement tool that helps
you put the last shining touch on your - almost - ready to go application. I received an
evaluation copy and want to tell you my impressions.
SoftPolish is, as I said, a tool. I just read a letter in the July issue complaining
about the tools’ reviews which we have regularly (and about the needlessness of
Fortran and Forth, for that matter, so I have to answer to this one). What after all do
we program the Macintosh for? For our own pleasure, that’s for sure, but many of us
make real money developing and selling programs, or writing programs that help them
doing some other job, like treating data. Now, you can write programs for fun and be
content if that great idea of a new sorting algorithm or a hack around the Launch trap or
that fast 3-D plotting routine really works. But no one (or only a few good friends)
will listen to your well-deserved enthusiasm or even use your program when a) you
can’t explain (Xplain?) to them how to use it and b) they can’t use it without your
continuing help because of illogical behavior or -worse - ‘undocumented features’ (no,
NO!!! don’t double-click the mouse outside that window, you’ll destroy your hard
disk!!!! ohwelltoo late.). This is speaking of my own experience, so let’s hear it for
good documentation and well-thought out and bug-free user interfaces. Not that I’m
writing any of that stuff for MY programs. I did it once, for something that I distributed
to a number of people, and in a very imperfect way. Still it took a lot of time, and I
admire those who have the patience to create a perfectly looking, logical, easy to use
interface to their original software idea and then give it away or sell it at cost. In my
own field, the genetic data editing package DNA Strider comes to mind, or the desk
accessory editor McSink (now Vantage, a commercial product).
Anyway, SoftPolish is a program that helps you to create a user interface that
doesn’t confuse the user, or pull the rug under his feet because you forget to put some
necessary resources into your application and that didn’t show up during testing.
How SoftPolish works
SoftPolish checks three major aspects of a Macintosh application:
• the consistency of the user interface;
• the validity of resources, their types and numbers;
• the spelling of strings anywhere in the program ( dialogs and alerts, STR, STR#
resources, file and folder names, etc.).
To see what SoftPolish does, let’s go through the example that is given with the
disk. There is an application ‘Testapp’ created with AppMaker, which contains several
deliberate errors.
When you start SoftPolish, it comes up with a ‘Navigator window’, like a
modeless dialog box. Here, you can choose one of six functions (which are also accessible
through the menus): Choose Target, Build User Dictionary, Scan Target, Correct
Spelling, Clean up, and Help.
You have to choose a target first, so you click the corresponding box, you select
the application to ‘polish’ from a standard file dialog, and then you may start by
clicking ‘Scan Target’. The User Interface Police then starts to scan all resources of the
application. The following checks can be made:
• Are the menu command key equivalents correct, i.e., are any characters used in
duplicate, or used in a way not recommended by the Apple Human Interface
Guidelines?
• Are the menu titles correctly capitalized? (i.e., a menu or window title starting
with a lower case letter is not recommended)?
• Do the dialogs and menus fit on a small screen (PowerBook or Macintosh
Classic)?
• Is the space for dialog text items large enough to contain all the text (such
problems may occur after an application has been localized for a different
language)?
• Do all dialog items fit inside the dialog box, are they non-overlapping, not too
small or too big, and is there enough space between them and the dialog border?
• ‘Old style’ quotation marks like the ones I use all the time (',") are flagged
because they should be replaced by the “new style” (“,”,‘,’). So are ellipses ()
that are made out of three periods in a row (. . .).
• Word and sentence spacing are checked; you should not use two spaces between
words, or after a period.
• Are any resource numbers used that are reserved by Apple? Are there any
resource types which are lower-case only (that’s also reserved)?
• The internal consistency of resources is checked.
• Any resources which should have a fixed size (like an ICON) are flagged if their
actual size is different.
• ALRTs, DLOGs and DITLs are cross-checked to make sure the resources referred
to in another resource are present.
• All strings in the application (STR#, STR, DITL, file and folder names etc.) are
checked for correct spelling. An English dictionary is included; I also received a
French dictionary in my evaluation copy, and there are dictionaries available for
other languages (Dutch, French, French Canadian, German, Italian, Norwegian,
Portuguese, Spanish, Swedish, and U.K. English at $49 each). You can build your
own user dictionary for technical terms not included in the main dictionary.
While the scan is running, a log is written to a text window which you can
review after the scan, and save or print.
SoftPolice - sorry, SoftPolish - will also make some of the necessary changes to
your application if you tell it to do so. Misspelled words can be corrected - like in any
good spelling checker, alternatives are suggested - and you can define a list of unwanted
resources that you want to be removed. For instance, some resources might be left over
from testing and are not needed in the final application. The modification and creation
dates will also be set to any value you like. Any inconsistencies found in resource
numbering or dialog layout will, of course, have to be corrected by the programmer.
Documentation
The 50-page manual is of the usual quality you’d expect from Language Systems
when you know their Fortran manual. The various options of the program are described
very clearly, and a tutorial is provided that lets you test some of SoftPolish’s features
on a test application. All the important information from the manual is also repeated in
a Help window that you can call it up.
I’ll show you some examples of the types of errors flagged in the test application:
1. Multiple spaces in About box:
yields the following error message:
DITL 1 “About”
The user interface was created with AppMaker, then AppMaker generated the
source code.
•• Multiple spaces between words
The next dialog contains several errors:
DITL 130 “Mistake”
cancel
•• Should the word start with a capital letter?
DITL 130 “Mistake”
This Check box will not fit in this dialog
•• Space is not wide enough for the text
DITL 130 “Mistake”
This Item is Spaced. Out
•• Multiple spaces between words
DITL 130 “Mistake”
This item is Mspelled
•• Questionable spelling: Mspelled
DLOG 130 “Mistake”
•• DITL 130 item 2 is within 6 pixels of the edge of the window
•• DITL 130 item 3 is within 6 pixels of the edge of the window
•• DITL 130 item 4 is within 6 pixels of the edge of the window
The last dialog box will definitely create a problem for a Mac Plus or Classic
user and SoftPolish complains at once:
DLOG 129 “Problems”
•• The window is too wide to fit on 9” screens
DITL 129 “Problems”
This is a poorly desined dialog box. It definitely will not fit on a small screen!
•• Questionable spelling: desined
DITL 129 “Problems”
TestApp’s comment
•• Should this be a real apostrophe (’)?
DITL 129 “Problems”
•• PICT 128 needed by DITL 129 item 4 is missing!
There are many more errors which are flagged in this program by SoftPolish.
Actually, it becomes annoying to see all of them and you really feel you have the User
Interface Squad on your back. But I think it is of great help to developers in the final
steps of creating a new program, it should remove many errors which may otherwise
be detected only after months of testing (i.e., alert boxes which are presented only for
very rare errors).
Aside from the spelling checker, an absolute necessity looking at some of the
existing applications, I e specially like the option which cross-checks whether all
resources referenced in a dialog are actually present, and the size checks on dialog
boxes and dialog items. The only negative thing about SoftPolish may be its rather steep
price - $295 suggested - but mail order sources might offer it cheaper. [Check the
MacTutor Mail Order Store for a special of $169 until October 31, 1992. - Ed.]. An
individual developer will probably think twice before spending 300 bucks for a tool
which is used much less often than for instance his C compiler which is in the same
price range.
User customization
When I just wanted to send off my column, I received two tech notes from
Language Systems (which they actually had announced to me before). They describe how
you can modify the resource checking process to adapt it to your own specifications
(i.e., play legislator to the User Police).
First, there are two resources that you can modify which specify all the
minimum and maximum sizes of buttons, check boxes, how far away from the border a
dialog item has to be, the dimensions of small screens, etc., etc. You can change all these
numbers, of course.
The most important feature, however, is that you can add your own
resource-checking code for resource types that are not checked by SoftPolish by
default. Plug-in code modules, state of the art of today’s software technology (by the
way, I’m anxious to see the dynamically linked libraries announced by Apple).
An excerpt from the tech note explains best how the user module mechanism
works:
“When added to SoftPolish, stand-alone code modules can provide extra
functionality for testing custom resources. Each code module must have a resource of
type ‘SPCM’. The name of the ‘SPCM’ resource indicates what resource type the code
module accepts. For example, an ‘SPCM’ resource named “DITL” is, to SoftPolish, a code
module that handles ‘DITL’ resources. If you add a code module for a type SoftPolish
already tests, your code module replaces the internal SoftPolish handling of that
resource type.
Code modules are called by the SoftPolish application which passes the address of
a parameter block. This block contains information the code module must know about
the resource. It also contains mechanisms, or “callbacks”, that call service routines
within SoftPolish. Language Systems supplies header files that define the parameter
block in C, Pascal, and FORTRAN.
The parameter block is divided into three general areas: the header, callback
information, and SoftPolish info. The header contains the handle to the resource to be
tested and other useful reference information. Callback information consists of the
fields a code module uses to request SoftPolish services. In normal use, code modules
should change only the fields in this section. The last area, SoftPolish information,
consists of the fields SoftPolish uses to pass information to the code module.
The general programming style for code modules is to first check which tests are
currently requested and then make the callbacks to perform these tests.”
Pretty clever - a good example of how an extensible application should be
written. For that matter, it is regrettable that not all applications have some extension
mechanism built in.
Fortran news - Absoft
Unfortunately we have a delay between writing an article and its publication. It
is quite short, 6-8 weeks, but sufficient that the activities of dynamic enterprises like
the developers of Fortran for the Macintosh can make our reviews outdated when they
appear. I just received a copy of an E-mail that Absoft sent to my colleague, Alan Hewat:
Tuesday, July 28, 1992
Dr. Hewat:
1: Unfortunately, I cannot help you (today) with AppleEvents. We don't have any
examples ready for release yet. However, the next release of the compiler will include
full AppleEvents capability and include much example code. We haven’t set a release
date yet.
2: You are correct that Absoft does not accept Internet mail through AppleLink. Cost
was not really a factor in the decision; there are easier and more direct ways to reach
us. AppleLink users can send mail to “absoft”; Internet users can contact me directly:
“ldr@absoft.com”.
We haven’t been using the Internet address for Mac tech support until recently; that’s
why it has not been widely publicized. Eventually we will probably replace my
individual address with a more generic “tech support” address.
3: Please express my appreciation to your colleague J. Langowski for pointing out
some shortcomings in our documentation. A review of LS FORTRAN 3.0b (which he
wrote some time ago, but which was only recently published here) incorrectly claimed
that Absoft MacFortran II could not pass the Paranoia accuracy test.
But he cannot be held accountable for the error. After reading his remarks, we
concluded our manual and example code do not adequately discuss the issue of FPU math
versus strict IEEE compliance. We’ve always been able to pass Paranoia, going back to
MacFortran/MPW 1.0; as long as you set the rounding precision of the FPU
appropriately. But we’re going to start documenting more clearly how to do this and
under what conditions it would be necessary.
If you or your colleague have any questions on this or other technical matters, please
feel free to contact me.
Lee David Rimar
Absoft Technical Support
ldr@absoft.com
Thank you very much for these remarks. I thought with the last article that I
wrote the question of accuracy vs. speed in Absoft Fortran was resolved (i.e., when you
give up the speed advantage over LS Fortran, you gain back the accuracy); but I might
still be wrong if there are some other non-documented options to set the rounding
precision of the FPU. I look forward to seeing some newer examples by Absoft, and
e specially the new AppleEvents-aware compiler. You’ll hear about it.
Referenced by (13):