todo item for !summon

[ircbot] / helpinfos

::wwwtitle	Blight (chiark IRC bot) help
::wwwaddress	chiark IRC operators <ircop@chiark>

:
See http://www.chiark.greenend.org.uk/ucgi/~ijackson/blight-help
or /msg me with `help !overview'.

:overview
General commands:           Registration and user settings:
 !help [<cmd>|<opt>|<topic>]  !register [insecure|delete]
 !seen <nick>                 !set [<opt> [<value>]]      who [<nick>]
 !summon <username>           (See `help !identify', `help !blight-id')
 !invite [<chan>] <nick>...  Channel settings (see `help channel'):
 !op [<chan>]                 !channel [<chan>] <setting> [....]
 !leave [<chan>]             Additional help topics:
 !ping [<stuff ...>]          !identify !identpass !invite !blight-id
 !kill <nick> [<reason>]
Send commands to me by /msg, or say them in channel with \! in front.
To get me on a channel, invite me.  To become channel manager, op me.

:help
help             gives an overview and lists the topics &c
help <command>   gives help on a command
help <opt>       gives help on an option
help <topic>     gives help on an additional topic

:seen
seen <nick>
 Tells you or the channel when I last saw that nick in
 use.  When the nick is next used, I'll tell them you asked.

:summon
summon <username>
 Invites a logged-on user onto IRC.  If the user is not logged on
 you'll be told.  Target users can change this (eg, to disable it)
 by reconfiguring the userv service `irc-summon'.  See ~ian/.userv.

:who
who [<nick>]
 Gives information about who I think the nick is (or who I think you
 are), including whether the nick is registered, whether it is
 associated with a username and if so who, and whether the current
 user of the nick has identified themselves to me.
 See `help !register'.

#:convert
#convert <number> <unit>
# Converts the specified quantity into SI units.  Units that are
# understood are any understood by units(1) and also
#   kelvin celsius fahrenheit    (convert to celsius or kelvin)
#(Not yet implemented.)

:op
op [<channel>]     on channel
op <channel>       (privately)
 I'll give you channel operator privilege, if you're a manager.
 See `help !manager'.

:leave
leave [<channel>]     on channel
leave <channel>       (privately)
 I'll leave the channel, if you're a manager.  For an unmanaged
 channel, I'll leave when I'm the last one on the channel.

:channel
channel [<chan>] [show]                       show settings
channel [<chan>] !manager +|-|= <nick> ...     set manager list
channel [<chan>] !autojoin yes|no              join at bot start ?
channel [<chan>] !userinvite pub|here|all|none who can !invite ?
channel [<chan>] !mode *|+...-...              set modes when alone
channel [<chan>] !topic leave | set <topic>    set topic when alone?
channel [<chan>] !topic see|tell +|-|= <chan>|* ...
 See `help <setting>' (eg, `help manager') for more info.

:topic
channel [<chan>] topic set <topic>    set topic when alone
channel [<chan>] topic leave          don't (default)
 If set to `topic set <topic>' then whenever I'm alone in the channel
 I'll reset the topic; if se to `topic leave' I'll leave it alone.
channel [<chan>] topic see|tell +|-|= <chan>|* ...
 I can inform one channel about topic changes in another.  Each
 channel has a `see list' and a `tell list' which may be empty or
 contain some channel names and/or a `*'.  I'll tell channel #spy
 whenever I see the topic change in #showoff if: #showoff or * is
 mentioned in #spy's see list, and #spy or * is mentioned in
 #showoff's tell list, and at least one those mentions is not a `*'.
 + adds items to the relevant list, - removes them, and = sets the
 list to exactly those items specified.  Both lists are empty by
 default, but a good permissive value is just `*' for both lists.

:autojoin
!channel [<chan>] autojoin yes|no      (`yes' is the default.)
 Controls whether I'll join the channel when I'm (re)started.

:userinvite
channel [<chan>] userinvite pub    users on chan can \!invite
channel [<chan>] userinvite here   users on chan can \!invite and /msg
channel [<chan>] userinvite all    anyone can \!invite and /msg
channel [<chan>] userinvite none   \!invite and /msg are disabled
 Controls whether the `invite' command works for this channel, and
 who can use it (`help !invite').  `userinvite pub' is the default.
 Channel managers can always use the `invite' command.

:mode
!channel [<chan>] mode *|+...-...           (`mode *' is default.)
 If not set to `*' then whenever I'm alone in the channel I'll set
 and unset the channel modes specified.  Only the modes imnpst are
 supported.  Precede one or more mode letters with + to set, - to
 unset; any letters not mentioned will be left alone.

:manager
!channel [<chan>] manager + <nick> <nick> ...  add managers
!channel [<chan>] manager - <nick> <nick> ...  remove managers
!channel [<chan>] manager = <nick> <nick> ...  set new manager list
 Managers are those who can use the `channel' command to change
 channel settings.  Manager status is only effective for secure
 nicks, after the manager has identified themselves.
 If you op me on an unmanaged channel you become the only manager,
 but you must use `!channel' to change a channel setting to make this
 permanent.  To make a channel unmanaged, make it have no managers.

:identify
You must identify yourself to change your settings if your nick is
secure, and to use channel management commands.  In ircII on chiark,
just say `/!blight-id'.  For other clients, see `help !identpass'.
Once you are identified you can then register new nicks, change
settings, etc. - so long as you remain on a channel that I'm on too
(see `help !invite').  See also `help !register'.

:blight-id
/blight-id is a command available in ircII (and possibly other
clients) on chiark.  It sets up a password if you don't already have
one, and then uses it to identify you to Blight.  If you want to
change your password, delete the file ~/.userv/irc-pass-md5.
See `help !register' and `help !identpass'.

:identpass
identpass <username> <password>
 Identifies you to Blight.  To set up your password, or be reminded
 of it, run the shell command `irc-blight-id' on chiark.
 (On ircII on chiark `/!blight-id' is easier, see `help !blight-id'.)
 See `help !identpass-internals' for technical details.

:identpass-internals
Identification, for example with /!blight-id, is actually done with
`!identpass', which feeds the md5sum of the password to `userv
<username> irc-identpass <nick>'.  That must exit 0 if all is well.
By default this checks the md5sum against ~/.userv/irc-pass-md5.

:invite
invite <nick> ...             on channel
invite <channel> <nick> ...   privately
 This command gets me to invite the specified people to the channel.
 This can be disabled for managed channels - see `help !userinvite'.
To get me to join a channel, just invite me to it.

:kill
kill <nick> [<reason>]
 Asks me to throw that client off IRC completely, using my IRC
 Operator privilege.  You must have identified yourself as the user
 to whom the nick is registered.  (See `help !register'.)

:register
register            register your nick (or make it secure)
register delete     delete your nick registration
register insecure   register your nick insecurely
 I only store settings for registered nicks.  For `insecure' nicks
 anyone who currently holds that nick can change its settings (see
 `help !set', including securing it to their username.  `secure'
 nicks can only have their settings changed by the user to which they
 are registered, after identifying themselves (see `help !identify').

:set
set                  show your current settings
set <option>         show the current setting of <option>
set <option> <value> set <option> to <value>
 Options:  !timeformat ks|hms|beat
           !marktime off|once|<n>[k]s|<n>m|<n>h
 See also `help <option>', `help !register' and `help !identify'

:timeformat
!set timeformat ks    show times in seconds, kiloseconds, etc.
set timeformat hms   use days, hours, minutes, seconds
set timeformat beat  use beats (1000 B = 1 day)

:ping
ping [<string>]
Replies with hopefully-useful information, including:
* Current time, number of IRC and system users, and load averages.
* Most recent traffic on a relevant channel (if sent privately, any
  channel we're both on, otherwise the channel in question.)  Only
  actual message traffic counts, and \!-commands don't count either.
* The specified string, if any.
I can tell you this automatically if you like - see `help !marktime'.

:marktime
!set marktime off    Only an explicit `!ping' command sends you info.
set marktime once   Send ping info shortly after I first see you.
set marktime <n>s   Also send info every <n> seconds (min 300s).
set marktime <n>ks  Also send info every <n> kiloseconds (min 1ks).
set marktime <n>m   Also send info every <n> minutes (min 5m).
set marktime <n>h   Also send info every <n> hours (min 1h).

# Local variables:
# fill-column: 69
# End: