Man page wip

.gitignore

@@ -40,3 +40,8 @@ prime/
 yq*.snap
 test.yml
 test2.yml
+
+
+# man page
+man.md
+yq.1

pkg/yqlib/doc/aa.md

@@ -1,5 +1,3 @@
-# Operators
-
 In `yq` expressions are made up of operators and pipes. A context of nodes is passed through the expression and each operation takes the context as input and returns a new context as output. That output is piped in as input for the next operation in the expression. To begin with, the context is set to the first yaml document of the first yaml file (if processing in sequence using eval).
 
 Lets look at a couple of examples.

pkg/yqlib/doc/headers/Main.md

@@ -0,0 +1,48 @@
+# NAME
+  *yq* - Command-line yaml processor
+
+# SYNOPSIS 
+a lightweight and portable command-line YAML processor. `yq` uses [jq](https://github.com/stedolan/jq) like syntax but works with yaml files as well as json. It doesn't yet support everything `jq` does - but it does support the most common operations and functions, and more is being added continuously.
+
+# QUICK GUIDE 
+
+## Read a value:
+```bash
+yq e '.a.b[0].c' file.yaml
+```
+
+## Pipe from STDIN:
+```bash
+cat file.yaml | yq e '.a.b[0].c' -
+```
+
+## Update a yaml file, inplace
+```bash
+yq e -i '.a.b[0].c = "cool"' file.yaml
+```
+
+## Update using environment variables
+```bash
+NAME=mike yq e -i '.a.b[0].c = strenv(NAME)' file.yaml
+```
+
+## Merge multiple files
+```
+yq ea '. as $item ireduce ({}; . * $item )' path/to/*.yml
+```
+
+## Multiple updates to a yaml file
+```bash
+yq e -i '
+  .a.b[0].c = "cool" |
+  .x.y.z = "foobar" |
+  .person.name = strenv(NAME)
+' file.yaml
+```
+
+See the [documentation](https://mikefarah.gitbook.io/yq/) for more.
+
+# KNOWN ISSUES / MISSING FEATURES
+- `yq` attempts to preserve comment positions and whitespace as much as possible, but it does not handle all scenarios (see https://github.com/go-yaml/yaml/tree/v3 for details)
+- Powershell has its own...opinions: https://mikefarah.gitbook.io/yq/usage/tips-and-tricks#quotes-in-windows-powershell
+

scripts/genman.sh

@@ -0,0 +1,21 @@
+#! /bin/bash
+set -e
+
+# note that this reqires pandoc to be installed.
+
+cat ./pkg/yqlib/doc/headers/Main.md > man.md
+printf "\n# HOW IT WORKS\n" >> man.md
+cat ./pkg/yqlib/doc/aa.md >> man.md
+
+for f in ./pkg/yqlib/doc/*.md; do 
+  docNameWithExt="${f##*/}"
+  docName="${docNameWithExt%.*}"
+  docNameCap=$(echo $docName | tr [a-z] [A-Z])
+  if [ "$docName" != "aa" ]; then
+    printf "\n\n# ${docNameCap}\n" >> man.md
+    cat "$f" >> man.md
+  fi
+  
+done
+
+pandoc --variable=title:"yq" --variable=author:"Mike Farah" --standalone --to man man.md -o yq.1