Psion Word file conversion for macOS and Linux

Latest Release: 0.4.0

 New Version

About word2text

Psion Word allows you to enter styled text on Psion palmtops. Back in the Series 3 palmtop’s heyday—the mid to late 1990s—Psion provided Windows software that converted Psion Word files to Microsoft Word. A separate DOS utility, wrd2txt could also convert transferred files to plain text. This latter was the inspiration for word2text, which I wrote to perform exactly the same task, but on a modern macOS or Linux machine.

I write either in plain text or, when I require formatting, Markdown. Psion Word, created long before Markdown’s conception, doesn’t support it, but both types of text file can be created in Word and transferred to a Mac. Word embeds the plain text in a document that also includes a host of file, formatting and printing related data. word2text strips all that away, applying the formatting information only when Markdown output is requested.

Back to the Top

Markdown

word2text can use Word files’ styling information to mark up the processed text with Markdown formatting tags. This is necessarily limited: Word has only two standard headline sizes, and the only emphasis options relevant to Markdown are bold and/or italic text. Where these apply, word2text will mark up the text accordingly. Text styled as a Word Bulleted List entry will be tagged as a Markdown unordered list.

Styles added to Word conversions from Markdown, as outlined below, will be converted back to their Markdown equivalents upon re-conversion.

For custom styles, word2text will apply bold and/or italic emphasis where it can. For custom headlines, word2text will apply a Markdown headline size based on the style’s font size.

In due course, I hope to support table formatting from Word tables and ultimately to more intelligently parse custom Word styles.

Back to the Top

Conversion to Psion Word

word2text can convert a Markdown file to Word format for transfer to a device and/or emulator. Currently, the level of Markdown parsing is limited to the following formatting markers:

 
All other formatting is ignored and content is passed through as plain Body Text (Psion Word style BT). Fenced code blocks are passed through line by line with no inline processing; thematic breaks are dropped. Inline code within backticks is placed within single quotes.

Back to the Top

Character Set Shenanigans

The Psion Series 3a uses the IBM Code Page 850 character set. This was used in the DOS days and was superseded first by Windows Code Page 1252 and ultimately UTF-8. 850 and 1252 are not exactly the same, and though Swift can convert from 1252 to UTF-8, it doesn’t speak 850. And compiled on Linux, the conversion code has issues with 1252 too, I have found.

word2text converts the UK pound sign £ from 850 value 156 to 1252’s 163. At some point, I may extend this to the full set of matchable characters. If you have a character that is not being correctly converted (word2text should report characters that have issues), please let me know.

Back to the Top

CLI Usage

Use word2text to convert into plain text any Psion Word documents that you have transferred to your Mac. Provide a .WRD file name as an argument and word2text will output a plain text version to a file of the same name but with the .txt extension. For example:

1

word2text $HOME/Psion/MAGOPUS.WRD

If you include the --stdout flag, word2text will output the processed text to stdout so it can be piped into tools.

You can also pass a directory name (or a mix of file names and directories), in which case each .WRD file in the directory will be converted to a text file in that directory. Again, files generated this way are named after the source file.

1
2

word2text $HOME/Psion
word2text $HOME/Psion $HOME/Desktop/MY_DOC.WRD

For convenience, files are written using UTF-8 encoding.

To convert a Word file to Markdown, include the -m or --markdown flag.

To convert a Markdown or plain text file to Word, include the -r or --reverse flag. Files will gain the same name as the source, but with the .wrd extension. Existing .wrd files will not be overwritten. To do so, use the --force flag.

word2text accepts the following modifiers:

• -m/--markdown—Output the body text in Markdown formatting rather than plain text. Default: false.
• -r/--reverse—Output Markdown/text files to Psion Word files. Default: false.
• -o/--outer—Include ‘outer’ content, i.e., header and footer text, in addition to the body text. Default: false.
• -f/--force—Overwrite an existing file. Default: false.
• -stdout—Output generated Markdown/text (not .wrd) to stdout. Default: false.
• -s/--stop—Stop processing multiple files on the first error. Default: false.
• -v/--verbose—Show file and content discovery information during file processing.

For example:

1
2
3

word2text $HOME/Psion/BIDDRAFT.WRD --stdout
Bid headline
Bid text to go here...

1
2
3
4
5
6
7

word2text $HOME/Psion/BIDDRAFT.WRD --outer --stdout
%F-%D:%T
********
Bid headline
Bid text to go here...
*******
Page %P

1
2
3

word2text $HOME/Psion/BIDDRAFT.WRD --markdown --stdout
# Bid headline
Bid text **to go here**...

1
2
3
4
5
6
7

word2text $HOME/Psion/BIDDRAFT.WRD -mo --stdout
%F-%D:%T
********
# Bid headline
Bid text **to go here**...
********
Page %P

Back to the Top

Library Usage

You can import the repo’s code as a library to make use of the conversion code in your own macOS app. This mode uses Swift Package Manager (SPM). On Linux, SPM is used to build the CLI executable and so cannot yet be used as the basis for library mode.

Add the Swift package to your project in Xcode in the usual way, then add import Word2text to your code. For example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

import Cocoa
import Word2text

@main
class AppDelegate: NSObject, NSApplicationDelegate {

    @IBOutlet var window: NSWindow!
    @IBOutlet var textViewInWindow: NSTextView!

    func applicationDidFinishLaunching(_ aNotification: Notification) {

        do {
            let wordFilePath = "/path/to/Psion/Word/file"
            let data = try Data(contentsOf: URL(filePath: wordFilePath))
            let settings: ProcessSettings = [.doReturnMarkdown]
            let result = PsionWord.processFile(data, settings, wordFilePath)

            switch result {
                case .failure(let error):
                    textViewInWindow.string = error.localizedDescription
                case .success(let processedText):
                    textViewInWindow.string = processedText
            }
        } catch {
            textViewInWindow.string = "File load error"
        }
    }

}

Settings

You can adjust the handling of the Psion Word file by adding parameters to the ProcessSettings instance. By default, no options are selected. The options are:

• doShowinfo — Issue logging messages during processing.
• doIncludeHeaders — Include Word document headers and footers in the processed output.
• doReturnMarkdown — Return the processed text in Markdown format rather than plain text (the default).

As the example above shows, options are added by inserting them into an empty ProcessSettings array:

1

let settings: ProcessSettings = [.doShowInfo, .doReturnMarkdown]

or, alternatively:

1
2
3

var settings: ProcessSettings = []
settings.insert(.doShowInfo)
settings.insert(.doReturnMarkdown)

Logging

In library mode, log messages and warnings are posted via the default notification centre. The names used are ProcessNotification.log and ProcessNotification.warning.

For example, add these lines to the start of the applicationDidFinishLaunching() function shown above:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

let nc: NotificationCenter = NotificationCenter.default
nc.addObserver(self,
               selector: #selector(self.printLog(_:)),
               name: ProcessNotification.log,
               object: nil)

nc.addObserver(self,
               selector: #selector(self.printLog(_:)),
               name: ProcessNotification.warning,
               object: nil)

And add this method to the AppDelegate class:

1
2
3
4
5
6

@objc
func printLog(_ note: Notification) {

    let message = note.object as! String
    print(message)
}

Back to the Top

Source Code

You can view Word2text’s source code at GitHub.

Back to the Top

Related Software

• Depot
• dlist
• imageprep
• pdfmaker
• utitool

Back to the Top