📝 Mode docs work

.gitattributes

@@ -0,0 +1 @@
+**/*.md  whitespace=space-before-tab

README.md

@@ -1,10 +1,12 @@
-# YAMPL
+# Yampl
 
-YAMPL (yaml + tmpl) is a simple templating tool that can template yaml values based on line-comments.
+[![Go](https://github.com/clevyr/go-yampl/actions/workflows/go.yml/badge.svg)](https://github.com/clevyr/go-yampl/actions/workflows/go.yml)
+
+Yampl (yaml + tmpl) is a simple tool to template yaml values based on line-comments.
 
 ## Installation
 
-YAMPL is available in brew or as a Docker container.
+Yampl is available in brew or as a Docker container.
 
 #### Brew
 
@@ -18,14 +20,8 @@ brew install clevyr/tap/yampl
 docker pull ghcr.io/clevyr/yampl
 ```
 
-## Usage
-
-[View the help docs for usage information.](docs/yampl.md)
-
 ## Templating
 
-
-
 ### Functions
 
 All [Sprig functions](https://masterminds.github.io/sprig/) are available in templates, along with some extra functions:
@@ -48,12 +44,25 @@ The above produces `stable-alpine`
 
 ### Variables
 
-All variables passed in with the `-v` flag are available during templating.
-For example, a variable given as `-v tag=latest` can be used as `{{ .tag }}`.
+All variables passed in with the `-v` flag are available during templating.  
+For example, the variable `-v tag=latest` can be used as `{{ .tag }}`.
 
 The previous value is always available via `.Value` (`.Val` or `.V` if you're feeling lazy).
 
-### Example
+### Examples
+
+## Simple Examples
+
+```shell
+$ echo 'name: Clevyr #yampl {{ .name }}' | yampl -v name='Clevyr Inc.'
+name: Clevyr Inc. #yampl {{ .name }}
+$ echo 'name: Clevyr #yampl {{ upper .Value }}' | yampl
+name: CLEVYR #yampl {{ upper .Value }}
+$ echo 'image: nginx:stable-alpine #yampl {{ repo .Value }}:{{ .tag }}' | yampl -v tag=stable
+image: nginx:stable #yampl {{ repo .Value }}:{{ .tag }}
+```
+
+## Full Example
 
 Here is a simple Kubernetes nginx Deployment:
 
@@ -115,3 +124,7 @@ image: nginx:1.21.6 #yampl {{ repo .Value }}:{{ .tag }}
 
 This would generate the same output, but I didn't have to type `nginx` twice.
 This becomes more useful when using custom Docker registries where repo names can get quite long.
+
+## Usage
+
+[View the generated docs for usage information.](docs/yampl.md)

cmd/cmd.go

@@ -2,6 +2,7 @@ package cmd
 
 import (
 	"bytes"
+	_ "embed"
 	"errors"
 	"fmt"
 	"github.com/clevyr/go-yampl/internal/config"
@@ -14,9 +15,13 @@ import (
 	"strings"
 )
 
+//go:embed description.md
+var description string
+
 var Command = &cobra.Command{
 	Use:                   "yampl [-i] [-p prefix] [-v key=value ...] [file ...]",
 	Short:                 "Inline YAML templating via line-comments",
+	Long:                  description,
 	DisableFlagsInUseLine: true,
 	DisableAutoGenTag:     true,
 	ValidArgsFunction:     validArgs,
@@ -28,10 +33,10 @@ var Command = &cobra.Command{
 var conf config.Config
 
 func init() {
-	Command.Flags().BoolVarP(&conf.Inline, "inline", "i", false, "Edit files in-place")
-	Command.Flags().StringVarP(&conf.Prefix, "prefix", "p", "#yampl", "Template prefix. Must begin with '#'")
-	Command.Flags().StringVar(&conf.LeftDelim, "left-delim", "{{", "Override the default left delimiter")
-	Command.Flags().StringVar(&conf.RightDelim, "right-delim", "}}", "Override the default right delimiter")
+	Command.Flags().BoolVarP(&conf.Inline, "inline", "i", false, "Edit files in-place instead of printing to stdout")
+	Command.Flags().StringVarP(&conf.Prefix, "prefix", "p", "#yampl", "Line-comments are ignored unless this prefix is found. Prefix must begin with '#'")
+	Command.Flags().StringVar(&conf.LeftDelim, "left-delim", "{{", "Override the left delimiter")
+	Command.Flags().StringVar(&conf.RightDelim, "right-delim", "}}", "Override the right delimiter")
 }
 
 func validArgs(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {

cmd/description.md

@@ -0,0 +1,24 @@
+Yampl (yaml + tmpl) is a simple tool to template yaml values based on line-comments.
+
+This command can work on stdin/stdout or on files similarly to GNU sed:
+ - If not positional args are given, it will listen for input on stdin.
+ - It will continue to read input until EOF is encountered.
+ - By default, it will print to stdout.
+ - The `-i` flag will make it update files in-place.
+ - Multiple files can be given, and they will all be templated.
+
+Simple Examples (Full example at https://github.com/clevyr/go-yampl#examples):
+
+ $ echo 'name: Clevyr #yampl {{ .name }}' | yampl -v name='Clevyr Inc.'  
+ name: Clevyr Inc. #yampl {{ .name }}  
+ $ echo 'name: Clevyr #yampl {{ upper .Value }}' | yampl  
+ name: CLEVYR #yampl {{ upper .Value }}  
+ $ echo 'image: nginx:stable-alpine #yampl {{ repo .Value }}:{{ .tag }}' | yampl -v tag=stable  
+ image: nginx:stable #yampl {{ repo .Value }}:{{ .tag }}
+
+Template Function Reference:
+ - https://github.com/clevyr/go-yampl#functions
+ - https://masterminds.github.io/sprig/
+
+Template Variable Reference:
+ - https://github.com/clevyr/go-yampl#variables

cmd/flag_values.go

@@ -16,7 +16,7 @@ import (
 )
 
 func init() {
-	Command.Flags().StringToStringVarP((*map[string]string)(&conf.Values), "value", "v", map[string]string{}, "Define a template variable")
+	Command.Flags().StringToStringVarP((*map[string]string)(&conf.Values), "value", "v", map[string]string{}, "Define a template variable. Can be used more than once.")
 	err := Command.RegisterFlagCompletionFunc("value", valueCompletion)
 	if err != nil {
 		panic(err)

docs/yampl.md

@@ -2,6 +2,34 @@
 
 Inline YAML templating via line-comments
 
+### Synopsis
+
+Yampl (yaml + tmpl) is a simple tool to template yaml values based on line-comments.
+
+This command can work on stdin/stdout or on files similarly to GNU sed:
+ - If not positional args are given, it will listen for input on stdin.
+ - It will continue to read input until EOF is encountered.
+ - By default, it will print to stdout.
+ - The `-i` flag will make it update files in-place.
+ - Multiple files can be given, and they will all be templated.
+
+Simple Examples (Full example at https://github.com/clevyr/go-yampl#examples):
+
+ $ echo 'name: Clevyr #yampl {{ .name }}' | yampl -v name='Clevyr Inc.'  
+ name: Clevyr Inc. #yampl {{ .name }}  
+ $ echo 'name: Clevyr #yampl {{ upper .Value }}' | yampl  
+ name: CLEVYR #yampl {{ upper .Value }}  
+ $ echo 'image: nginx:stable-alpine #yampl {{ repo .Value }}:{{ .tag }}' | yampl -v tag=stable  
+ image: nginx:stable #yampl {{ repo .Value }}:{{ .tag }}
+
+Template Function Reference:
+ - https://github.com/clevyr/go-yampl#functions
+ - https://masterminds.github.io/sprig/
+
+Template Variable Reference:
+ - https://github.com/clevyr/go-yampl#variables
+
+
 ```
 yampl [-i] [-p prefix] [-v key=value ...] [file ...]
 ```
@@ -10,12 +38,11 @@ yampl [-i] [-p prefix] [-v key=value ...] [file ...]
 
 ```
       --completion string      Output command-line completion code for the specified shell. Can be 'bash', 'zsh', 'fish', or 'powershell'.
-  -C, --directory string       dir to hold the generated config (default "./docs")
   -h, --help                   help for yampl
-  -i, --inline                 Edit files in-place
-      --left-delim string      Override the default left delimiter (default "{{")
-  -p, --prefix string          Template prefix. Must begin with '#' (default "#yampl")
-      --right-delim string     Override the default right delimiter (default "}}")
-  -v, --value stringToString   Define a template variable (default [])
+  -i, --inline                 Edit files in-place instead of printing to stdout
+      --left-delim string      Override the left delimiter (default "{{")
+  -p, --prefix string          Line-comments are ignored unless this prefix is found. Prefix must begin with '#' (default "#yampl")
+      --right-delim string     Override the right delimiter (default "}}")
+  -v, --value stringToString   Define a template variable. Can be used more than once. (default [])
 ```