Extract and improve documentation

.editorconfig

@@ -0,0 +1,14 @@
+root = true
+
+[doc/*.adoc]
+end_of_line = lf
+max_line_length = 76
+insert_final_newline = true
+trim_trailing_whitespace = true
+charset = utf-8
+
+[*.hs]
+indent_size = 2
+indent_style = space
+tab_width = 8
+

doc/README.md

@@ -0,0 +1,7 @@
+# glirc Documentation
+
+For auto-generated Haddock documentation, see `docs`.
+
+The command documentation is written in a subset of AsciiDoc,
+and is added back into glirc at compile time.
+Please consult `#glirc` on Libera.Chat before modifying it.

doc/cmds_chanop.adoc

@@ -0,0 +1,67 @@
+= Channel Management Commands
+:toc:
+
+== /invite
+
+Invite a user to the current channel.
+
+== /kick
+
+Kick a user from the current channel.
+
+See also: kickban, remove
+
+== /kickban
+
+Ban and kick a user from the current channel.
+
+Users are banned by hostname match.
+
+See also: kick, remove
+
+== /masks
+
+Show mask lists for current channel.
+
+The `mode` argument is typically one of the following:
+
+`b`: bans +
+`i`: invite exemptions (op view only) +
+`e`: ban exemptions (op view only) +
+`q`: quiets (on Charybdis/Solanum-based networks)
+
+== /mode
+
+Set IRC modes.
+
+When executed in a channel window, mode changes are applied to the channel.
+When executed in a network window, mode changes are applied to your user.
+
+This command has parameter sensitive tab-completion.
+
+See also: masks, channelinfo
+
+=== Examples
+
+`+/mode -t+`               - Remove the topic lock +
+`+/mode +b *!*@hostname+`  - Set a ban +
+`+/mode -q *!*@hostname+`  - Remove a quiet +
+`+/mode +vv user1 user2+`  - Voice two users +
+`+/mode +v-o user1 user1+` - Demote an op to voice
+
+== /remove
+
+Remove a user from the current channel.
+
+Remove works like /kick except it results in a PART.
+
+Not all servers support removal in this manner.
+Refer to your server/network's documentation.
+
+See also: kick, kickban
+
+== /topic
+
+View or set the topic of the current channel.
+
+Tab-completion with no `message` specified will load the current topic.

doc/cmds_chat.adoc

@@ -0,0 +1,203 @@
+= Chat Commands
+:toc:
+
+== /join
+
+Join the given channels.
+
+Multiple channels and keys may be provided as comma-separated lists.
+
+When keys are provided, they should occur in the same order as the channels.
+
+=== Examples
+
+`+/join #friends+` +
+`+/join #secret thekey+` +
+`+/join #secret1,#secret2,#public key1,key2+`
+
+See also: channel, clear, part
+
+== /me
+
+Sends an action message to the currently focused channel.
+Most clients will render these messages prefixed with
+only your nickname as though describing an action.
+
+=== Examples
+
+`+/me shrugs+`
+
+See also: notice, msg, say
+
+== /msg
+
+Send a chat message to a user or a channel.
+
+Multiple targets may be provided as a comma-separated list.
+
+On servers with STATUSMSG support,
+the channel name can be prefixed with a sigil to
+restrict the recipients to those with the given mode.
+
+=== Examples
+
+`+/msg buddy I'm sending you a message.+` +
+`+/msg #friends This message is for the whole channel.+` +
+`+/msg him,her I'm chatting with two people.+` +
+`+/msg @#users This message is only for ops!+`
+
+See also: notice, me, say
+
+== /part
+
+Leave the currently-focused channel,
+optionally with the provided message.
+
+=== Examples
+
+`+/part+` +
+`+/part It's not me, it's you+`
+
+See also: clear, join, quit
+
+== /query
+
+Switch the client focus to the given
+target and optionally send a message to that target.
+
+See also: msg, channel, focus
+
+=== Examples
+
+`+/q libera:#haskell+` +
+`+/q #haskell+` +
+`+/q lambdabot @messages+` +
+`+/q irc_friend How are you?+`
+
+== /say
+
+Send a message to the current chat window.
+
+This can be useful for sending a chat message with
+a leading '/' to the current chat window.
+
+=== Examples
+
+`+/say /help is the right place to start!+`
+
+See also: notice, me, msg
+
+== /away
+
+Mark yourself as away.
+The away message is used by the server to update
+status in /whois and to provide automated responses.
+
+Omit the `message` parameter to clear your away status.
+
+=== Examples
+
+`+/away Out getting some sun+` +
+`+/away+`
+
+== /channelinfo
+
+Show information about the current channel.
+Information includes topic, creation time, URL, and modes.
+
+See also: masks, mode, topic, users
+
+== /ctcp
+
+Client-to-client protocol (CTCP) commands can be used
+to query information from another user's client application
+directly. Common CTCP commands include: ACTION, PING, VERSION,
+USERINFO, CLIENTINFO, and TIME.
+
+glirc does not automatically respond to CTCP commands.
+
+=== Parameters
+
+`target`    - Comma-separated list of nicknames and channels +
+`command`   - CTCP command name +
+`arguments` - CTCP command arguments
+
+=== Examples
+
+`+/ctcp myfriend VERSION+` +
+`+/ctcp myfriend TIME+`
+
+== /knock
+
+Request entry to an invite-only channel.
+
+== /monitor
+
+Monitor is a protocol for getting server-side notifications
+when users become online/offline.
+
+=== Subcommands
+
+`+/monitor + target[,target2]*+` - Add nicknames to monitor list +
+`+/monitor - target[,target2]*+` - Remove nicknames to monitor list +
+`+/monitor C+`                   - Clear monitor list +
+`+/monitor L+`                   - Show monitor list +
+`+/monitor S+`                   - Show status of nicknames on monitor list
+
+== /names
+
+Show the user list for the current channel.
+Detailed view (default key F2) shows full hostmask.
+
+See also: channelinfo, masks
+
+== /nick
+
+Change your nickname.
+
+=== Examples
+
+`+/nick guest123+` +
+`+/nick better_nick+`
+
+== /notice
+
+Send a chat notice to a user or a channel.
+
+Notice messages were originally intended to be used by bots.
+Different clients will render these in different ways.
+
+Multiple targets may be provided as a comma-separated list.
+
+On servers with STATUSMSG support,
+the channel name can be prefixed with a sigil to
+restrict the recipients to those with the given mode.
+
+=== Examples
+
+`+/notice buddy I'm sending you a notice.+` +
+`+/notice #friends This notice is for the whole channel.+` +
+`+/notice him,her I'm informing two people.+` +
+`+/notice @#users This notice is only for ops!+`
+
+See also: me, msg, say
+
+== /operwall
+
+Send a network-wide WALLOPS message to opers only.
+
+See also: me, msg, say
+
+== /wallops
+
+Send a network-wide WALLOPS message.
+These messages go out to users who have the 'w' usermode set.
+
+See also: me, msg, say
+
+== /quote
+
+Send a raw IRC command.
+
+The argument to this command is sent as-is.
+No additional word-splitting is done.

doc/cmds_client.adoc

@@ -0,0 +1,88 @@
+= Client Commands
+:toc:
+
+== /exit
+
+Exit the client immediately.
+
+== /reload
+
+Reload the client configuration file.
+
+If `filename` is provided it will be used to reload.
+Otherwise the previously loaded configuration file will be reloaded.
+
+== /extension
+
+Run a command provided by an extension.
+
+`extension` should be the name of a loaded extension with
+a process_command callback.
+
+== /palette
+
+Show the current palette settings and a color chart to help pick new colors.
+
+== /digraphs
+
+Show the table of digraphs. A digraph is a pair of characters
+that can be used together to represent an uncommon character.
+Type the two-character digraph corresponding to the desired
+output character and then press M-k (default binding).
+
+The digraphs list is searchable with `+/grep+`.
+
+See also: grep
+
+== /keymap
+
+Show the key binding map.
+
+Key bindings can be changed in configuration file.
+Run `+glirc --config-format+` for details.
+
+== /rtsstats
+
+Show the GHC RTS statistics.
+
+== /exec
+
+Execute a command synchnonously, optionally sending the output to IRC.
+
+Arguments to this command are:
+`+[-n[network]] [-c[channel]] [-i input] command [arguments...]+`
+
+`input` is sent to the standard input of the command.
+
+When neither `network` nor `channel` are specified,
+output goes to client window (focus name "*").
+When `network` is specified,
+output is sent as raw IRC traffic to the network.
+When `channel` is specified,
+output is sent as chat to the given channel on the current network.
+When `network` and `channel` are specified,
+output is sent as chat to the given channel on the given network.
+
+`arguments` is split on spaces into words before being
+processed by getopt. Use Haskell string literal syntax to
+create arguments with escaped characters and spaces inside.
+
+== /url
+
+Open a URL seen in chat.
+
+The URL is opened using the executable configured under `url-opener`.
+
+When this command is active in the textbox,
+chat messages are filtered to only show ones with URLs.
+
+When `number` is omitted it defaults to 1.
+The number selects the URL to open, counting back from the most recent.
+
+== /help
+
+Show command documentation.
+
+When `command` is omitted, a list of all commands and macros is shown.
+When `command` is specified, detailed help for that command is shown.
+