docs(readme): change default examples to use --output option (#45)

princjef · web-flow · commit 4f6490ebcdd7 · 2021-06-22T08:21:47.000-07:00
diff --git a/README.md b/README.md
@@ -52,7 +52,7 @@ Flags:
 The gomarkdoc command processes each of the provided packages\, generating documentation for the package in markdown format and writing it to console\. For example\, if you have a package in your current directory and want to send it to a documentation markdown file\, you might do something like this:
 
 ```
-gomarkdoc . > doc.md
+gomarkdoc --output doc.md .
 ```
 
 ### Package Specifiers
@@ -61,7 +61,13 @@ The gomarkdoc tool supports generating documentation for both local packages and
 
 ### Output Redirection
 
-If you want to redirect output for each processed package to a file\, you can alternatively provide the \-\-output/\-o option\, which accepts a template specifying how to generate the path of the output file\. A common usage of this option is when generating README documentation for a package with subpackages \(which are supported via the \.\.\. signifier available in other tools\):
+By default\, the documentation generated by the gomarkdoc command is sent to standard output\, where it can be redirected to a file\. This can be useful if you want to perform additional modifications to the documentation or send it somewhere other than a file\. However\, keep in mind that there are some inconsistencies in how various shells/platforms handle redirected command output \(for example\, Powershell encodes in UTF\-16\, not UTF\-8\)\. As a result\, the \-\-output option described below is recommended for most use cases\.
+
+```
+gomarkdoc . > doc.md
+```
+
+If you want to redirect output for each processed package to a file\, you can provide the \-\-output/\-o option\, which accepts a template specifying how to generate the path of the output file\. A common usage of this option is when generating README documentation for a package with subpackages \(which are supported via the \.\.\. signifier as in other parts of the golang toolchain\)\. In addition\, this option provides consistent behavior across platforms and shells:
 
 ```
 gomarkdoc --output '{{.Dir}}/README.md' ./...
@@ -116,7 +122,7 @@ gomarkdoc -t package=custom-package.gotxt -t doc=custom-doc.gotxt .
 As with the godoc tool itself\, only exported symbols will be shown in documentation\. This can be expanded to include all symbols in a package by adding the \-\-include\-unexported/\-u flag\.
 
 ```
-gomarkdoc -u . > README.md
+gomarkdoc -u -o README.md .
 ```
 
 You can also run gomarkdoc in a verification mode with the \-\-check/\-c flag\. This is particularly useful for continuous integration when you want to make sure that a commit correctly updated the generated documentation\. This flag is only supported when the \-\-output/\-o flag is specified\, as the file provided there is what the tool is checking:
diff --git a/doc.go b/doc.go
@@ -44,7 +44,7 @@
 // For example, if you have a package in your current directory and want to
 // send it to a documentation markdown file, you might do something like this:
 //
-//	gomarkdoc . > doc.md
+//	gomarkdoc --output doc.md .
 //
 // Package Specifiers
 //
@@ -57,12 +57,23 @@
 //
 // Output Redirection
 //
+// By default, the documentation generated by the gomarkdoc command is sent to
+// standard output, where it can be redirected to a file. This can be useful if
+// you want to perform additional modifications to the documentation or send it
+// somewhere other than a file. However, keep in mind that there are some
+// inconsistencies in how various shells/platforms handle redirected command
+// output (for example, Powershell encodes in UTF-16, not UTF-8). As a result,
+// the --output option described below is recommended for most use cases.
+//
+//	gomarkdoc . > doc.md
+//
 // If you want to redirect output for each processed package to a file, you can
-// alternatively provide the --output/-o option, which accepts a template
-// specifying how to generate the path of the output file. A common usage of
-// this option is when generating README documentation for a package with
-// subpackages (which are supported via the ... signifier available in other
-// tools):
+// provide the --output/-o option, which accepts a template specifying how to
+// generate the path of the output file. A common usage of this option is when
+// generating README documentation for a package with subpackages (which are
+// supported via the ... signifier as in other parts of the golang toolchain).
+// In addition, this option provides consistent behavior across platforms and
+// shells:
 //
 //	gomarkdoc --output '{{.Dir}}/README.md' ./...
 //
@@ -120,7 +131,7 @@
 // documentation. This can be expanded to include all symbols in a package by
 // adding the --include-unexported/-u flag.
 //
-//	gomarkdoc -u . > README.md
+//	gomarkdoc -u -o README.md .
 //
 // You can also run gomarkdoc in a verification mode with the --check/-c flag.
 // This is particularly useful for continuous integration when you want to make
