BITTERS MANUAL
Behold the manual! This disk describes what bitters is, and how
you might use it. It's packed with information. Some useful, some
maybe less? No, just kidding, how could any of that information
be useful! Before we dive in, let's start by paying some due
credits.
##################################################################
CREDITS
Bitters is not much more than a reproduction of the word
processing abilities of the Canon Cat. All the ideas have been
pioneered by Jef Rasking and the team that worked on the Canon
Cat project. I'm in awe to see the attention to details the whole
team had on every aspect the Cat.
This manual itself has been inspired by the Canon Cat's Reference
Manual that's available online. The Cat's manual is much more
exhaustive and a definite read I'd suggest you to go through
after you're done reading this one. As a matter of fact, I'm
adding URLs to Cat documentation at the end of this manual.
You've been warned!
Of course, it's hard to learn the details of a machine when we
can't fiddle with it. The Internet Archive has an emulator of the
Cat that has been incredibly helpful.
A little note on the font used: I've used the font_8x16 from the
Linux kernel. It's provided under the GPL 2.0 license.
Most of the work done on this project should also be attributed
to my local coffee roaster. Let's be honest, the coffee she sells
should absolutely take credit for what's been done here!
##################################################################
A LITTLE INTRODUCTION
What is bitters? Why is it called that way? How does it work? So
many questions, and hopefully many more are currently floating in
your brain. And don't get me started on brain. That should be the
subject of another document.
So you're here, reading this manual. Congratulations! Out of all
the different activities the modern world provides us, you chose
to read this manual. Let me tell you this: you chose well. You
are about to hop on a journey that started in the late 80s, a
point in time where many innovation started. I, myself, was born
in the late 80s. I was too young to appreciate all the machines
and ideas and paradigms that were invented back then. But here I
am today!
Bitters is a word processor that's inspired by the Canon Cat. The
Cat is a machine that's been released in 1987 by Jef Raskin, who
worked on the Macintosh project at Apple before that. The Cat's
approach to what tech should be is vastly different from what
computers are today. Instead of being a machine that allows
everyone to do everything, the Cat had a much more utilitarian
view. A computer should be an inexpensive tool that allows
everyone to work with words.
While the Cat wasn't a commercial success, it is PACKED with
incredible ideas. Bitters only implements a fraction of them. But
this little fraction makes writing so enjoyable that it's worth,
in my opinion, exploring them.
##################################################################
INSTALLING
In order to install bitters, you need to have a C compiler and
the SDL2 library installed. Compile directly from the source
using the provided 'build.sh' script.
##################################################################
KEYBOARD
Your interface to writing with bitters is your keyboard, as I'm
sure you have guessed! Bitters only supports standard ANSI QWERTY
keyboards. If you are using an other type of keyboard, the
modifiers key will be mapped to the ones of the QWERTY keyboard.
In addition to that, bitters only allows characters that are part
of the ASCII table, meaning that it's currently not possible to
write accents, for example.
Bitters uses special keys to work with text. In this manual, I'll
be mentioning them enclosed in [].
-----------------------------------------------------------------
KEY MAPPING
ALT is used for leaping. Control is used as the "use front"
modifier, which changes the behavior of some keys.
[<- LEAP]: Left ALT
[LEAP ->]: Right ALT
[USE FRONT]: Control
[ERASE]: Backspace
[PAGE]: PageDown
[DOCUMENT]: [SHIFT] + [PAGE]
Pressing [USE FRONT] allows you to access other keys:
[LEAP AGAIN]: [USE FRONT] + [LEAP]
[PASTE]: [USE FRONT] + "p"
[DISK]: [USE FRONT] + "l" (ell)
Some keys are available only when the text is highlighted. The
commands carried by these keys operate directly on the selection.
[COPY]: "c"
[CENTER]: "="
##################################################################
DISK
In the Canon Cat, you'd insert a floppy disk in the machine and
directly start typing. There were no file system, no OS. Just
disks you'd write your text on. A lot like you'd have paper in a
typewriter.
On bitters, disks are files that contain all your writing. They
aren't actual, real floppy disks like on the Cat. Just files.
They are named disks because they serve a similar purpose and
philosophy: they store all your documents.
While the norm is to have many different files with their own
names, on bitters you'd have one disk with all your documents.
This allows you to quickly lookup information using LEAP.
On bitters, a disk can store up to 250 KB of text. After that,
the disk becomes full and you are not able to write in it
anymore. This 250 KB limit is similar to the one of the Canon Cat.
By convention, name your disks with the '.bit' extension. Disks
are simple text files and contain no other information than the
text you've written in them.
To start bitters, you need to pass it the path of a disk. If the
disk doesn't exist, bitters will create a new one for you.
-----------------------------------------------------------------
SAVING YOUR WORK
When you have unsaved changes on a disk, a * character should
appear on the bottom line of the editor. To write the changes to
the disk, use the [DISK] (CTRL + 'l' (ell)) key. Once saved, the
* character disappear, indicating that your work has been
successfully recorded.
##################################################################
DOCUMENTS AND PAGES
As we've just seen in the previous section (DISKS), there's no
files in bitters, just disks which are a place where you can have
documents. What you are reading right now, this whole document,
is a disk. And as I'm sure you've noticed there are different
sections. This section for example talks about DOCUMENTS and
PAGES. It's separated from its neighbors with a very special
character. The DOCUMENT character. It's a normal character, just
like the 'o' or the 'i'. It's octal ASCII code is . Because
it's a normal character, you can LEAP to it. But hey, we haven't
covered LEAPing yet!
Here's what to remember: DOCUMENTS should describe standalone
parts of your disks. If we take the analogy of a file system:
your disk is the folder, and the DOCUMENTS are its files.
A PAGE is another character. Its octal code (not that you need to
know about it, really) is . Since it's a character, you can
also LEAP to it. A Page is a way to subdivide your DOCUMENTS. If
DOCUMENTS can be viewed as files, PAGES are subsections of those
files.
To type a PAGE character, press PageDown. To type a DOCUMENT
character, press [SHIFT] + [PAGE].
##################################################################
THE CURSOR AND THE HIGHLIGHT
The way the Cat and bitters handle the cursor is a little
different than what we tend to see. Instead of having a single
like that shows where the next character will be inserted, there
are two visual cues:
- The cursor: the dotted rectangle that always shows you where
your next character is going to be inserted.
- The highlight: the filled rectangle that preceeds the cursor.
It shows the character that would be removed if you pressed the
[ERASE] key.
When the cursor and the higlight are on different character, we
say that the cursor is wide. When they are both on the same
character, we say that the cursor is narrow.
When you press [ERASE] on a wide cursor, it will erase backward.
When you press [ERASE] on a narrow cursor, it will erase forward.
When we LEAP, the cursor automatically becomes narrow. But what's
leaping exactly?!
##################################################################
LEAPING
Leaping is the heart and soul of the Cat, and also of bitters.
Without it, it'd be pretty dull to write with... So what's
leaping? It's a way to "jump" (leap) to any character in the
disk. Instead of using arrow keys or your mouse to get to a place
in your document, you would just leap to that location directly.
LEAP is a great way to edit parts of your text, but also to
browse your disk, or to look up information.
-----------------------------------------------------------------
LEAP PATTERN
You can leap forward ([LEAP ->]) or backward ([<- LEAP]) from
your current location. To do it, press one of the LEAP keys and
start typing the pattern. A pattern can go up to 10 characters.
It describes the sequence of letters to target.
The target is the first letter of the sequence, that's where your
cursor will land. Once it lands on the target, the cursor becomes
narrow: [ERASE] will erase forward.
Any character can be part of your LEAP pattern. That includes the
DOCUMENT and PAGE character, as well as the RETURN character.
-----------------------------------------------------------------
LEAP AGAIN
Once you've leaped onto a target, you can ask bitters to LEAP to
the next available target. That's done using the [LEAP AGAIN]
key. To activate it, press [USE FRONT] and press either [<- LEAP]
or [LEAP ->].
Note that [LEAP AGAIN] auto-repeats. Just keep your fingers on
the key and bitters will jump around on all available targets.
This makes [LEAP AGAIN] a great tool to browse your disk! Just
press [LEAP ->] [RETURN] [RETURN] [LEAP AGAIN] to scroll your
disk forward. Use [<- LEAP] instead to scroll backward.
-----------------------------------------------------------------
CIRCULAR SEARCH
When you LEAP too far in one direction, the search for the
pattern will hit either the begining or end of the disk. When
that happens, the search picks up from the opposite direction.
This is called the "circular search".
-----------------------------------------------------------------
CURSOR REBOUND
So what happens when you LEAP to a pattern that isn't found on
the disk? The cursor gets back to its original position. It's
called the "cursor rebound". It's a great way to lookup for
information! Just LEAP to a pattern you'd like to check on, then
press "xx" (or any random string) to get back to where you were.
-----------------------------------------------------------------
CREEPING
There are no arrow keys on bitters or the Cat. Instead, you have
your good old LEAP keys. If you press one of the LEAP keys and
immediatly release it, it will move forward or backward one
character, and narrow the cursor. This is called "creeping", and
its helpful to adjust the target after a leap.
Of course, you want to limit the use of creeping as much as
possible and instead train on using LEAP to land on the correct
target!
-----------------------------------------------------------------
UPPERCASE AND LOWERCASE MATCHING
When the LEAP pattern contains a lowercase character, it will try
to match it with both lowercase AND uppercase targets. So if your
pattern is "hello", it will match with both "hello" and "HELLO".
However if your pattern is uppercase, only uppercase target will
match.
##################################################################
HIGHLIGHTING
Highlighting is the process of selecting text to do things with
it. You can ERASE it, CENTER it, COPY it or MOVE it. To highlight
a part of your text, position yourself to one side of your
selection. LEAP to the other side of the text you'd like to
highlight, and press both LEAP keys. There you go!
-----------------------------------------------------------------
ERASE
You can erase your selection by pressing the [ERASE] key.
-----------------------------------------------------------------
CENTER
If your selection fits on a single line, you can center it by
pressing the [CENTER] key. It will pad it with spaces.
-----------------------------------------------------------------
COPY
By pressing the [COPY] key, your selection goes into your
system's clipboard and is available anywhere. Note that you can
paste the text you have copied anywhere on your disk by pressing
the [PASTE] key.
-----------------------------------------------------------------
MOVE
When your text is highlighted, you can move it to another
location by LEAPING to the new location. As soon as you release
the LEAP key, the text will be moved there. To cancel the move
when you have started LEAPING, use the CURSOR REBOUND (by typing
"xx" or any other random pattern).
##################################################################
TAB AND TABSTOP
When you press the [TAB] key, Bitters will insert a horizontal
tab character ( ). This character will expand until it reaches
the next tabstop. By default, there is a tabstop every 8
characters, but this can be changed. More on that in the next
section!
TAB is a great for tabular data, or for indenting lists. As any
character, it's possible to LEAP to it, however many systems
already use the ALT-TAB key binding.
##################################################################
CONFIGURATION FILE
You can pass the path of a configuration file as the second
argument when you run bitter. The configuration file allows you
to change default values and colors. Each line should be the name
of an option followed by an '=' and the value. Every line that
starts with a '#' won't be read, and can be used for comments.
Below are the different options:
OPTION DEFINITION
-----------------------------------------------------------------
TAB_STOP Tab characters will be halted at every multiple
of this number. Defaults to 8.
ROWS The number of visible rows for editing text. This
will change the height of the window. Defaults to
23.
COLR_BG A hex number representing the color of the
background. Defaults to 0.
COLR_TXT A hex number representing the color of the text.
Defaults to ffffff.
-----------------------------------------------------------------
Note: Don't use the '#' when defining a COLR_* option. Simply
write the hex value without it.
##################################################################
BITTERS STYLE
This section of the manual describes a simple style convention
for writing with bitters. Feel free to use it for your own
writing, or don't! As long as you stay consistent, you will be
happy. And isn't being happy why we use bitters in the first
place?
- Name your disk with the '.bit' extension.
- DOCUMENTs should be standalone sections in your disk.
PAGEs should be used as sub-headings withing your
DOCUMENTs.
- The first DOCUMENT of your disk should describe its
content. Its title should be the title of the disk. It
should be centered horizontally to make it standout from
other titles. Below the title should be a description of
the disk.
- Add a title to your DOCUMENTs and PAGEs. The title should
be inserted after the DOCUMENT or PAGE character. Finish
every title with two RETURN.
- Finish every paragraph with two RETURN.
- Indent lists with one TAB, and finish every list item by
a period (".") followed by two RETURN.
-----------------------------------------------------------------
GOING FURTHER
The above convention should be a good balance between simplicity
and practicalness. If you write a lot with bitters and edit text
often, you can add those few rules to make working with LEAP
easier.
- Capitalize your titles. LEAP to a title using SHIFT.
- Start your sentences with two spaces. LEAP to the start of a
sentence by typing LEAP followed by SPACE and SPACE.
##################################################################
BITTERS TIPS
Below are some tips, methods and best practices to use bitters.
You will for sure discover tips yourself! When you do, feel free
to email them to me so I can add them.
-----------------------------------------------------------------
LOOKUP INFORMATION
Having all your DOCUMENTS on the same disk comes with a huge
benefit: you can lookup any piece of information from anywhere!
Here's how you'd do that:
[LEAP] to the pattern you'd like to lookup. Once you've gotten
the information you need, get back to where you were by adding
"xx" to the pattern, thus causing the cursor to rebound.
-----------------------------------------------------------------
LEAP SENTENCE-TO-SENTENCE
Since sentences are separated by a "." (period), LEAP to "." to
get to the next sentences.
[LEAP] [.] [LEAP AGAIN]
-----------------------------------------------------------------
LEAP PARAGRAPH-TO-PARAGRAPH
If you follow the BITTERS STYLE (and I hope you do!) then all
your paragraphs are separated by the [RETURN] keys. Use the
following pattern:
[LEAP] [RETURN] [RETURN] [LEAP AGAIN]
This pattern is a great way to browse the content of a disk. Keep
in mind that the [LEAP AGAIN] key auto-repeats, which makes it
more convinent to scroll.
-----------------------------------------------------------------
LEAP TO NEXT PAGE OR DOCUMENT
Since PAGE and DOCUMENT are on the same key, you can LEAP to a
PAGE to match both PAGEs and DOCUMENTs.
-----------------------------------------------------------------
RETURN TO PREVIOUS POSITION AFTER LEAPING
I find this one especially useful! Anytime to leap somewhere to
edit a part of the text, you can get back to where you were by
doing the following:
Highlight the text with [LEAP ->] [<- LEAP] then CREEP to the
side you'd like to go.
-----------------------------------------------------------------
MOVE A PARAGRAPH
Highlight from the RETURN before the start of the paragraph to
the one after the end. Leap to the line you'd like the selection
to go.
-----------------------------------------------------------------
MOVE A SENTENCE
Highlight from the first letter of the sentence (or the space, if
it follows a period) up to the finishing period. Leap to the
place you'd like the selection to go to.
##################################################################
GOING FURTHER
I hope you've enjoyed reading this manual and that you've learned
a thing on two! Practice makes perfect, and the best you can do
is to apply your knowledge: go ahead and start writing! After a
little bit, you'll even forget about bitters and only care about
what you write. That's the place you want to be in.
There's great documentation of the Canon Cat, and I highly
recommend giving them a look. You can find it on www.canoncat.net.
~~
QUESTIONS? COMMENTS?
Let me know! You can contact me at m15o at posteo dot net
Thanks for reading!