From c9d40e7c81f57172baf8d8c31c7be4b1fbd8f5b3 Mon Sep 17 00:00:00 2001 From: Griatch Date: Mon, 10 May 2021 23:28:41 +0200 Subject: [PATCH] Expand channel help entry --- docs/source/Components/Channels.md | 17 ++- .../api/evennia.comms.channelhandler.rst | 7 - docs/source/api/evennia.comms.rst | 1 - docs/source/api/evennia.help.rst | 2 + docs/source/toc.md | 2 +- evennia/commands/default/comms.py | 127 +++++++++++++++--- evennia/commands/default/help.py | 2 +- 7 files changed, 120 insertions(+), 38 deletions(-) delete mode 100644 docs/source/api/evennia.comms.channelhandler.rst diff --git a/docs/source/Components/Channels.md b/docs/source/Components/Channels.md index 1438448eb7..6447b80993 100644 --- a/docs/source/Components/Channels.md +++ b/docs/source/Components/Channels.md @@ -8,9 +8,8 @@ connected to a channel, sending a message to it will automatically distribute it to every other subscriber. Channels can be used both for chats between [Accounts](./Accounts) and between -[Objects](./Objects) (usually Characters) and (in principle) a mix of the two. -Chats could be both OOC (out-of-character) or IC (in-charcter) in nature. Some -examples: +[Objects](./Objects) (usually Characters). Chats could be both OOC +(out-of-character) or IC (in-charcter) in nature. Some examples: - A support channel for contacting staff (OOC) - A general chat for discussing anything and foster community (OOC) @@ -105,9 +104,10 @@ But you can also use your alias with the `channel` command: > alias + argument onto calling the `channel` command. So when you enter `foo hello`, > what the server sees is actually `channel foo = hello`. The system is also > clever enough to know that whenever you search for channels, your channel-nicks -> should first be considered. +> should also be considered so as to convert your input to an existing channel name. -You can check if you missed something by viewing the channel's scrollback with +You can check if you missed channel conversations by viewing the channel's +scrollback with channel/history public @@ -144,14 +144,13 @@ You can give a comma-separated list of channels to kick the same user from all those channels at once. The user will be unsubbed from the channel and all their aliases will be wiped. But they can still rejoin if they like. - channel/ban mychannel = annoyinguser123 : spammed too much + channel/ban mychannel = annoyinguser123 channel/ban - view bans channel/unban mychannel = annoyinguser123 -The optional reason at the end shows in the banlist Banning adds the user to the channels blacklist. This means they will not be -able to rejoin if you boot them. You will need to run `channel/boot` to -actually kick them. +able to _rejoin_ if you boot them. You will need to run `channel/boot` to +actually kick them out. See the [Channel command](api:evennia.commands.default.comms.CmdChannel) api docs (and in-game help) for more details. diff --git a/docs/source/api/evennia.comms.channelhandler.rst b/docs/source/api/evennia.comms.channelhandler.rst deleted file mode 100644 index 0d0561cef3..0000000000 --- a/docs/source/api/evennia.comms.channelhandler.rst +++ /dev/null @@ -1,7 +0,0 @@ -evennia.comms.channelhandler -=================================== - -.. automodule:: evennia.comms.channelhandler - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/api/evennia.comms.rst b/docs/source/api/evennia.comms.rst index df024da752..0ae919dbd3 100644 --- a/docs/source/api/evennia.comms.rst +++ b/docs/source/api/evennia.comms.rst @@ -12,7 +12,6 @@ evennia.comms :maxdepth: 6 evennia.comms.admin - evennia.comms.channelhandler evennia.comms.comms evennia.comms.managers evennia.comms.models diff --git a/docs/source/api/evennia.help.rst b/docs/source/api/evennia.help.rst index cc9b4ac68c..6c737f8390 100644 --- a/docs/source/api/evennia.help.rst +++ b/docs/source/api/evennia.help.rst @@ -12,5 +12,7 @@ evennia.help :maxdepth: 6 evennia.help.admin + evennia.help.filehelp evennia.help.manager evennia.help.models + evennia.help.utils diff --git a/docs/source/toc.md b/docs/source/toc.md index c713a94026..0fd3b361b4 100644 --- a/docs/source/toc.md +++ b/docs/source/toc.md @@ -1,5 +1,5 @@ # Toc - +- [API root](api/evennia-api.rst) - [Coding/Coding Introduction](Coding/Coding-Introduction) - [Coding/Coding Overview](Coding/Coding-Overview) - [Coding/Continuous Integration](Coding/Continuous-Integration) diff --git a/evennia/commands/default/comms.py b/evennia/commands/default/comms.py index a681490640..1ae88649a7 100644 --- a/evennia/commands/default/comms.py +++ b/evennia/commands/default/comms.py @@ -1,12 +1,12 @@ """ -Comsystem command module. +Communication commands: -Comm commands are OOC commands and intended to be made available to -the Account at all times (they go into the AccountCmdSet). So we -make sure to homogenize self.caller to always be the account object -for easy handling. +- channel +- page +- irc/rss/grapevine linking """ + from django.conf import settings from evennia.comms.models import Msg from evennia.accounts.models import AccountDB @@ -25,6 +25,7 @@ CHANNEL_DEFAULT_TYPECLASS = class_from_module( # limit symbol import for API __all__ = ( "CmdChannel", + "CmdAddCom", "CmdDelCom", "CmdAllCom", @@ -34,7 +35,9 @@ __all__ = ( "CmdChannelCreate", "CmdClock", "CmdCdesc", + "CmdPage", + "CmdIRC2Chan", "CmdIRCStatus", "CmdRSS2Chan", @@ -52,17 +55,20 @@ class CmdChannel(COMMAND_DEFAULT_CLASS): Usage: channel - channel channelname [= ] + channel channelname + channel channel name [= ] channel/list channel/all + channel/alias channelname = alias[;alias...] + channel/unalias alias + channel/who channelname channel/history channelname [= index] channel/sub channelname [= alias[;alias...]] channel/unsub channelname[,channelname, ...] - channel/alias channelname = alias[;alias...] - channel/unalias alias channel/mute channelname[,channelname,...] channel/unmute channelname[,channelname,...] - channel/create channelname;alias;alias:typeclass [= description] + + channel/create channelname[;alias;alias[:typeclass]] [= description] channel/destroy channelname [= reason] channel/desc channelname = description channel/lock channelname = lockstring @@ -71,16 +77,99 @@ class CmdChannel(COMMAND_DEFAULT_CLASS): channel/ban channelname (list bans) channe/ban[/quiet] channelname[, channelname, ...] = subscribername [: reason] channel/unban[/quiet] channelname[, channelname, ...] = subscribername - channel/who channelname - # help-subcategories - ## channel/list + # subtopics + + ## sending + + Usage: channel channelname msg + channel channel name = msg (with space in channel name) + + This sends a message to the channel. Note that you will rarely use this command + like this; instead you can use the alias + + channelname + channelalias + + For example + + public Hello World + pub Hello World + + (this shortcut doesn't work for aliases containing spaces) + + See channel/alias for help on setting channel aliases. + + ## alias and unalias + + Usage: channel/alias channel = alias[;alias[;alias...]] + channel/unalias alias + channel - this will list your subs and aliases to each channel + + Set one or more personal aliases for referencing a channel. For example: + + channel/alias warrior's guild = warrior;wguild;warchannel;warrior guild + + You can now send to the channel using all of these: + + warrior's guild Hello + warrior Hello + wguild Hello + warchannel Hello + + Note that this will not work if the alias has a space in it. So the 'warrior guild' + alias must be used with the `channel` command: + + channel warrior guild = Hello + + Channel-aliases can be removed one at a time, using the '/unalias' switch. + + ## who + + Usage: channel/who channelname + + List the channel's subscribers. Shows who are currently offline or are + muting the channel. Subscribers who are 'muting' will not see messages sent + to the channel (use channel/mute to mute a channel). + + ## history + + Usage: channel/history channel [= index] + + This will display the last |c20|n lines of channel history. By supplying an + index number, you will step that many lines back before viewing those 20 lines. + For example: + + channel/history public = 35 + + will go back 35 lines and show the previous 20 lines from that point (so + lines -35 to -55). + + ## sub and unsub + + Usage: channel/sub channel [=alias[;alias;...]] + channel/unsub channel + + This subscribes you to a channel and optionally assigns personal shortcuts + for you to use to send to that channel (see aliases). When you unsub, all + your personal aliases will also be removed. + + ## mute and unmute + + Usage: channel/mute channelname + channel/unmute channelname + + Muting silences all output from the channel without actually + un-subscribing. Other channel members will see you are muted in the /who + list. Sending a message to the channel will automatically unmute you. + + ## create and destroy + + Usage: channel/create channelname[;alias;alias[:typeclass]] [= description] + channel/destroy channelname [= reason] + + Creates a new channel (or destroys one you control). - This handles all operations on channels. Note that the default operation is to - assign a nick/alias for sending to a channel. This would mean you can send - using 'foo Hello world' instead of using 'channel foo = Hello world'. Note that - aliases set when creating the channel are made available as aliases to subscribers - automatically. """ key = "channel" @@ -589,7 +678,7 @@ class CmdChannel(COMMAND_DEFAULT_CLASS): who_list = [] for subscriber in all_subs: name = subscriber.get_display_name(caller) - conditions = ("muted" if subscriber in mute_list else "", + conditions = ("muting" if subscriber in mute_list else "", "offline" if subscriber not in online_list else "") conditions = [cond for cond in conditions if cond] cond_text = "(" + ", ".join(conditions) + ")" if conditions else "" @@ -677,7 +766,7 @@ class CmdChannel(COMMAND_DEFAULT_CLASS): if chan not in subscribed: substatus = "|rNo|n" elif caller in chan.mutelist: - substatus = "|rMuted|n" + substatus = "|rMuting|n" else: substatus = "|gYes|n" comtable.add_row( diff --git a/evennia/commands/default/help.py b/evennia/commands/default/help.py index a0bcf41150..13e8ed36c9 100644 --- a/evennia/commands/default/help.py +++ b/evennia/commands/default/help.py @@ -153,7 +153,7 @@ class CmdHelp(COMMAND_DEFAULT_CLASS): else: aliases = '' - help_text = "\n\n" + dedent(help_text.strip(), indent=0) + "\n" if help_text else "" + help_text = "\n\n" + dedent(help_text.strip('\n')) + "\n" if help_text else "" if subtopics: subtopics = (