Add doc/ dir, move docs there.

7 files changed, 336 insertions, 0 deletions

diff --git a/doc/config.txt b/doc/config.txt
new file mode 100644
index 0000000..02c196d
--- /dev/null
+++ b/doc/config.txt
@@ -0,0 +1,22 @@
+Server: irc.whatever.blah
+Port: 6667
+Use SSL? N
+Nick: blah
+Real Name: blah blah
+Channels: #foo #bar #baz
+Background Color: xx
+Text Brightness: xx
+
+Arrows/Enter to select, C to connect
+
+----------------------------------------------------------
+Choose a server
+
+irc.some.server
+irc.some.server
+irc.some.server
+irc.some.server
+irc.some.server
+irc.some.server
+
+Arrows/Enter to select, A to add
diff --git a/doc/ideas.txt b/doc/ideas.txt
new file mode 100644
index 0000000..55b5901
--- /dev/null
+++ b/doc/ideas.txt
@@ -0,0 +1,46 @@
+These are not really TODOs, they're "might do" or "hope to do".
+
+Features that should be implemented:
+
+- Support for (some of) the extra RAM in 64K machines. Can get an
+  extra 4K because we don't need the international font or the
+  floating point routines, and we can plop our custom font directly
+  into $E400. *Maybe* look into using the 800 OS, which would give
+  another 3K (the rest of the $C000 area besides the intl font).
+  This would be a separate executable (fnchatxl.xex).
+
+- Support for 130XE, 256K XL, etc extended RAM. Apparently a lot
+  of people have 1MB these days. *Lots* of screens, each with lots
+  of scrollback, would be the main (only?) use for the extra RAM.
+  Separate executable (fnchatxe.xex).
+
+- Custom cgetc() that doesn't block forever, and does its own
+  keyclick (using POKEY, not the console speaker), so we can
+  disable the click even on an 800. Also maybe we can set the
+  key repeat rate on an 800... and since the clicks are done
+  via POKEY, 800 users can *turn the volume down*. Also since
+  we won't be using WSYNC, it opens up the possibility of
+  using DLIs (if I can think of a useful use for them).
+
+- Keyboard buffer, if possible. Right now we miss the occasional
+  keystroke when typing fast & furious during network I/O. Not
+  sure how to accomplish this with FujiNet (the old FujiChat
+  key buffer actually hooked into the SLIP code).
+
+- Adaptive scrollback (dynamic screen size). Using fewer screens
+  would mean you get more scroll. Shorter screens steal lines from
+  the top of the tallest screen as needed. Requires a display list
+  that's all LMS, and each line needs to be 42 bytes (the extra
+  2 bytes are a pointer to the previous line, or 0 for the top line).
+  Some lines would have to be blacklisted because they'd cross a 4K
+  boundary. As a side effect, scrolling in new text would be *fast*,
+  no need to move memory around, just allocate a new line and change
+  the display list.
+
+- URL handling. Extract URLs from message text, send them to a
+  UDP port on a local machine that knows how to deal with them.
+
+- Some method of copy/paste, using the keyboard or maybe a joystick.
+
+- Cut buffer for ^U ^K ^W, like bash/emacs. LImited size (like,
+  240 bytes, same as the input box).
diff --git a/doc/limitations.txt b/doc/limitations.txt
new file mode 100644
index 0000000..cba6c9f
--- /dev/null
+++ b/doc/limitations.txt
@@ -0,0 +1,35 @@
+Things that won't be implemented:
+
+- Stupidly long nick or channel names. Libera has 24 chars for
+  max nick len, 50 for channels. Any more than that is insane.
+
+- Color. No sane way to do it on the Atari. Color codes will be
+  stripped before messages are displayed. You can *send* color
+  codes (Ctrl-C and numbers) for other clients to see.
+
+- Connecting to multiple IRC servers. While the FujiNet is capable
+  of multiple simultaneous TCP connections, I really don't want to
+  complicate things enough to make this possible.
+
+- Unicode/UTF-8. We're using GR.0 on an Atari, there aren't enough
+  glyphs available to make it worthwhile. Plus, decoding UTF-8
+  would take up a lot of space.
+
+- Support for XEP80 or VBXE, or in general any 80-column hardware.
+  Or software 80 columns, for that matter.
+
+- Extended IRCv3 stuff (tags, capabilities). I *might* try to
+  implement SASL, but it's low on my list of priorities.
+
+- PASS command during registration. If you're an IRCop, you
+  should use a modern full-featured client.
+
+- Log files. SIO bus doesn't have the bandwidth for writing to
+  disk while also doing TCP/IP. I suppose logging to something
+  like a RAMdisk or SIO2IDE (or other non-SIO hard drive) wouldn't
+  be impossible, but doing it right would be a PITA.
+
+- Triggers or scripting. At most, there will be autojoin channels
+  and a (very) few keyboard macros (e.g. you could define a macro
+  that does "/m ChanServ identify <user> <pass>", but you'd have
+  to press a key to send it).
diff --git a/doc/prefs.txt b/doc/prefs.txt
new file mode 100644
index 0000000..165c7a0
--- /dev/null
+++ b/doc/prefs.txt
@@ -0,0 +1,11 @@
+Things that should be prefs in the config:
+
+- Server, port, nick.
+- "Real" name.
+- Use SSL? (default: off...?).
+- Colors
+- Connect macro (to be automatically sent to e.g. log in to ChanServ).
+- Auto-away (default: on).
+- Beep or flash on PM/highlight (default: beep).
+- Closing screen parts channel (default: off).
+- Parting channel with /part closes screen (default: off).
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.
diff --git a/doc/scroll.txt b/doc/scroll.txt
new file mode 100644
index 0000000..2d956d2
--- /dev/null
+++ b/doc/scroll.txt
@@ -0,0 +1,9 @@
+7 screens of 58 lines each (2320 bytes each).
+
+screens start at $8000, end at $bf6f.
+display list goes at $bf70, ~40 bytes.
+status lines (80 bytes) go at ~$bf98.
+
+whoops. the screens can't be contiguous with a standard display list
+due to the 4K boundaries at $9000, $a000, $b000. so we'll need each
+one to have its own 40-byte display list.
diff --git a/doc/window_ui.ideas b/doc/window_ui.ideas
new file mode 100644
index 0000000..789f230
--- /dev/null
+++ b/doc/window_ui.ideas
@@ -0,0 +1,55 @@
+so assume the client can be made small enough to run with RAMTOP
+set to 40K or less...
+
+for windowing to be useful, we have to have at least 4 of them,
+preferably more.
+
+scrollback would be a nice feature. it's a tradeoff of course,
+more scrollback per window = fewer windows.
+
+suppose we can manage to set RAMTOP to 36K ($9000).
+
+we need 1K for a font. for one thing, we want { } ~ ` glyphs (and
+maybe some chunk of latin-1 based on the XL intl set). for another,
+we want the font to be in screen order, so putting $41 in screen RAM
+actually show a capital A, etc. this will speed things up, and also
+allow for nick tab-completion to search backwards through screen
+memory (so we won't have to keep a separate list).
+
+we *don't* need a regular GR.0 screen. all display will be done with
+the windowing UI.
+
+we *do* need a GR.0-like display list, with an LMS for every line.
+probably it'll be 23 lines of channel/query text, and 2 lines for the
+input/status area (and a blank line between them). this will be ~80
+bytes, and the different screens can share it (the LMS addresses get
+updated when switching windows).
+
+a GR0 line is 40 bytes. we have, say, 12200 bytes. that's 300 lines.
+the inputbox is shared between all the windows. that gives us 13
+23-line screens, if we don't do scrollback. if we allocate 60 lines
+per screen (23 of which are visible at any given time), that gives us
+5 scrollable windows. not really enough of them: one for each channel
+or query, and one "everything else" (server messages and PMs that
+aren't queries).
+
+if it's 50 lines per window, we get 6 of them.
+
+how about they aren't all the same height?
+
+the 'everything else' window and the primary channel can have more lines.
+say, they get 59 lines each, and we have 4 more windows at 46 lines.
+that puts us a bit over (12080 bytes) but I think it's doable. that still
+only gives us 6 windows though. not worth doing.
+
+what about a non-scrollable server window, then 6 46-line scrollable
+windows, one of which is "msgs" (all non-query PMs). that gets us 5
+channel/query windows, plus the msgs window will be more convenient
+than having the msgs mixed with server text.
+
+what if we want 8 windows? they'd only be 37 lines each (not even a
+whole screen of scrollback).
+
+maybe we can scrunch the client down so it fits under 32K... maybe
+that can include the font too, so we have 16K for window lines. that
+would give us 8 51-line windows or 7 58-line ones.