Improve help output

infogulch · Mar 6, 2024 · 309ab1d · 309ab1d
1 parent 71af297
commit 309ab1d
Show file tree

Hide file tree

Showing 3 changed files with 117 additions and 123 deletions.
diff --git a/README.md b/README.md
@@ -248,64 +248,55 @@ Download from the [Releases page](https://github.com/infogulch/xtemplate/release
 
 <details><summary><strong>🎏 CLI flags listing and examples</strong></summary>
 
-```
-$ ./xtemplate -help
-xtemplate is a hypertext preprocessor and http templating web server
-
-  -listen string
-        Listen address (default "0.0.0.0:8080")
-
-  -template-path string
-        Directory where templates are loaded from (default "templates")
-  -watch-template
-        Watch the template directory and reload if changed (default true)
-  -template-extension
-        File extension to look for to identify templates (default ".html")
-  -ldelim string
-        Left template delimiter (default "{{")
-  -rdelim string
-        Right template delimiter (default "}}")
-
-  -context-path string
-        Directory that template definitions are given direct access to. No access is given if empty (default "")
-  -watch-context
-        Watch the context directory and reload if changed (default false)
-
-  -db-driver string
-        Name of the database driver registered as a Go `sql.Driver`. Not available if empty. (default "")
-  -db-connstr string
-        Database connection string
-
-  -c string
-        Config values, in the form `x=y`. This arg can be specified multiple times
-
-  -log int
-        Log level, DEBUG=-4, INFO=0, WARN=4, ERROR=8
-  -help
-        Display help
-```
+```shell
+$ ./xtemplate --help
+xtemplate is a hypertext preprocessor and html templating http server
+
+Usage: ./xtemplate [options]
+
+Options:
+  -listen string              Listen address (default "0.0.0.0:8080")
+
+  -template-path string       Directory where templates are loaded from (default "templates")
+  -watch-template bool        Watch the template directory and reload if changed (default true)
+  -template-extension string  File extension to look for to identify templates (default ".html")
+  -minify bool                Preprocess the template files to minimize their size at load time (default false)
+  -ldelim string              Left template delimiter (default "{{")
+  -rdelim string              Right template delimiter (default "}}")
+
+  -context-path string        Directory that template definitions are given direct access to. No access is given if empty (default "")
+  -watch-context bool         Watch the context directory and reload if changed (default false)
+
+  -db-driver string           Name of the database driver registered as a Go 'sql.Driver'. Not available if empty. (default "")
+  -db-connstr string          Database connection string
+
+  -c string                   Config values, in the form 'x=y'. Can be used multiple times
+
+  -log int                    Log level. Log statements below this value are omitted from log output, DEBUG=-4, INFO=0, WARN=4, ERROR=8 (Default: 0)
+  -help                       Display help
 
 Examples:
-```shell
-# Listen on a custom port or address, see net.Listen.
-xtemplate -listen ":80"
+    Listen on port 80:
+    $ ./xtemplate -listen :80
+
+    Specify a context directory and reload when it changes:
+    $ ./xtemplate -context-path context/ -watch-context
 
-# Specify a custom path to the templates directory. Unless disabled with `-watch-template false`, xtemplate will
-# automatically reload the server when files in the templates directory are modified.
-xtemplate -template-path ./my-templates
+    Parse template files matching a custom extension and minify them:
+    $ ./xtemplate -template-extension ".go.html" -minify
 
-# This opens the specified db and makes it available to template files `.DB`. See
-xtemplate -db-driver sqlite3 -db-connstr 'file:rss.sqlite?_journal=WAL'
+    Open the specified db and makes it available to template files as '.DB':
+    $ ./xtemplate -db-driver sqlite3 -db-connstr 'file:rss.sqlite?_journal=WAL'
 ```
 
 </details>
 
 #### 2. As a custom CLI application
 
-Custom builds can add your chosen db drivers, add Go functions to the funcmap
-that are available to the template definitions, and even embed templates for
-true single binary deployments. See The [`./cmd` package](./cmd/) for reference
-when making a custom build.
+Custom builds can include your chosen db drivers, make Go functions available to
+the template definitions, and even embed templates for true single binary
+deployments. See The [`./cmd` package](./cmd/) for reference when making a
+custom build.
 
 #### 3. As a Go library
 

diff --git a/cmd/README.md b/cmd/README.md
@@ -2,8 +2,9 @@ This package is a tiny wrapper around [`xtemplate.Main()`](../main.go) which is
 the only code in the package.
 
 If you want to customize the xtemplate build with a specific database driver,
-custom template funcs, or to have more control over application startup, this is
-a good place to start looking.
+custom template funcs, or to have more control over application startup copy
+[main.go](main.go) to a new package and provide override funcs to call to
+`xtemplate.Main()`.
 
 ### Build
 
@@ -20,45 +21,43 @@ GOFLAGS='-tags="sqlite_json"' CGO_ENABLED=1 go build -o xtemplate ./cmd
 
 ### Usage
 
-```
+```shell
 $ ./xtemplate --help
-xtemplate is a hypertext preprocessor and http templating web server
-
-  -listen string
-        Listen address (default "0.0.0.0:8080")
-
-  -template-path string
-        Directory where templates are loaded from (default "templates")
-  -watch-template
-        Watch the template directory and reload if changed (default true)
-  -template-extension
-        File extension to look for to identify templates (default ".html")
-  -ldelim string
-        Left template delimiter (default "{{")
-  -rdelim string
-        Right template delimiter (default "}}")
-
-  -context-path string
-        Directory that template definitions are given direct access to. No access is given if empty (default "")
-  -watch-context
-        Watch the context directory and reload if changed (default false)
-
-  -db-driver string
-        Name of the database driver registered as a Go `sql.Driver`. Not available if empty. (default "")
-  -db-connstr string
-        Database connection string
-
-  -c string
-        Config values, in the form `x=y`. This arg can be specified multiple times
-
-  -log int
-        Log level, DEBUG=-4, INFO=0, WARN=4, ERROR=8
-  -help
-        Display help
-```
+xtemplate is a hypertext preprocessor and html templating http server
 
-### Example
+Usage: ./xtemplate [options]
 
-```
-xtemplate -template-path my-templates-folder/ -watch-template -log -4
+Options:
+  -listen string              Listen address (default "0.0.0.0:8080")
+
+  -template-path string       Directory where templates are loaded from (default "templates")
+  -watch-template bool        Watch the template directory and reload if changed (default true)
+  -template-extension string  File extension to look for to identify templates (default ".html")
+  -minify bool                Preprocess the template files to minimize their size at load time (default false)
+  -ldelim string              Left template delimiter (default "{{")
+  -rdelim string              Right template delimiter (default "}}")
+
+  -context-path string        Directory that template definitions are given direct access to. No access is given if empty (default "")
+  -watch-context bool         Watch the context directory and reload if changed (default false)
+
+  -db-driver string           Name of the database driver registered as a Go 'sql.Driver'. Not available if empty. (default "")
+  -db-connstr string          Database connection string
+
+  -c string                   Config values, in the form 'x=y'. Can be used multiple times
+
+  -log int                    Log level. Log statements below this value are omitted from log output, DEBUG=-4, INFO=0, WARN=4, ERROR=8 (Default: 0)
+  -help                       Display help
+
+Examples:
+    Listen on port 80:
+    $ ./xtemplate -listen :80
+
+    Specify a context directory and reload when it changes:
+    $ ./xtemplate -context-path context/ -watch-context
+
+    Parse template files matching a custom extension and minify them:
+    $ ./xtemplate -template-extension ".go.html" -minify
+
+    Open the specified db and makes it available to template files as '.DB':
+    $ ./xtemplate -db-driver sqlite3 -db-connstr 'file:rss.sqlite?_journal=WAL'
 ```
diff --git a/main.go b/main.go
@@ -21,39 +21,41 @@ type flags struct {
 
 var helptext = `xtemplate is a hypertext preprocessor and html templating http server
 
-  -listen string
-        Listen address (default "0.0.0.0:8080")
-
-  -template-path string
-        Directory where templates are loaded from (default "templates")
-  -watch-template
-        Watch the template directory and reload if changed (default true)
-  -template-extension
-        File extension to look for to identify templates (default ".html")
-  -minify
-		Preprocess the template files to minimize their size at load time (default false)
-  -ldelim string
-        Left template delimiter (default "{{")
-  -rdelim string
-        Right template delimiter (default "}}")
-
-  -context-path string
-        Directory that template definitions are given direct access to. No access is given if empty (default "")
-  -watch-context
-        Watch the context directory and reload if changed (default false)
-
-  -db-driver string
-        Name of the database driver registered as a Go 'sql.Driver'. Not available if empty. (default "")
-  -db-connstr string
-        Database connection string
-
-  -c string
-        Config values, in the form 'x=y'. This arg can be specified multiple times
-
-  -log int
-        Log level, DEBUG=-4, INFO=0, WARN=4, ERROR=8
-  -help
-        Display help
+Usage: %[1]s [options]
+
+Options:
+  -listen string              Listen address (default "0.0.0.0:8080")
+
+  -template-path string       Directory where templates are loaded from (default "templates")
+  -watch-template bool        Watch the template directory and reload if changed (default true)
+  -template-extension string  File extension to look for to identify templates (default ".html")
+  -minify bool                Preprocess the template files to minimize their size at load time (default false)
+  -ldelim string              Left template delimiter (default "{{")
+  -rdelim string              Right template delimiter (default "}}")
+
+  -context-path string        Directory that template definitions are given direct access to. No access is given if empty (default "")
+  -watch-context bool         Watch the context directory and reload if changed (default false)
+
+  -db-driver string           Name of the database driver registered as a Go 'sql.Driver'. Not available if empty. (default "")
+  -db-connstr string          Database connection string
+
+  -c string                   Config values, in the form 'x=y'. Can be used multiple times
+
+  -log int                    Log level. Log statements below this value are omitted from log output, DEBUG=-4, INFO=0, WARN=4, ERROR=8 (Default: 0)
+  -help                       Display help
+
+Examples:
+    Listen on port 80:
+    $ %[1]s -listen :80
+
+    Specify a context directory and reload when it changes:
+    $ %[1]s -context-path context/ -watch-context
+
+    Parse template files matching a custom extension and minify them:
+    $ %[1]s -template-extension ".go.html" -minify
+
+    Open the specified db and makes it available to template files as '.DB':
+    $ %[1]s -db-driver sqlite3 -db-connstr 'file:rss.sqlite?_journal=WAL'
 `
 
 func parseflags() (f flags) {
@@ -75,10 +77,12 @@ func parseflags() (f flags) {
 	flag.Var(&f.config.UserConfig, "c", "Config values, in the form 'x=y', can be specified multiple times")
 
 	flag.IntVar(&f.config.LogLevel, "log", 0, "Log level, DEBUG=-4, INFO=0, WARN=4, ERROR=8")
-	flag.Parse()
+
 	flag.Usage = func() {
-		fmt.Fprintf(flag.CommandLine.Output(), "Usage of %s:\n%s\n", os.Args[0], helptext)
+		fmt.Fprintf(flag.CommandLine.Output(), helptext, os.Args[0])
 	}
+
+	flag.Parse()
 	return
 }