wordstar-launcher

A tool to launch WordStar with DOSBox-X on macOS.

It works with a WordStar 7 archive that was put together by science-fiction writer Robert J. Sawyer. His archive can be downloaded from his blog.

Warnings

This project is unstable, in that I might radically change how everything is structured in the next revision. Updating could be painful.

Use this launcher at your own risk. It works for me, but If you should loose data or whatever don't blame me. Please refer to the LICENCE file.

That being said, If something doesn't work, please raise the issue.

Operation

WordStar documents must be in a particular directory (or one of its subdirectories). On my system I've set this to ~/Documents/WordStar, but you can set it to anywhere.

Double-clicking on a .WS document in the finder will open it with WordStar running in the DOS emulator.

Documents can also be opened from the command line. Use the command wordstar -h for help with that.

Note that WordStar documents must normally reside under the WordStar document directory, regardless of how they are opened.

Version 0.4 adds the ability to open a WordStar document anywhere with the '-a' or '-any' option. This will mount the document's parent directory in DOSBox-X, exposing it both to the emulator and to WordStar. Use this option at your own risk.

Defaults for this option, and other options, can be set by changing the

Installation

Install DOS-Box-X

The DOS-Box-X emulator can be download from its releases page on GitHub. The only version that I've tested is the sdl2 version in the download dosbox-x-macosx-arm64-20240702034526.zip, running on an M1 MacBook Pro. Move the application into your /Applications/ folder.

Download or clone this repository

On my system it lives at ~/Applications/WordStar, which I'll hereon refer to as just WordStar.

Unpack the WordStar archive

Unpacking Robert J. Sawyer's WordStar 7 archive will produce a folder named WS. Put it inside of WordStar/DOS root/.

Install the fonts

Robert J. Sawyer's WordStar 7 archive includes fonts for use with DOS-Box-X. They are mono-spaced .ttf fonts that include code page 437. Use the built-in Font Book application to install any you want to use. The configuration in this repository uses DejaVu Sans.

Delete the key-mapping file (probably)

On my system, I use Karabiner-Elements to remap my caps-lock key to act as the right control key, making the left control key redundant. Out of the box, DOS-Box-X uses F-12 as a modifier key, which it calls "host". In the file WordStar/mapper-dosbox-x.map I have redefined the left control key as this "host" key. If this won't work for your system configuration, delete the file—it's the only modification I've made to the default map.

There are other ways to make the caps-lock key as a control key. One is with a DOS utillity included in Robert J. Sawyer's WordStar 7 archive. I have yet to try it.

Customize the zsh script

Locations of things

Near the head of the script, an associative array is defined that specifies various default settings. These are ones you might have to change:

• c_mount_path should point to WordStar/DOS root
• dosbox_config_path should be WordStar/dosbox-x.conf
• dosbox_path specifies the command to start DOSBox-X. If installed as an application, this should be /Applications/dosbox-x.app/Contents/MacOS/dosbox-x. If you've installed DOSBox-X via homebrew or something, then the command will found be somewhere else.

Fonts

If you've decided on using other fonts, you'll also need to change the following lines with your fonts' names:

  -set 'ttf font=dejavusansmono'
  -set 'ttf fontbold=dejavusansmono-bold'
  -set 'ttf fontital=dejavusansmono-oblique'
  -set 'ttf fontboit=dejavusansmono-boldoblique'

And to resize the font and window, change these lines:

  -set 'ttf ptsize=30'
  -set 'ttf lins=30'
  -set 'ttf cols=96'

I've picked values that work well with my screen, your mileage may vary.

Deleting these seven lines will use the values defined in the configuration file provided by Robert J. Sawyer's WordStar 7 archive, which uses the Iosevka Fixed typeface family.

Put it on your PATH

If you want to conveniently run WordStar on the command line from anywhere, make a symbolic link to the WordStar/wordstar script somewhere on your path. (There are other ways to do this, with trade-offs.)

On my system I put a symbolic link at ~/.local/bin with the command:

ln -is ~/Applications/WordStar/wordstar ~/.local/bin/

Again, YMMV—you might not even have a directory at that location.

Make an application

If you want to open a .WS file with WordStar by default you'll need a default application. One can be made with the built-in app Automator.

1. Create a new document of the type 'Application'.
2. On the leftmost panel, select the Library called 'Utilities'
3. On the list to the right of that, double-click 'Run Shell Script'
4. For the "Shell", select "/bin/sh", and for "Pass Input" select "to stdin".
5. In the textbox, I entered ~/.local/bin/wordstar "$@", because that's the location of my symbolic link. You can also specify the path to the script itself. You must keep the "$@" at the end; that's how the filename of the document to open is specified.
6. Save your application as "WordStar" (or whatever). Its icon can be changed using the Finder. Some icon options are included in the folder WordStar/icons.
7. Set your new application as the default application for .WS files. I did so by right-clicking a .WS file and selecting "Open With > Other…"

Note that this will only work for .WS files located in the folder defined by DOC_ROOT in the BASH script.

---

This project includes the following resources, which may be subject to their own copyrights and licenses.

In the icons directory:

• the .svg file was derived from a WordStar logotype, the code for which was found on seeklogo.com.
• the .png files were converted from .ico files found in the WS folder of Robert J. Sawyer's WordStar 7 Archive.