Add doc/ dir, move docs there.

1 files changed, 158 insertions, 0 deletions

diff --git a/doc/screens.txt b/doc/screens.txt
new file mode 100644
index 0000000..fc11c68
--- /dev/null
+++ b/doc/screens.txt
@@ -0,0 +1,158 @@
+You get 7 screens (for now at least), with a total of 48 40-column
+lines per screen (again, for now). These screens work a bit like the
+screens in GNU screen, or tmux, or the windows in terminal mode IRC
+clients like irssi.
+
+Each screen normally shows the bottom 23 lines, plus either the input
+box or the status lines as the bottom 2 lines. When you "scroll up" to
+see the top 25 lines, all 25 of them show, and you don't see the input
+box or status lines at all. For now, you can only scroll up once (more
+memory will be needed for more scrollback).
+
+The screens are numbered 1 to 7. Screens 1 and 2 always exist, and are
+always called [server] and [private], respectively. Other screens are
+created as needed, by the /join or /query commands.
+
+Screen 1, the server screen, is really a "catch-all" screen: it will
+display all IRC protocol messages that aren't specific to a channel.
+It will also act as the "overflow" area when you join more channels
+than you have screens available, or if you use /j1 or /join1 to join a
+channel without creating a screen.
+
+Screen 2, the private screen, will display private messages and
+notices [TODO: not notices yet] directed to you, specifically (your
+nick). Only private messages from nicks that don't have a query screen
+will appear here (see below). To respond to these messages, use "/m
+nick response".
+
+The remaining screens, 3 to 7, can each be used for either a channel
+or a query.
+
+A "query" is a private message conversation between you and one other
+user, initiated with the /query command. Trying to issue a /query when
+no unused screens are available will fail. Unlike clients like irssi,
+query screens won't automatically be created when someone messages
+you. They have to manually be created with /query. This is because
+there are so few screens available.
+
+Channel screens are created by the /join command (or its alias /j).
+The screen is created as soon as you issue the /join command,
+and anything referencing the channel will show up in that screen,
+including error replies like "banned from channel" or "channel
+is invite-only". Channel screens are only deleted when you delete
+them explicitly, with Start + Escape.
+
+Creating a screen with /join or /query switches to that screen
+immediately. You can press Start+Tab to get back to where you were.
+
+If you want to join a channel without creating a screen (so its text
+appears in the [server] screen), use "/j1" or "/join1". To send text
+to the channel, you'll have to use "/m #channel text". [At some
+point, there will be tab-completion for channels, so this won't
+be so annoying]
+
+Leaving a channel via /part or being kicked out, doesn't delete the
+channel screen! Also, if the join fails (e.g. because the channel is
+invite-only, or you've been banned), the screen still gets created.
+Trying to enter text into a screen after leaving its channel will
+give you a "Cannot send to nick/channel" error.
+
+[TODO: not working yet] If you do part or get kicked, you can issue
+"/j" or "/join" (with no channel name) from the (former) channel's
+screen to rejoin that channel in that screen.
+
+Deleting a channel screen doesn't exit (part) the channel, either.
+That channel's messages will now appear in screen 1, [server].
+
+If you're in a channel that doesn't have its own screen (it's showing
+up in [server]), you can "/query ##channel" to move it to its own
+screen (provided you have an unused screen for it).
+
+Status lines:
+
+When not entering text, and not scrolled up, there are two status
+lines at the bottom of the screen. The top one (in GRAPHICS 0) shows
+the name of the current screen (channel, query nick, [server], or
+[private]). The bottom status line (in GRAPHICS 1 [TODO: not yet])
+shows the status of all the screens, in color:
+
+- Text background color (green by default, change with /color) is used
+  for screens that are open, but have no activity since they were last
+  displayed (nothing new to see there).
+
+- Yellow is used for channel screens that have new text you haven't
+  yet seen, but your name hasn't been mentioned (you haven't
+  been "highlighted").
+
+- Red is used for query screens that have new text you haven't seen
+  yet, and for channel screens with new text where someone has
+  mentioned your name (you have been "highlighted").
+
+[TODO: the /color command only takes 1 or 2 arguments right now]
+The /color command can take up to 4 numeric (decimal) values, which
+set the color registers for the text background, text foreground,
+non-highlighted channels, and queries or highlighted channels, in that
+order. Example:
+
+/color 0 8 99 200
+
+...will set the background to black, the text to medium grey,
+un-highlighted channels to purple, and queries + highlighted channels
+to medium green. There is no way to change the border color; it's
+always 0 (black). As usual on the Atari, only the luminance of the
+text color is used.
+
+If you give fewer than 4 numbers, the remaining color registers are
+not changed. If you give *no* numbers, the colors are reset to the
+built-in defaults.
+
+Beware: there's no error checking. Non-numbers will be treated as
+zero values, and there's nothing to prevent you setting the text
+foreground and background to the same luminance (which makes the
+text invisible). If this happens, you can blindly type /color with no
+arguments to restore the default color set.
+
+Hotkeys:
+
+Hold down Start and press:
+
+Number 1 to 7: switch to screen, by number. Screens that are
+empty/unused (never been used, or closed via Start+Escape) can't be
+switched to.
+
+Escape: Close the current screen, and switches to the [server] screen
+(1). Has no effect if used in screens 1 or 2. Closing a channel's
+screen with Escape does not exit the channel; the channel's text will
+be seen in the [server] screen.
+
+[TODO] Ctrl+Escape: Close the current screen and exit (part)
+the screen's channel, if any. There's no confirmation, but
+Start+Ctrl+Escape is difficult to press by accident.
+
+Left/Right arrows: switch to previous/next screen (wraps around from 1
+to 7, or 7 to 1). Again, empty/unused screens will be skipped. You
+don't have to hold Control with the arrow keys.
+
+A: Switch to lowest-numbered "active" screen. An active screen is
+one that has new text in it that you haven't seen yet. Does nothing
+if there are no active screens.
+
+Tab: Switch back to the last screen you were looking at. Can be used
+repeatedly to toggle between 2 screens.
+
+S: Show status. Hides the input box (but does not clear its contents).
+The input box will reappear when you start typing again.
+
+[TODO] J: Join a channel you were invited to. This is only the most recent
+invite (there's no history). Does nothing if you haven't received
+an invite, or if you're already in that channel. The join is done as
+/join (creates a screen, if it can).
+
+[TODO] Q: In the [server] screen, create a channel window for the channel you
+most recently got a message from. In the [private] screen, creates
+a query window for the user you most recently got a private message
+from. Does nothing if there are no empty screens, or if used from a
+screen other than [server] or [private].
+
+[TODO] L: List all existing screens (numbers and channels/nicks). Output goes
+to the currently displayed window.