Some notes and hints

Herein are notes regarding installation and running of webify, obtaining Ghostscript, troubleshooting common problems, Macintosh-specific issues, Windows-specific issues, bugs, and a summary of recent changes.

Installing Webify

Webify runs only on UNIX systems, although it should be a fairly simple port to other platforms supporting Ghostscript.

Obtaining Ghostscript

LATE FLASH: The recommended gs version is 3.33. Earlier versions, including the Gnu 2.6.2 version, are reputed to work as well (despite incompatibilites with previous versions of webify). The Aladdin version 3.51 has other problems (see below); a recent version 3.53 hasn't yet been tried.

Ghostscript version 2.6.2 is distributed under the GNU copyleft terms and is available at prep.ai.mit.edu; you might grab fonts too.

A newer, fancier, and somewhat buggier version is distributed by Aladdin under different terms; poke around ftp://ftp.cs.wisc.edu:/pub/ghost/aladdin/ and you'll find version 3.33 along with fonts, fixes, and information. This version seems to work fine with webify.
At this writing, Aladdin's current distribution is version 3.51. A number of users have noticed that this version rasterizes fonts poorly, generating muddled-looking (but readable) output. You can see what the difference is by clicking here.

NOTE: Earlier Webify versions generated gif images, using a postcript prependage to crop and rotate the images. Gif images are no longer supported in current supported in current gs versions, and the postscript hacks failed to work with postscript files from certain sources and with the Aladin gs versions. For this reason, Webify version 2 uses gs to generate .ppm files, and postprocessors to crop/rotate and convert to JPEG or GIF formats. The additional complexity is that webify users must install, in addition to webify, hackppm and either/both of cjpeg or ppmtogif. Pity, but hopefully myriad problems with the earlier version will be avoided.

Running Webify

To get summary help on webify, type the command "webify" with no arguments. You'll get something like this.

Before using webify to convert a postscript file, you'll probably want to customize a template for your own use. Edit webify.template; start with minor changes (like changing my name and email address -- at the bottom of the file -- to your own). If you know HTML and have a strong intuition, you'll immediately see how to make substantive changes; otherwise, you may want to make your changes more incrementally. Very little has to be changed to make the sample template useful for a wide variety of purposes.

To run webify on a UNIX system, type the command

       webify <options> template file.ps
which will read specified template file as well as the postscript file.ps, and generate a subdirectory ("named "file") containing a tree of web pages whose root is named "index.html".

Template is a text file containing skeletal HTML, as well as escape sequences enclosed in curly brackets {...}. Click here to see a typical template (the one which generated the sample webify presentation). <options> allow various parameters to be specified in the command line rather than via escapes in the template; this allows a single template to be used for a variety of applications. For a summary of available options, invoke webify with no arguments as described above.

Troubleshooting: Hints for common problems

Following are some problems which webify users have reported:
Image Quality:
For unknown reasons, gs version 3.51 generates PPM files which are somewhat muddled looking. Use gs version 3.33 until Aladin fixes this problem.

Hangs forever:
If webify hangs forever, it is probably waiting for gs to finish. GS may have returned an error (which webify doesn't understand), or it may itself be hanging. You can tell by running ps, and (perhaps) by looking at gs.out.

General advice: try running gs on your postscript file directly and checking for errors.

If your your images aren't oriented properly, try the -r1 or -r3 options (assuming you DON'T have a {rotate ...} escape in your template). If you can't get the orientation right, check your version of hackppm ("hackppm -h").

Some users have reported that webify produces inverted color slides -- -- white letters on black background -- under some circumstances. Version 2.1 of hackppm reinterprets P4-format input data to address what I expect is the source of the problem; but the -v input to webify is provided as a safety net. If your images are inverted, add -v to the webify command line and see if that fixes the problem.

Some users have had problems getting stale versions of cjpeg or ppmtogif or hackppm after compiling new versions. This can be due to former versions of these programs which remain on the search path. When you replace an auxilliary program, either replace it in its search path location or give the appropriate webify argument to access the new version.

Basic Troubleshooting:
If your slides/thumbnails don't look as you expect them to, try running gs directly on your postscript file (via something like "gs slides.ps"). You can view the output on your screen and decide whether your postscript file means the right thing to gs.

Advanced Troubleshooting:
If gs produces proper output, run webify with the -d and -F flags, preferably on a shortened version of your postscript presentation. This will preserve ppm files and show you all the commands webify is invoking. You can use a utility like xv to view the ppm files, and try running hackppm and cjpeg manually to pin down where the process is screwing up your images.

Postscript from Macintosh applications

Generation of postscript from the Macintosh is easy using the Laserwriter 8 driver (currently version 8.3; 8.1.1 and earlier are extremely buggy). Select file output from the print dialog, include all fonts (to be safe), and write the postscript file somewhere for convenient transport to the UNIX system running webify.

Idiosyncrasy: The Mac driver inherits some parameters from the selected printer, even when producing postscript files rather than hard copy. For certain printers, the postscript -- hence the gif images -- are upside down. This can be accommodated via the -r command line option to webify, or via the {rotate n} directive in the template file.

Postscript from Windows applications

Due to a fairly serious dose of Mac bigotry during the past several years, I'm not competent to provide much advice here (despite numerous inquiries). Contributions from Windows-savvy users are welcome.

Between the likelihood of Apple's demise, the frustrating rate of Mac crashes, and the growing irrelevence of the NuBus (a link to circa 1980 nostalgia) my Mac loyalty is likely to finally give way.... when this happens, I may actually have some intelligent advice for this section.

Known Bugs

Change log

Recent changes include:

Thanks to all the users who conveyed bug reports, suggestions, improvements, and encouragement.

Steve Ward ... ward@mit.edu