From e14109e1b4d64b25e4efcc4b9151ec25fbcf4db3 Mon Sep 17 00:00:00 2001
From: Nick Craig-Wood <nick@craig-wood.com>
Date: Mon, 24 Feb 2025 09:58:38 +0000
Subject: [PATCH] convmv: update help text - FIXME WIP

need a help line for each conversion mode
---
 cmd/convmv/convmv.go          | 43 ++++++++++++++++++++++++-----------
 cmd/convmv/convmv_examples.go | 14 ++++++++----
 2 files changed, 39 insertions(+), 18 deletions(-)

diff --git a/cmd/convmv/convmv.go b/cmd/convmv/convmv.go
index e58207d22..2a0ae99c1 100644
--- a/cmd/convmv/convmv.go
+++ b/cmd/convmv/convmv.go
@@ -167,7 +167,9 @@ var commandDefinition = &cobra.Command{
 	Short: `Convert file and directory names`,
 	// Warning! "|" will be replaced by backticks below
 	Long: strings.ReplaceAll(`
-Docs todo!
+This command renames files and directory names according a user supplied conversion.
+
+It is useful for renaming a lot of files in an automated way.
 
 `+sprintList()+`
 
@@ -459,27 +461,42 @@ func toASCII(s string) string {
 }
 
 func sprintList() string {
-	s := fmt.Sprintln("Conversion modes:  ")
+	var out strings.Builder
+
+	_, _ = out.WriteString(`### Conversion modes
+
+The conversion mode |-t| or |--conv| flag must be specified. This
+defines what transformation the |convmv| command will make.
+
+`)
 	for _, v := range Opt.ConvertAlgo.Choices() {
-		s += fmt.Sprintln(v + "  ")
+		_, _ = fmt.Fprintf(&out, "- `%s`\n", v)
 	}
-	s += fmt.Sprintln()
+	_, _ = out.WriteRune('\n')
 
-	s += fmt.Sprintln("Char maps:  ")
+	_, _ = out.WriteString(`### Char maps
+
+These are the choices for the |--charmap| flag.
+
+`)
 	for _, v := range Opt.CmapFlag.Choices() {
-		s += fmt.Sprintln(v + "  ")
+		_, _ = fmt.Fprintf(&out, "- `%s`\n", v)
 	}
-	s += fmt.Sprintln()
+	_, _ = out.WriteRune('\n')
 
-	s += fmt.Sprintln("Encoding masks:  ")
-	for _, v := range strings.Split(encoder.ValidStrings(), ",") {
-		s += fmt.Sprintln(v + "  ")
+	_, _ = out.WriteString(`### Encoding masks
+
+These are the valid options for the --encoding flag.
+
+`)
+	for _, v := range strings.Split(encoder.ValidStrings(), ", ") {
+		_, _ = fmt.Fprintf(&out, "- `%s`\n", v)
 	}
-	s += fmt.Sprintln()
+	_, _ = out.WriteRune('\n')
 
-	s += sprintExamples()
+	sprintExamples(&out)
 
-	return s
+	return out.String()
 }
 
 func printList() {
diff --git a/cmd/convmv/convmv_examples.go b/cmd/convmv/convmv_examples.go
index 1aa9ca550..0a7784998 100644
--- a/cmd/convmv/convmv_examples.go
+++ b/cmd/convmv/convmv_examples.go
@@ -2,6 +2,7 @@ package convmv
 
 import (
 	"fmt"
+	"strings"
 
 	"github.com/rclone/rclone/fs"
 	"github.com/rclone/rclone/lib/encoder"
@@ -59,14 +60,17 @@ func (e example) output() string {
 }
 
 // go run ./ convmv --help
-func sprintExamples() string {
-	s := "Examples: \n\n"
+func sprintExamples(out *strings.Builder) {
+	_, _ = fmt.Fprintf(out, `### Examples:
+
+Here are some examples of rclone convmv in action.
+
+`)
 	for _, e := range examples {
-		s += fmt.Sprintf("```\n%s\n", e.command())
-		s += fmt.Sprintf("// Output: %s\n```\n\n", e.output())
+		_, _ = fmt.Fprintf(out, "```\n%s\n", e.command())
+		_, _ = fmt.Fprintf(out, "// Output: %s\n```\n\n", e.output())
 	}
 	Opt = ConvOpt{} // reset
-	return s
 }
 
 /* func sprintAllCharmapExamples() string {