gistfile1.txt

Welcome to WordGrinder

Important note for Windows users

WordGrinder is a port of a Unix program, and a few things don’t map well onto the way Windows works. There are some things you need to know.

• the mouse is ignored. WordGrinder is keyboard driven.
• the close button at the top right hand corner of the window won’t work. Instead, to quit, type CTRL+Q (or press ESC to open the menu and pick File_→_Quit).
• by clicking on the icon at the top-left corner of the window you can change the font (the default one is pretty ugly; I recommend Consolas) and switch in and out of full-screen mode.

There’s more information on using WordGrinder with Windows further down in this file.

Introduction

WordGrinder is a word processor for processing words.

WordGrinder is not WYSIWYG. It is not point and click. It is not a desktop publisher. It is not a text editor. It is not do fonts and it barely does styles.

What it does do is words. It’s designed for writing text. It gets out of your way and lets you type.

Survival Guide

All your favourite navigation keys should work. Just type and it should do the right thing.

Important things you need to know:

• pressing ESC opens the menu. Press ESC again or CTRL+C to close it. (Pressing CTRL+C will cancel most things in WordGrinder.)
• inside a menu, navigate with the cursor keys and RETURN or just press the highlighted letter.
• a key combination displayed to the right of a menu item is a shortcut that will invoke that item directly. These can all be changed; see the section on menu customisation below.
• all navigation controls are defined in the Navigation menu. Forget which key combination goes to the beginning of the line? Just look there.
• if no menu is open, pressing ALT+letter will open the specified submenu directly, bypassing the main menu. e.g. to open a file, just type ALT+F, O.
• typing CTRL+G will open this document’s table of contents.

You can load and save files using the File menu. A Document Set is a file on disk. Each file can contain multiple Documents. Pay careful attention to whether WordGrinder is talking about Documents or Document Sets. There’s more information below.

Some operations (applying character styles, cut and paste) require you to select text. To do this, move to one end of the area to mark; press CTRL+SPACE; move to the other end. The operation will be applied to the highlighted text between the mark and the cursor. Note that the marks are always placed on the left side of the cursor. Pressing CTRL+SPACE again will remove the marks.

That’s it. Now you can work WordGrinder.

Styles

Character styles

WordGrinder supports the following character styles:

• Italicised text
• Underlined text
• Bold text
• And any combinations of the above

That’s all. To apply them, select some text and then use Style_→_Italic (CTRL+I) or Style_→_Underline (CTRL+B) to apply. To remove styles, use Style_→_Plain (CTRL+O). When you type type new text, it will always appear unstyled (even if in the middle of a styled word).

Tip: to type a new word in a particular character style, make sure nothing’s selected, press CTRL+I, CTRL+B or CTRL+U to toggle the insertion state (look down at the right hand side of the status bar), and then type.

Paragraph styles

WordGrinder supports a number of paragraph styles. See Style_→_Paragraph Styles (CTRL+P) for the list. Each style applies to a complete paragraph. If you want to see what style each paragraph has set, use Style_→_Set Margin Mode_→_Show Paragraph Styles. The style names will be displayed in the left-hand margin.

Paragraph styles are not currently customisable, but they may become so in the future.

The RAW paragraph style is interesting as it allows you to embed arbitrary chunks of data into your document which, when exported, are emitted intact into the output file. I use this to insert HTML into documents I’m writing.

Documents and Document Sets

Each WordGrinder file can contain multiple pieces of text. A file is referred to as a Document Set; each piece of text within the Document Set is a Document.

You can have as many documents in a document set as you like (within reason). You can manage them using the File_→_Manage Documents... menu item, and can quickly see and switch between documents using the Documents menu (ESC, D).

Documents have their own text, selection, viewing style, cursor position, etc. The clipboard, however, is shared across the entire document set. This allows you to move pieces of text around within the document set using the clipboard.

Importing non-WordGrinder files always results in a new document being added to the current document set.

Menu customisation

You can change any of the keyboard shortcuts assigned to menu items. These are then saved as part of the document set, so each WordGrinder file takes its keyboard configuration with it.

To do this, open the menu, navigate to the entry you want to change, and then press CTRL+V followed by the key you want to bind. You can’t bind the text entry keys. You also can’t bind a key that’s already in use elsewhere. You can remove a binding by navigating to the appropriate menu item and pressing CTRL+X. You have to manually remove a binding from a menu item before you can bind a different key to it. Watch the status bar while a menu’s open for reminders.

