flags.Help takes a summary string

flags/flags.go

@@ -86,11 +86,12 @@ func HelpInvalidArg(sub cmd.Subcommand, arg string) {
 
 // print out help string by reflecting over fields of provided opts struct
 // and os.Exit(0)
-func Help(sub cmd.Subcommand, opts any) {
+func Help(sub cmd.Subcommand, summary string, opts any) {
 	v := reflect.ValueOf(opts)
 	t := v.Type()
 
-	w := tabwriter.NewWriter(os.Stdout, 0, 0, 3, ' ', 0)
+	// everything should go to either stderr or stdout:
+	w := tabwriter.NewWriter(os.Stderr, 0, 0, 3, ' ', 0)
 	positional := ""
 
 	for i := 0; i < v.NumField(); i++ {
@@ -112,7 +113,8 @@ func Help(sub cmd.Subcommand, opts any) {
 			)
 		}
 	}
-	log.Printf("um %s%s\n", sub, positional)
+	log.Printf("um %s%s\n\n", sub, positional)
+	log.Printf("%s\n\n", summary)
 	w.Flush()
 	os.Exit(0)
 }

last/last.go

@@ -6,11 +6,14 @@ import (
 	"log"
 	"path/filepath"
 
-	cmdpkg "github.com/brtholomy/um/go/cmd"
+	"github.com/brtholomy/um/go/cmd"
 	"github.com/brtholomy/um/go/flags"
 )
 
-const cmd = cmdpkg.Last
+const (
+	CMD     = cmd.Last
+	SUMMARY = "print the lexically last um file"
+)
 
 const (
 	GLOB = "[0-9]*.md"
@@ -33,10 +36,10 @@ func parseArgs(args []string) options {
 	for _, arg := range args {
 		switch {
 		case arg == opts.Help.Long || arg == opts.Help.Short:
-			flags.Help(cmd, opts)
+			flags.Help(CMD, SUMMARY, opts)
 		default:
-			flags.HelpInvalidArg(cmd, arg)
+			flags.HelpInvalidArg(CMD, arg)
-			flags.Help(cmd, opts)
+			flags.Help(CMD, SUMMARY, opts)
 		}
 	}
 	return opts
@@ -59,7 +62,7 @@ func Last(args []string) {
 	_ = parseArgs(args)
 	s, err := GlobLast(GLOB)
 	if err != nil {
-		log.Fatalf("um %s: %v", cmdpkg.Last, err)
+		log.Fatalf("um %s: %v", cmd.Last, err)
 	}
 	// send to stdout, not stderr as is default for log.Print:
 	fmt.Println(s)

next/next.go

@@ -8,12 +8,15 @@ import (
 	"regexp"
 	"strconv"
 
-	cmdpkg "github.com/brtholomy/um/go/cmd"
+	"github.com/brtholomy/um/go/cmd"
 	"github.com/brtholomy/um/go/flags"
 	"github.com/brtholomy/um/go/last"
 )
 
-const cmd = cmdpkg.Next
+const (
+	CMD     = cmd.Next
+	SUMMARY = "create the next um file and open with emacsclient"
+)
 
 const FILE_REGEXP = `(?m)^([0-9]+)\.[[:alpha:]]*\.*md$`
 
@@ -42,10 +45,10 @@ func parseArgs(args []string) options {
 		case i == 1 && !flags.HasDashPrefix(arg):
 			opts.Tags.Val = arg
 		case arg == opts.Help.Long || arg == opts.Help.Short:
-			flags.Help(cmd, opts)
+			flags.Help(CMD, SUMMARY, opts)
 		default:
-			flags.HelpInvalidArg(cmd, arg)
+			flags.HelpInvalidArg(CMD, arg)
-			flags.Help(cmd, opts)
+			flags.Help(CMD, SUMMARY, opts)
 		}
 	}
 	return opts
@@ -116,13 +119,13 @@ func Next(args []string) {
 	opts := parseArgs(args)
 	l, err := last.GlobLast(last.GLOB)
 	if err != nil {
-		log.Fatalf("um %s: %v", cmd, err)
+		log.Fatalf("um %s: %v", CMD, err)
 	}
 	filename, err := next(l, opts.Descriptor.Val)
 	if err != nil {
-		log.Fatalf("um %s: %v", cmd, err)
+		log.Fatalf("um %s: %v", CMD, err)
 	}
 	if err := emacsNext(filename, opts.Tags.Val); err != nil {
-		log.Fatalf("um %s: %v", cmd, err)
+		log.Fatalf("um %s: %v", CMD, err)
 	}
 }

sort/sort.go

@@ -7,12 +7,15 @@ import (
 	"slices"
 	"strings"
 
-	cmdpkg "github.com/brtholomy/um/go/cmd"
+	"github.com/brtholomy/um/go/cmd"
 	"github.com/brtholomy/um/go/flags"
 	"github.com/brtholomy/um/go/pipe"
 )
 
-const cmd = cmdpkg.Sort
+const (
+	CMD     = cmd.Sort
+	SUMMARY = "sort a filelist using a provided key filelist"
+)
 
 type options struct {
 	Source flags.Flag[string]
@@ -42,15 +45,15 @@ func parseArgs(args []string) options {
 		case arg == opts.Write.Long || arg == opts.Write.Short:
 			opts.Write.Val = true
 		case arg == opts.Help.Long || arg == opts.Help.Short:
-			flags.Help(cmd, opts)
+			flags.Help(CMD, SUMMARY, opts)
 		default:
-			flags.HelpInvalidArg(cmd, arg)
+			flags.HelpInvalidArg(CMD, arg)
-			flags.Help(cmd, opts)
+			flags.Help(CMD, SUMMARY, opts)
 		}
 	}
 	if !opts.Key.IsSet() {
-		flags.HelpRequired(cmd, opts.Key.Long)
+		flags.HelpRequired(CMD, opts.Key.Long)
-		flags.Help(cmd, opts)
+		flags.Help(CMD, SUMMARY, opts)
 	}
 	return opts
 }
@@ -69,7 +72,7 @@ func fileListSplit(f string) []string {
 	dat, err := os.ReadFile(f)
 	if err != nil {
 		// if this fails all is lost. just exit.
-		log.Fatalf("um %s: error opening file: %s\n%s", cmd, f, err)
+		log.Fatalf("um %s: error opening file: %s\n%s", CMD, f, err)
 	}
 	return strings.Split(string(dat), pipe.Newline)
 }
@@ -104,7 +107,7 @@ func sort(sslice []string, kmap map[string]int) string {
 
 func write(file string, content string) {
 	if err := os.WriteFile(file, []byte(content), 0664); err != nil {
-		log.Fatalf("um %s: error writing file: %s\n%s", cmd, file, err)
+		log.Fatalf("um %s: error writing file: %s\n%s", CMD, file, err)
 	}
 }
 

tag/tag.go

@@ -3,13 +3,15 @@ package tag
 import (
 	"os"
 
-	cmdpkg "github.com/brtholomy/um/go/cmd"
+	"github.com/brtholomy/um/go/cmd"
 	"github.com/brtholomy/um/go/flags"
 	"github.com/brtholomy/um/go/last"
 )
 
-// just so that copied calls into flags.Help don't have to be adjusted between files:
+const (
-const cmd = cmdpkg.Tag
+	CMD     = cmd.Tag
+	SUMMARY = "search for files with a set of tags"
+)
 
 type options struct {
 	Query   flags.Arg
@@ -43,10 +45,10 @@ func parseArgs(args []string) options {
 		case arg == opts.Date.Long || arg == opts.Date.Short:
 			i, opts.Date.Val = flags.ValidateIncrementFetchOrExit(args, i)
 		case arg == opts.Help.Long || arg == opts.Help.Short:
-			flags.Help(cmd, opts)
+			flags.Help(CMD, SUMMARY, opts)
 		default:
-			flags.HelpInvalidArg(cmd, arg)
+			flags.HelpInvalidArg(CMD, arg)
-			flags.Help(cmd, opts)
+			flags.Help(CMD, SUMMARY, opts)
 		}
 	}
 	return opts