[README.md] added documentation of feature support, local and remote …

…template file rendering usage, stream editor usage, ink template specification/syntax

README.md

@@ -1,18 +1,18 @@
 # <img src="https://raw.githubusercontent.com/chrissimpkins/ink/images/img/ink-logo-crunch.png">
-### A fast, flexible text template renderer
+### A fast, flexible stream editor and text file template renderer
 
 [![Build Status](https://semaphoreci.com/api/v1/sourcefoundry/ink/branches/master/badge.svg)](https://semaphoreci.com/sourcefoundry/ink) [![Build status](https://ci.appveyor.com/api/projects/status/21si0rtxx9q36cad/branch/master?svg=true)](https://ci.appveyor.com/project/chrissimpkins/ink/branch/master) [![Go Report Card](https://goreportcard.com/badge/github.com/chrissimpkins/ink)](https://goreportcard.com/report/github.com/chrissimpkins/ink)
 
 # What is ink?
 
-ink is an open source command line text file template renderer that is built with Go. The ink executable is compiled for use on [Linux, macOS, and Windows platforms]((https://github.com/chrissimpkins/ink/releases/latest)).  It was designed to provide a simple approach to get your command line executable text data into pre-formatted text files.
+ink is an open source stream editor and text file template renderer that is built with Go. The ink executable is compiled for use on [Linux, macOS, and Windows platforms](https://github.com/chrissimpkins/ink/releases/latest).  It was designed to provide a simple approach to get command line executable text data into pre-formatted text files.
 
 It features:
 
-- line filter support (pipe replacement text from other applications to ink, render your template with the standard input piped text, then pipe the rendered text to the standard output stream for file writes or further text processing)
-- support for parallel multi-file renders from local and remotely stored (GET request accessible) templates
+- line filter stream editor support (pipe replacement text from other applications to ink, render your template with the standard input piped text, then pipe the rendered text to the standard output stream for file writes or further text processing)
+- support for parallel multi-file text replacements from local and remotely stored (GET request accessible) templates
 - a simple built-in text template format using `{{ ink }}` text labels
-- extremely flexible user defined text template formatting that supports *any template format*™ that you'd like to use (you define it on the command line)
+- extremely flexible user defined text template formatting that supports *any text replacement label*™ that you'd like to use (you define it on the command line)
 
 ### Example
 
@@ -141,15 +141,123 @@ $ go get github.com/chrissimpkins/ink
 
 ### Syntax
 
-#### Local template files
+#### Local template file rendering
+
+The following approach uses the built-in ink template syntax and file extension format to identify text replacement sites in the source document (see details below).
+
+```
+$ ink --replace=[replacement string] [options] [template path 1]...[template path n]
+```
+
+or 
+
+```
+$ [executable command stdout stream] | ink [options] [template path 1]...[template path n]
+```
+
+#### Remote template file rendering
+
+The following approach uses the built-in ink template syntax and file extension format to identify text replacement sites in the source document (see details below).
+
+```
+$ ink --replace=[replacement string] [options] [template URL 1]...[template URL n]
+```
+
+or
 
 ```
-$ ink [options] [template path 1]...[template path n]
+$ [executable command stdout stream] | ink [options] [template URL 1]...[template URL n]
 ```
 
-#### Remote template files
+#### Stream editor text substitutions
 
+The stream editor approach supports user-defined text replacement sites in the source document. This permits you to define alternate template tags in pre-formatted files and to use ink as a stream editor for routine find/replace text substitutions in the source document.
+
+```
+$ ink --find=[find string] --replace=[replacement string] [options] [template path 1]...[template path n]
 ```
-$ ink [options] [template URL 1]...[template URL n]
+
+or
+
+```
+$ [executable command stdout replacement stream] | ink --find=[find string] [options] [template path 1]...[template path n]
+```
+
+Remote text files can be streamed as the source text by replacing the template file paths with one or more GET request accessible URL as shown in the examples above.
+
+You can create a pipeline from ink to additional applications (or define your own outfile path) by including the `--stdout` option in your command.
+
+### Options
+
+- `--find=` : find string value for user defined templates
+- `-h, --help` : application help
+- `--lint` : lint a template file for validity
+- `--replace=` : replacement string value for template renders
+- `--stdout` : write rendered text to standard output stream
+- `--trimnl` : trim newline value from replacement string (intended for use with data piped through stdin stream)
+- `--usage` : application usage
+- `-v, --version` : application version
+
+### How to define a replacement string
+
+The replacement text for your template file can either be piped to `ink` through the standard input stream or you can include the `--replace=[replacement string]` option in the command.  These are mutually exclusive and one of the two approaches is mandatory with each command.
+
+The following examples demonstrate how to achieve replacements with the same constant string literal using each approach:
+
 ```
+$ echo "abcd123" | ink template.txt.in
+$ ink --replace=abcd123 template.txt.in
+```
+
+and these examples demonstrate how to evaluate command line expressions and use the standard output data as the replacement text with each approach:
+
+```
+$ date | ink template.txt.in
+$ ink --replace="$(date)" template.txt.in
+```
+
+### How to pipe a rendered template to the standard output stream
+
+By default, `ink` writes the rendered text to a file located in the same directory as the template file on a file path that is defined by the removal of the `.in` file extension.  You can modify this behavior to pipe the data through the standard output stream instead of writing to disk by including the `--stdout` option in your command.
+
+For example:
+
+```
+$ ink --replace=abcd123 --stdout template.txt.in
+```
+
+This will permit you to view the rendered text in your terminal or to pipe it to another application for further text processing.
+
+Here is a Linux/macOS example of a pipeline to and from `ink` with a file write to the path `finalfile.txt` after further processing in the (fake) application `cooltxt`:
+
+```
+$ echo "abcd123" | ink template.txt.in | cooltxt --dothings > finalfile.txt
+```
+
+### Replacement Text Modification Options
+
+#### Trim newline characters from replacement strings
+
+Some command line executables include a newline character following the standard output text (including the echo executable examples above).  This is not always desirable in the replacement substring that is used in your template files.  To remove the newline character, include the `--trimnl` option in your command:
+
+```
+$ echo "abcd123" | ink --trimnl template.txt.in
+```
+
+## Templates
+
+### ink template specification
+
+The ink template file is specified as follows:
+
+- Local and remote template files that are rendered to text file by ink MUST be defined by a path that includes the intended file path of the rendered text outfile with the addition of the extension `.in`.
+- Local and remote template files that are used to pipe rendered text data to the standard output stream do not have a specified file path format.  Users may define any local or remote path when the `--stdout` option is used.  The addition of a `.in` extension to the desired outfile path for these template files is RECOMMENDED when file writes are performed with these data.
+- The template MAY include template text replacement site tags that are defined as `{{ink}}` or `{{ ink }}`.
+- The template MAY include template text replacement site tags that are defined as `{{.Ink}}` or `{{ .Ink }}`.
+- ink MUST replace all characters up to and including the initial `{` and final `}` glyphs in the template text replacement site tags.
+- ink MUST replace all template text replacement site tags in template files during each execution.
+
+### User-defined templates
+
+- TODO
 

ink.go

@@ -42,7 +42,7 @@ import (
 
 const (
 	// Version is the application version string
-	Version = "0.6.2"
+	Version = "0.6.3.dev1"
 
 	// Usage is the application usage string
 	Usage = `Usage: ink [options] [template path 1]...[template path n]