All WordGrinder keybindings (except ESC, and menu and dialogue navigation) appear on the menus, so they’re all configurable. Things like the cursor keys appear in the Navigation menu.

If you get irrecoverably confused, you can reset all the keybindings by opening a menu and doing CTRL+R.

Note: WordGrinder’s keyboard support is at the mercy of which keys your platform supports, and this can vary wildly from platform to platform. For example, on some platforms that use ncurses it doesn’t seem possible to bind CTRL+arrow keys. In addition, some platforms have keys that I don’t know about. WordGrinder will support these, but they’ll be labelled as UNKNOWN_1234 or similar. If this happens to you, please get in touch so I can make it display a sensible name.

Importing

If you don’t want to write a document from scratch in WordGrinder, it’s possible to import documents in a small number of other formats using File_→_Import new document. These all add a new document to the existing document set, rather than replacing the current one. The followng formats are available:

• Plain text
• Imports flat encoded plain text with no character or paragraph styles. Paragraphs are delimited by newlines.
• Files must be UTF-8. Be aware that Windows notepad and friends don’t save in UTF-8 by default. If you import a file which isn’t UTF-8 you’ll probably get gibberish.
• OpenDocument
• Imports basic content from ODT files. OpenDocument is complicated and hard to parse but WordGrinder will do its best to apply appropriate styles. Unsupported features are ignored.
• HTML
• Imports ‘tag soup’ UTF-8 encoded HTML. All unknown tags are ignored. (or ), and are mapped to italic, underline and bold, respectively;

  ..

  become paragraph styles H1 to H4; all

  become LB. Paragraphs are delimited by either

  or
  .

Exporting

Once you’re done with your document, you can export it to a small but growing variety of other formats using the File_→_Export current document menu option. The following formats are available:

• Plain text
• This produces a simple, flat UTF-8 text file. Character and paragraph styles are lost, but all your text remains. Paragraphs are delimited by newlines, so you end up with one very long line per paragraph.
• OpenDocument
• This produces an ODT file which can be read by LibreOffice and a variety of other major word processors. Character and paragraph styles are exported and are mapped to OpenDocument styles called P, H1, H2 etc.
• Note that you can’t losslessly convert a WordGrinder document to OpenDocument and back again.
• HTML
• This generates a very basic UTF-8 encoded HTML document, nominally HTML 4. Practically everything will read this. Character and paragraph styles are exported. There are some customisation options in the File_→_Settings_→_HTML export dialogue; I use these when writing program documentation to cause underlined text appear as .
• LaTeX
• This generates a UTF-8 LaTeX document suitable for running through XeTeX using the ‘xelatex’ command. You can use stock LaTeX if you wish, but you will need to edit the file to remove the xunicode package --- any non-ASCII characters probably won’t work correctly. Character and paragraph styles are supported; H1..H4 are mapped to \section, \subsection, \subsubsection and \paragraph respectively.
• Note that even when using XeTeX, TeX’s Unicode support is currently rather poor, and that which characters are supported depends strongly on what font you’re using: read the Unicode section below. You’ll probably need to edit the output file to set an appropriate font or set of fonts.
• Troff
• This generates an ASCII Troff file suitable for use with the ms macro package. Character and paragraph styles are supported; exporting to troff and then running the result through nroff is a good way of getting a formatted plain text version of a document.
• Non-ASCII characters are encoded using the [char1234] mechanism, which means that if you’re lucky enough to have a version of groff modern enough to handle proper Unicode, it should all work. If you don’t, then characters in the ISO-8859-1 range will probably work, and all others will be ignored. (I don’t use the [u1234] idiom because this causes groff 1.18.1 to crash horribly when exporting this document. Blame the groff team; they’ve been promising real UTF-8 for years now.)
• Unfortunately the troff format has some limitations which means that switching from one character style to another sometimes involves inserting a space. Please get in touch if you know how to get around this.

Manually configuring WordGrinder

All WordGrinder configuration optiosn are automatically saved with your document set. All of them. Menu bindings, settings, etc; you can change them through the user interface and they’ll be saved into the file and reloaded later.

However, there is also a mechanism for allowing these settings to be overridden. I use this to have different keybindings on machines with different keyboards. It is currently very clunky and under development, and so may change without notice.

To use, run this command:

wordgrinder --help

