Merge pull request #588 from slingamn/servicehelp.5

refactor /HELP for services

irc/chanserv.go

@@ -17,13 +17,7 @@ import (
 	"github.com/oragono/oragono/irc/sno"
 )
 
-const chanservHelp = `ChanServ lets you register and manage channels.
+const chanservHelp = `ChanServ lets you register and manage channels.`
-
-To see in-depth help for a specific ChanServ command, try:
-    $b/CS HELP <command>$b
-
-Here are the commands you can use:
-%s`
 
 func chanregEnabled(config *Config) bool {
 	return config.Channels.Registration.Enabled

irc/handlers.go

@@ -1091,7 +1091,7 @@ Get an explanation of <argument>, or "index" for a list of help topics.`), rb)
 
 	if exists && (!helpHandler.oper || (helpHandler.oper && client.HasMode(modes.Operator))) {
 		if helpHandler.textGenerator != nil {
-			client.sendHelp(strings.ToUpper(argument), client.t(helpHandler.textGenerator(client)), rb)
+			client.sendHelp(strings.ToUpper(argument), helpHandler.textGenerator(client), rb)
 		} else {
 			client.sendHelp(strings.ToUpper(argument), client.t(helpHandler.text), rb)
 		}

irc/help.go

@@ -135,11 +135,6 @@ message (and as your quit message if you don't return in time).`,
 Used in capability negotiation. See the IRCv3 specs for more info:
 http://ircv3.net/specs/core/capability-negotiation-3.1.html
 http://ircv3.net/specs/core/capability-negotiation-3.2.html`,
-	},
-	"chanserv": {
-		text: `CHANSERV <subcommand> [params]
-
-ChanServ controls channel registrations.`,
 	},
 	"chathistory": {
 		text: `CHATHISTORY [params]
@@ -147,11 +142,6 @@ ChanServ controls channel registrations.`,
 CHATHISTORY is an experimental history replay command. See these documents:
 https://github.com/MuffinMedic/ircv3-specifications/blob/chathistory/extensions/chathistory.md
 https://gist.github.com/DanielOaks/c104ad6e8759c01eb5c826d627caf80d`,
-	},
-	"cs": {
-		text: `CS <subcommand> [params]
-
-ChanServ controls channel registrations.`,
 	},
 	"debug": {
 		oper: true,
@@ -212,18 +202,6 @@ Replay message history. <target> can be a channel name, "me" to replay direct
 message history, or a nickname to replay another client's direct message
 history (they must be logged into the same account as you). At most [limit]
 messages will be replayed.`,
-	},
-	"hostserv": {
-		text: `HOSTSERV <command> [params]
-
-HostServ lets you manage your vhost (a string displayed in place of your
-real hostname).`,
-	},
-	"hs": {
-		text: `HS <command> [params]
-
-HostServ lets you manage your vhost (a string displayed in place of your
-real hostname).`,
 	},
 	"info": {
 		text: `INFO
@@ -350,11 +328,6 @@ view the channel membership prefixes supported by this server, see the help for
 		text: `NICK <newnick>
 
 Sets your nickname to the new given one.`,
-	},
-	"nickserv": {
-		text: `NICKSERV <subcommand> [params]
-
-NickServ controls accounts and user registrations.`,
 	},
 	"notice": {
 		text: `NOTICE <target>{,<target>} <text to be sent>
@@ -374,11 +347,6 @@ Requires the roleplay mode (+E) to be set on the target.`,
 The NPC command is used to send an action to the target as the source.
 
 Requires the roleplay mode (+E) to be set on the target.`,
-	},
-	"ns": {
-		text: `NS <subcommand> [params]
-
-NickServ controls accounts and user registrations.`,
 	},
 	"oper": {
 		text: `OPER <name> <password>

irc/hostserv.go

@@ -11,13 +11,7 @@ import (
 )
 
 const hostservHelp = `HostServ lets you manage your vhost (i.e., the string displayed
-in place of your client's hostname/IP).
+in place of your client's hostname/IP).`
-
-To see in-depth help for a specific HostServ command, try:
-    $b/HS HELP <command>$b
-
-Here are the commands you can use:
-%s`
 
 var (
 	errVHostBadCharacters = errors.New("Vhost contains prohibited characters")

irc/nickserv.go

@@ -41,13 +41,7 @@ const (
 	nsTimeoutNotice = `This nickname is reserved. Please login within %v (using $b/msg NickServ IDENTIFY <password>$b or SASL), or switch to a different nickname.`
 )
 
-const nickservHelp = `NickServ lets you register and login to an account.
+const nickservHelp = `NickServ lets you register and log into an account.`
-
-To see in-depth help for a specific NickServ command, try:
-    $b/NS HELP <command>$b
-
-Here are the commands you can use:
-%s`
 
 var (
 	nickservCommands = map[string]*serviceCommand{

irc/services.go

@@ -4,6 +4,7 @@
 package irc
 
 import (
+	"bytes"
 	"fmt"
 	"log"
 	"sort"
@@ -190,6 +191,14 @@ func serviceHelpHandler(service *ircService, server *Server, client *Client, par
 	sendNotice(ircfmt.Unescape(fmt.Sprintf("*** $b%s HELP$b ***", service.Name)))
 
 	if len(params) == 0 {
+		helpBannerLines := strings.Split(client.t(service.HelpBanner), "\n")
+		helpBannerLines = append(helpBannerLines, []string{
+			"",
+			client.t("To see in-depth help for a specific command, try:"),
+			ircfmt.Unescape(fmt.Sprintf(client.t("    $b/msg %s HELP <command>$b"), service.Name)),
+			"",
+			client.t("Here are the commands you can use:"),
+		}...)
 		// show general help
 		var shownHelpLines sort.StringSlice
 		var disabledCommands bool
@@ -206,7 +215,7 @@ func serviceHelpHandler(service *ircService, server *Server, client *Client, par
 				continue
 			}
 
-			shownHelpLines = append(shownHelpLines, "    "+client.t(commandInfo.helpShort))
+			shownHelpLines = append(shownHelpLines, ircfmt.Unescape("    "+client.t(commandInfo.helpShort)))
 		}
 
 		if disabledCommands {
@@ -216,12 +225,11 @@ func serviceHelpHandler(service *ircService, server *Server, client *Client, par
 		// sort help lines
 		sort.Sort(shownHelpLines)
 
-		// assemble help text
-		assembledHelpLines := strings.Join(shownHelpLines, "\n")
-		fullHelp := ircfmt.Unescape(fmt.Sprintf(client.t(service.HelpBanner), assembledHelpLines))
-
 		// push out help text
-		for _, line := range strings.Split(fullHelp, "\n") {
+		for _, line := range helpBannerLines {
+			sendNotice(line)
+		}
+		for _, line := range shownHelpLines {
 			sendNotice(line)
 		}
 	} else {
@@ -249,6 +257,18 @@ func serviceHelpHandler(service *ircService, server *Server, client *Client, par
 	sendNotice(ircfmt.Unescape(fmt.Sprintf(client.t("*** $bEnd of %s HELP$b ***"), service.Name)))
 }
 
+func makeServiceHelpTextGenerator(cmd string, banner string) func(*Client) string {
+	return func(client *Client) string {
+		var buf bytes.Buffer
+		fmt.Fprintf(&buf, client.t("%s <subcommand> [params]"), cmd)
+		buf.WriteRune('\n')
+		buf.WriteString(client.t(banner)) // may contain newlines, that's fine
+		buf.WriteRune('\n')
+		fmt.Fprintf(&buf, client.t("For more details, try /%s HELP"), cmd)
+		return buf.String()
+	}
+}
+
 func initializeServices() {
 	// this modifies the global Commands map,
 	// so it must be called from irc/commands.go's init()
@@ -263,12 +283,16 @@ func initializeServices() {
 		// reserve the nickname
 		restrictedNicknames = append(restrictedNicknames, service.Name)
 
-		// register the protocol-level commands (NICKSERV, NS) that talk to the service
+		// register the protocol-level commands (NICKSERV, NS) that talk to the service,
+		// and their associated help entries
 		var ircCmdDef Command
 		ircCmdDef.handler = serviceCmdHandler
 		for _, ircCmd := range service.CommandAliases {
 			Commands[ircCmd] = ircCmdDef
 			oragonoServicesByCommandAlias[ircCmd] = service
+			Help[strings.ToLower(ircCmd)] = HelpEntry{
+				textGenerator: makeServiceHelpTextGenerator(ircCmd, service.HelpBanner),
+			}
 		}
 
 		// force devs to write a help entry for every command