Profanity: Standardize commands

Created on 5 Jun 2019 · 8Comments · Source: profanity-im/profanity

Some commands work differently than others or are grouped badly.
Examples:

/roster show/hide resource is the setting to manipulate whether the resource is shown in the roster.
Everywhere where we can decide whether something should be shown or hidden we should use this syntax. However to enable showing the resource in the title bar we use /resource titlebar on.

We need to collect all such behaviour here and then work on standardizing it to cover all cases.
I plan to have this for 0.8.0 because I plan more cleanup there.

discussion improvement

Source

jubalh

Most helpful comment

Warning, long and filled with personal oppinion.

First of all, i think distiguishing between commands that trigger an action immediatly and commands that only set a configuration option and is rarely ever used again, could be helpful.

i went through cmd_defs.c from top. examples to discuss about:

/tls show on|off, show or hide the TLS indicator in the titlebar.
- this could be expected as sub command in /titlebar as it affects the titlebars appearance
/tls revoke revokes a cert, but
- /omemo|otr untrust is used to revoke/untrust a key. /pgp setkey also adds inconsistency
/msg <contact> message a contact, uses nick, if set
- should react on jid even if nick is set, it works with jid if nick is not set
/group manages roster entries
- somewhat confusing to have it as seperate command while nicks are set as roster sub command
/info|caps|software|status show several informations
- maybe group them as sub command below one info command
/status feels like it should set our own status
/resource remove current funtionality suggested in #912
- use the command to manage ones own resource, set it explicitly to a desired value instead of default
- default should be something like profanity.#### as suggested by XMPP 2.0 , but setting a preferably unique resource is still allowed
/leave nothing wrong, but
- maybe add /part as compatibility to irc (which muc comes from), see https://xmpp.org/extensions/xep-0045.html#impl-client-irc
- also a leave/part massage would be neat /leave so long and thanks for all the fish (see document, i think thats )
/invites see the following
/decline room seems good, but could be merged as subcommand of /invites decline ... as invites are managed by this. I have yet not received an invite with profanity, where is accept?
- also /sub is the equivalet to invite and there all management tasks are done with sub commants to /sub
/occupants show shows occupants panel
- as show is mainly used to configure roster or occ panel, the command to display the occupants panel may be changed? what about /panel show occupants|roster
- or use /occupants list to print a list off occupants to muc window, but /occupants to show the panel
/bookmark update ...
- in other commands with equal functionality we use set rather than update, which is only used again with /plugins but in another context.
lastactivity sets sending own last activity to on or off but also queries others last activity
- querying others last activity might fit into the /info command
/wins unread --> /wins list unread maybe also /wins list in addition to /wins so one knows without any documentation, what the command does.
/sub nothing wrong, but /subscription as second name since novices might not know at first sight, what sub does.
- also listing pending requests could be shown via /subs(criptions) sent|received
/tiny i highly vote for removing/putting it in a plugin, as it uses a third party service not anybody might like.
- Or make it configurable, as you could host your own service like https://yourls.org/
/who too mighty, did not check thourroghly :P
/close works on windows so might fit as a subcommand somehwere in /win(s). Actually i never used it before, mostly switch to the window and /leave
/quit maybe add a quit/leave message to show in mucs ;-)
/privileges should be a sub command to /occupants as it groups the occupant list by privileges or not.
/encwarn, as it modifies the titlebar it should be subcommand there
/presence titlebar fites better to /titlebar
/presence console --> /console presence all|online|none
- there is a bigger conflict here. The command /presence sounds like it has something to do with our own presence settings, but it is just about informational display of others presences. Not sure how to feel about it, yet. Meybe a /settings command to structure that static settings one does not access often?
/time also feels wrong, some settings belong to status bar, somt to title bar, some could fit in a new /settings command.
/inpblock --> /settings inpblock ?
/titlebar|statusbar|mainwin|inputwin really own commands needed? See /settings
/notify, see /time and /presence.
/theme reload and get current theme subcommand would be neat
/resource, ,what @jubalh said :-)
/export exports contacts to csv never seen before :P
- either subcommands /export roster and /export bookmarks
- or /bookmark export and /roster export are nice to have

kaffeekanne on 5 Jun 2019

👍2

All 8 comments

Warning, long and filled with personal oppinion.

First of all, i think distiguishing between commands that trigger an action immediatly and commands that only set a configuration option and is rarely ever used again, could be helpful.

i went through cmd_defs.c from top. examples to discuss about:

/tls show on|off, show or hide the TLS indicator in the titlebar.
- this could be expected as sub command in /titlebar as it affects the titlebars appearance
/tls revoke revokes a cert, but
- /omemo|otr untrust is used to revoke/untrust a key. /pgp setkey also adds inconsistency
/msg <contact> message a contact, uses nick, if set
- should react on jid even if nick is set, it works with jid if nick is not set
/group manages roster entries
- somewhat confusing to have it as seperate command while nicks are set as roster sub command
/info|caps|software|status show several informations
- maybe group them as sub command below one info command
/status feels like it should set our own status
/resource remove current funtionality suggested in #912
- use the command to manage ones own resource, set it explicitly to a desired value instead of default
- default should be something like profanity.#### as suggested by XMPP 2.0 , but setting a preferably unique resource is still allowed
/leave nothing wrong, but
- maybe add /part as compatibility to irc (which muc comes from), see https://xmpp.org/extensions/xep-0045.html#impl-client-irc
- also a leave/part massage would be neat /leave so long and thanks for all the fish (see document, i think thats )
/invites see the following
/decline room seems good, but could be merged as subcommand of /invites decline ... as invites are managed by this. I have yet not received an invite with profanity, where is accept?
- also /sub is the equivalet to invite and there all management tasks are done with sub commants to /sub
/occupants show shows occupants panel
- as show is mainly used to configure roster or occ panel, the command to display the occupants panel may be changed? what about /panel show occupants|roster
- or use /occupants list to print a list off occupants to muc window, but /occupants to show the panel
/bookmark update ...
- in other commands with equal functionality we use set rather than update, which is only used again with /plugins but in another context.
lastactivity sets sending own last activity to on or off but also queries others last activity
- querying others last activity might fit into the /info command
/wins unread --> /wins list unread maybe also /wins list in addition to /wins so one knows without any documentation, what the command does.
/sub nothing wrong, but /subscription as second name since novices might not know at first sight, what sub does.
- also listing pending requests could be shown via /subs(criptions) sent|received
/tiny i highly vote for removing/putting it in a plugin, as it uses a third party service not anybody might like.
- Or make it configurable, as you could host your own service like https://yourls.org/
/who too mighty, did not check thourroghly :P
/close works on windows so might fit as a subcommand somehwere in /win(s). Actually i never used it before, mostly switch to the window and /leave
/quit maybe add a quit/leave message to show in mucs ;-)
/privileges should be a sub command to /occupants as it groups the occupant list by privileges or not.
/encwarn, as it modifies the titlebar it should be subcommand there
/presence titlebar fites better to /titlebar
/presence console --> /console presence all|online|none
- there is a bigger conflict here. The command /presence sounds like it has something to do with our own presence settings, but it is just about informational display of others presences. Not sure how to feel about it, yet. Meybe a /settings command to structure that static settings one does not access often?
/time also feels wrong, some settings belong to status bar, somt to title bar, some could fit in a new /settings command.
/inpblock --> /settings inpblock ?
/titlebar|statusbar|mainwin|inputwin really own commands needed? See /settings
/notify, see /time and /presence.
/theme reload and get current theme subcommand would be neat
/resource, ,what @jubalh said :-)
/export exports contacts to csv never seen before :P
- either subcommands /export roster and /export bookmarks
- or /bookmark export and /roster export are nice to have

kaffeekanne on 5 Jun 2019

👍2

Also related to this issue. We need to keep https://github.com/profanity-im/profanity/issues/934 in mind

jubalh on 5 Oct 2019

/status feels like it should set our own status

I agree. Maybe it should do both. Right now we have individual commands: /online, /away. It's hard to find all the possibilities of them and list them in one place.

I think they should all go into status, like /status set away /status set online to set our own status.
And remove /online etc.

/status in a 1:1 chat will then print the others status. /status someone will print the others status too.

And alternative would be to leave status as is, and use /presence to set our own.
/presence is so far used to display (or not) the presence in various UI elements. Which we plan to change too and put into a general ui changing command or one command for each ui element.

jubalh on 8 Oct 2019

Prepared website to have individual userguides for each version.
Probably things will change especially the command reference. It's nicer for users to have a reference for each version.

Relevant commits:
https://github.com/profanity-im/profanity-im.github.io/commit/e1d25d96606da37fda20dab382360013aab0b711
https://github.com/profanity-im/profanity-im.github.io/commit/abaa43022f94be03b7b01e07e2a3f91730d6dc13
https://github.com/profanity-im/profanity-im.github.io/commit/04ab8adebdb4d954f1241c77e61bf5c002da2d2b
https://github.com/profanity-im/profanity-im.github.io/commit/a1a3778094a99965ca9f0f394a25509dac4d86d3

jubalh on 8 Oct 2019

👍1

/leave just closes the current window. I will remove this and people should use /close or create an alias.

jubalh on 22 Oct 2019

I'll copy @kaffeekanne s text down here and will always edit it according to latest changes. I want to leave his original comment as is.

jubalh on 5 Nov 2019

WIP of @kaffekannes comment:

/info|caps|software|status show several informations
- maybe group them as sub command below one info command
/resource remove current funtionality suggested in #912
- use the command to manage ones own resource, set it explicitly to a desired value instead of default
- default should be something like profanity.#### as suggested by XMPP 2.0 , but setting a preferably unique resource is still allowed
- listing pending requests could be shown via /subs(criptions) sent|received