This will show the command line options, and at the bottom will tell you where your configuration file lives. Open this in a (non-Wordgrinder) text editor.

Now run:

wordgrinder --lua "ListMenuItems()"

WordGrinder will display all the menu items it knows about, plus their menu ID. You can now enter lines like this in your configuration file:

OverrideKey("^Z", "ZM")

OverrideKey("F1", "D1")

OverrideKey("F2", "D2")

...where the first item is the key to override, and the second is the menu ID over the thing you want to happen when the key is pressed.

These settings override any document set settings, but they are not saved with the document set --- if you load the document set into an instance of WordGrinder which doesn’t have that configuration file available, the standard keybindings apply. The settings are not shown in the menus and rebinding menu items will not affect them.

Some global settings use variables. Change these with:

X11_FONT = "comic sans"

This whole area needs some work. We apologise for the inconvenience.

Platforms

WordGrinder can be used on several platforms.

Unix terminal

WordGrinder will run in a terminal on practically any Unix platform with a modern curses library; I use Linux with ncurses.

Underlined text is displayed underlined. Italicised text will be displayed in italics if you have a curses which is new enough, if your terminal supports italics, and if WordGrinder can figure out that your terminal supports italics; otherwise it will be displayed highlighted. Bold text... is also display highlighted. Sorry. That’s the best ncurses can do.

ncurses’ keyboard support is hugely variant on what terminal you’re using, and some terminals don’t support things like SHIFT+UP/DOWN, CTRL+arrows, SHIFT+function keys, etc. In addition, ncurses enforces a one second delay when responding to the ESCAPE key. This is really annoying, but can be avoided by using ALT+letter instead.

You will also need a decent terminal emulator with Unicode support. I use xfce4-terminal with the Terminus font.

Unix X11

There is also a specific version of WordGrinder which will run natively on X. You get antialiased fonts, configurable colours, underline, bold and italicised text being displayed natively as underline, bold and italics, and most key combinations work (including SHIFT+CTRL+cursor keys).

Unicode support is not so great as font substitution is not done, so you’re at the mercy of whatever glyphs your font supports. If Unicode is important to you, use a font like Unifont which good Unicode coverage.

Configuration is done by setting values in your configuration file (which is not very user friendly; sorry). See the section above on manually configuring WordGrinder. Set the following variables:

• X11_FONT: name of the font to use. WordGrinder uses Xft names. The default is “monospace”. Italic and bold versions are selected automatically, which might not work on some fonts (this isn’t WordGrinder’s fault).
• X11_BLACK_COLOUR: background colour. Any X11 colour name will work. The default is “#000000”.
• X11_DIM_COLOUR: colour used for unimportant UI elements. The default is “#555555”.
• X11_NORMAL_COLOUR: colour used for ordinary text. The default is “#888888”.
• X11_BRIGHT_COLOUR: colour used for highlighted text. The default is “#ffffff”.

Apple OS X

The Unix build of WordGrinder will run happily on OS X, in a Terminal window, behaving exactly like any other Unix system.

For best use it’s recommended that you turn on the ‘Use Option as meta key’ setting in Terminal (it’s in Preferences->Keyboard). This will let you use ALT+letter to open menus. Without it you have to use ESC. Personally I think that the Homebrew or Pro themes for Terminal look best with WordGrinder, although you’ll most likely need to increase the font size.

Fullscreen mode works very well.

Windows

WordGrinder will also run as a Window application. Some menu options have been added to the titlebar menu (single click on the icon on the top-left corner of the screen) to allow you to change the font and toggle full-screen mode on and off; this last may also be done with ALT+ENTER (note that this is not rebindable).

Underline, bold and italics are displayed as underline, bold and italics.

The Windows version provides good keyboard support and most key combinations are supported.

WordGrinder will do its best to display Unicode characters. If the font you choose does not contain a particular glyph, WordGrinder will attempt to find a glyph from the closest matching font. Unfortunately this works quite badly with bitmap fonts, resulting in quite ugly results, but it does work.

I strongly suggest installing a decent TrueType Unicode monospaced font. Consolas is good and is supplied by default on most Windows systems, but I like DejaVu Sans Mono:

http://dejavu.sourceforge.net/wiki/index.php/Download

Neat features

Table of contents

In a document containing structured content (like this one), you can use Edit_→_Goto to bring up a dialogue showing an outline of the document and which allows you to jump quickly to any heading in it.

Undo

WordGrinder will remember every change you make, up to a limit of about 500. Use CTRL+Z to undo, and then CTRL+Y to redo an undone change. You can only use redo if you haven’t made any changes in the mean time, as usual.

The undo stack is not saved along with your document --- the undo stack always starts as empty when a document is loaded. (Because otherwise the files get stupidly big, and very slow to load and save.)

Autosave

WordGrinder also has a feature that will save a timestamped snapshot of your document set periodically. This is disabled by default; to enable this, go to File_→_Settings_→_Autosave. You can specify how long between snapshots and what filename pattern you want WordGrinder to use.

Note that autosaving will only happen if you don’t touch the keyboard for a few seconds, to prevent a dialogue box from being popped up just as you’re about to press a key. Autosaving will also only happen if your document set contains unsaved changes. (In this situation, autosaving does not count as saving your changes, and your document set will remain dirty.)

Unicode

WordGrinder supports ＵＮＩＣＯＤＥ!

(If you see a bunch of boxes in the above line, it means that your platform doesn’t support displaying exotic Unicode characters. WordGrinder will still let you edit them, you just won’t be able to see what you’re doing.)

Mostly, at any rate. Combining characters and right-to-left are unsupported. This means that you can use, say, Français, русский язык, 한국어 and 日本語, but you can’t use Arabic or Hebrew because they end up mangled (العربية and עברית respectively). You can use line art but that’s not what WordGrinder’s for and it’ll probably work badly.

Unfortunately, how to actually enter Unicode characters is entirely up to your operating system and your terminal application. WordGrinder can’t help you there.

This document set contains a Unicode test document containing a rather more strenuous workout than the above paragraph; see the Documents menu.

Scrapbook

The Edit_→_Scrapbook provides various options to allow you to quickly copy fragments of document to a scrapbook document. Fragments get appended onto the end of the scrapbook with an optional timestamp; this is configurable in File_→_Settings_→_Scrapbook. (The scrapbook itself is just another document; you can even copy things to the scrapbook while viewing it, but it probably won’t behave the way you want!)

Page count

For some applications it’s important to know --- roughly --- how many pages you’ve written, rather than how many words. WordGrinder doesn’t know what pages are, but there’s a feature to allow you to show you a rough estimate as to how many pages you’ve got based on the number of words. See File_→_Settings_→_Page Count.

Widescreen mode

Running WordGrinder full screen on a widescreen monitor is typically pretty uncomfortable, as you end up with very long lines. Widescreen mode allows you to restrict the text to a column in the centre of the screen. (Dialogue boxes are not affected.) See File_→_Settings_→_Widescreen mode. I find that 80 or 100 columns is the most comfortable.

Smart quotes

WordGrinder supports smart quotation marks, “like this” or ‘like this’. To turn on, see File_→_Settings_→_Smart quotes. It’ll convert them when you type, or when you paste into your document. To bulk convert text, simply copy it into the clipboard and paste it back again. You can change the characters used for quotation marks (which is useful if, e.g. «you’re French»).

Command line

There are some WordGrinder features which can be used from the command line, both on Unix and Windows. Firstly, it’s completely scriptable in Lua: write a file in Lua, then run WordGrinder with wordgrinder --lua filename.lua and it’ll run and then exit. Or use wordgrinder --lua "lua command". Nearly all of WordGrinder is written in Lua and it’s all available via this interface. The API is, unfortunately, beyond the scope of this document; if you’re interested, ask the author (or look at the source code).

Secondly, the file .wordgrinder.lua in your home directory will be automatically loaded and run whenever WordGrinder starts; see the section above on configuring WordGrinder for information.

Thirdly, you can use WordGrinder to automatically convert between any supported document formats. For example:

wordgrinder --convert sourcefile.wg destfile.odt

...will convert the default document in sourcefile.wg to OpenDocument format.

See wordgrinder --help for more information.

When Things Go Wrong

Is WordGrinder behaving funny? Did it just crash?

If so, please get in touch. Software shouldn’t crash, and if you tell me about it, I will fix it so it won’t. (Probably.)

When reporting bugs, it will make my life considerably easier if you can (a) duplicate the bug, and (b) show me the stack trace produced by the debug version of WordGrinder. (Windows users should get in touch and I’ll send you a copy of the debug version, and show you how to get at the stack trace.) Without these, I’m afraid there’s not a lot I can do.

David Given

[email protected]