commit 0e53eec4b61dd0cd33ddf67502d60772bf470302
parent 8beaaea788c5529d0eb16b4f74cf7b5c50414376
Author: gearsix <gearsix@tuta.io>
Date: Sat, 13 Mar 2021 13:19:46 +0000
moved suti.txt to doc/
Diffstat:
| A | doc/suti.txt | | | 126 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| D | suti.txt | | | 127 | ------------------------------------------------------------------------------- |
2 files changed, 126 insertions(+), 127 deletions(-)
diff --git a/doc/suti.txt b/doc/suti.txt
@@ -0,0 +1,125 @@
+NAME
+ suti - simple unified templating interface
+
+USAGE
+ suti [OPTIONS]
+
+DESCRIPTION
+ suti aims to provide a universal interface for executing data files,
+ written in any data-serialization language, against template files,
+ written in any templating languages.
+ Ideally suti will support any language you want to use.
+
+ suti works by using various libraries that do all the hard work to
+ parse data and template files passed to it. It generates a data
+ structure of all the passed data files combined (a super-data
+ structure) and executes that structure against a set of root template
+ files.
+ The used libraries are listed below for credit/reference.
+
+ suti can also be imported as a golang package to be used as a library.
+ See suti-lib for details.
+
+OPTIONS
+ -r path, -root path
+ path of template file to execute against.
+
+ -p path..., -partial path...
+ path of (multiple) template files that are called upon by at least one
+ root template. If a directory is passed then all files within that
+ directory will (recursively) be loaded.
+
+ -gd path..., -global-data path...
+ path of (multiple) data files to load as "global data". If a directory is
+ passed then all files within that directory will (recursively) be loaded.
+
+ -d path..., -data path...
+ path of (multiple) data files to load as "data". If a directory is passed
+ then all files within that directory will (recursively) be loaded.
+
+ -dk name, -data-key name
+ set the name of the key used for the generated array of data (default:
+ "data")
+
+ -sd attribute, -sort-data attribute
+ The file attribute to order data files by. If no value is provided, the data
+ will be provided in the order it's loaded.
+ Accepted values: "filename", "modified".
+ A suffix can be appended to each value to set the sort order: "-asc" (for
+ ascending), "-desc" (for descending). If not specified, this defaults to
+ "-asc".
+ -cfg file, -config file
+ A data file to provide default values for the above options (see CONFIG).
+
+CONFIG
+ It's possible you'll want to set the same options if you run suti multiple
+ times for the same project. This can be done by creating a file (written as
+ a data file) and passing the filepath to the -cfg argument.
+
+ The key names for the options set in the config file must match the name of
+ the argument option to set (long or short). For example (a config file in
+ toml):
+
+ root="~/templates/blog.mst"
+ partial="~/templates/blog/"
+ gd="./blog.json"
+ data="./posts/"
+ dk="posts"
+
+DATA
+ suti generates a single super-structure of all the data files passed to it.
+ This super-structure is executed against each "root" template.
+
+ The super-structure generated by suti will only have 1 definite key: "data"
+ (or the value of the "data-key" option). This key will overwrite any "global
+ data" keys in the root of the super-structure. Its value will be an array,
+ where each element is the resulting data structure of each parsed "data"
+ file.
+
+ Parsed "global data" will be written to the root of the super-structure and
+ into the root of each "data" array object. If a key within one of these
+ objects conflicts with one of the "global data" keys, then that
+ "global data" key will not be written to the object.
+
+TEMPLATES
+ All "root" template files passed to suti that have a file extension matching
+ one of the supported templating languages will be parsed and executed
+ against the super-structure generated by suti.
+
+ All "parital" templates will be parsed into any "root" templates that have a
+ file extension that match the same templating language.
+
+SUPPORTED LANGUAGES
+ Below is a list of the supported data-serialisation languages, used for
+ "data" and "global data" files.
+
+ - JSON (.json), see https://json.org/
+ - YAML (.yaml), see https://yamllint.com/
+ - TOML (.toml), see https://toml.io/
+
+ These are the currently supported templating languages, used for files
+ passed in the "root" and "partial" arguments.
+
+ - mustache (.mu, .mustache), see https://mustache.github.io/
+ - golang text/template (.tmpl, .gotmpl), see https://golang.org/pkg/text/template/
+ - golang html/template (.hmpl, .gohmpl), see https://golang.org/pkg/html/template/
+ - note that this and text/template are almost interchangable, with the
+ exception that html/template will produce "HTML output safe against code
+ injection".
+ - statix (.stx .statix), see https://gist.github.com/plugnburn/c2f7cc3807e8934b179e
+
+EXAMPLES
+ // TODO
+
+LIBRARIES
+ As stated above, all of these libraries do the hard work, suti just combines
+ it all together - so thanks to the authors. Also here for reference.
+
+ - The Go standard library is used for parsing JSON, .tmpl/.gotmpl, .hmpl/.gohmpl
+ // ...
+
+SEE ALSO
+ suti-lib(1)
+
+AUTHORS
+ - gearsix <gearsix@tuta.io>
+\ No newline at end of file
diff --git a/suti.txt b/suti.txt
@@ -1,127 +0,0 @@
-// FIRST-DRAFT
-
-NAME
- suti - simple unified templating interface
-
-USAGE
- suti [OPTIONS]
-
-DESCRIPTION
- suti aims to provide a universal interface for executing data files,
- written in any data-serialization language, against template files,
- written in any templating languages.
- Ideally suti will support any language you want to use.
-
- suti works by using various libraries that do all the hard work to
- parse data and template files passed to it. It generates a data
- structure of all the passed data files combined (a super-data
- structure) and executes that structure against a set of root template
- files.
- The used libraries are listed below for credit/reference.
-
- suti can also be imported as a golang package to be used as a library.
- See suti-lib for details.
-
-OPTIONS
- -r path, -root path
- path of template file to execute against.
-
- -p path..., -partial path...
- path of (multiple) template files that are called upon by at least one
- root template. If a directory is passed then all files within that
- directory will (recursively) be loaded.
-
- -gd path..., -global-data path...
- path of (multiple) data files to load as "global data". If a directory is
- passed then all files within that directory will (recursively) be loaded.
-
- -d path..., -data path...
- path of (multiple) data files to load as "data". If a directory is passed
- then all files within that directory will (recursively) be loaded.
-
- -dk name, -data-key name
- set the name of the key used for the generated array of data (default:
- "data")
-
- -sd attribute, -sort-data attribute
- The file attribute to order data files by. If no value is provided, the data
- will be provided in the order it's loaded.
- Accepted values: "filename", "modified".
- A suffix can be appended to each value to set the sort order: "-asc" (for
- ascending), "-desc" (for descending). If not specified, this defaults to
- "-asc".
- -cfg file, -config file
- A data file to provide default values for the above options (see CONFIG).
-
-CONFIG
- It's possible you'll want to set the same options if you run suti multiple
- times for the same project. This can be done by creating a file (written as
- a data file) and passing the filepath to the -cfg argument.
-
- The key names for the options set in the config file must match the name of
- the argument option to set (long or short). For example (a config file in
- toml):
-
- root="~/templates/blog.mst"
- partial="~/templates/blog/"
- gd="./blog.json"
- data="./posts/"
- dk="posts"
-
-DATA
- suti generates a single super-structure of all the data files passed to it.
- This super-structure is executed against each "root" template.
-
- The super-structure generated by suti will only have 1 definite key: "data"
- (or the value of the "data-key" option). This key will overwrite any "global
- data" keys in the root of the super-structure. Its value will be an array,
- where each element is the resulting data structure of each parsed "data"
- file.
-
- Parsed "global data" will be written to the root of the super-structure and
- into the root of each "data" array object. If a key within one of these
- objects conflicts with one of the "global data" keys, then that
- "global data" key will not be written to the object.
-
-TEMPLATES
- All "root" template files passed to suti that have a file extension matching
- one of the supported templating languages will be parsed and executed
- against the super-structure generated by suti.
-
- All "parital" templates will be parsed into any "root" templates that have a
- file extension that match the same templating language.
-
-SUPPORTED LANGUAGES
- Below is a list of the supported data-serialisation languages, used for
- "data" and "global data" files.
-
- - JSON (.json), see https://json.org/
- - YAML (.yaml), see https://yamllint.com/
- - TOML (.toml), see https://toml.io/
-
- These are the currently supported templating languages, used for files
- passed in the "root" and "partial" arguments.
-
- - mustache (.mu, .mustache), see https://mustache.github.io/
- - golang text/template (.tmpl, .gotmpl), see https://golang.org/pkg/text/template/
- - golang html/template (.hmpl, .gohmpl), see https://golang.org/pkg/html/template/
- - note that this and text/template are almost interchangable, with the
- exception that html/template will produce "HTML output safe against code
- injection".
- - statix (.stx .statix), see https://gist.github.com/plugnburn/c2f7cc3807e8934b179e
-
-EXAMPLES
- // TODO
-
-LIBRARIES
- As stated above, all of these libraries do the hard work, suti just combines
- it all together - so thanks to the authors. Also here for reference.
-
- - The Go standard library is used for parsing JSON, .tmpl/.gotmpl, .hmpl/.gohmpl
- // ...
-
-SEE ALSO
- suti-lib(1)
-
-AUTHORS
- - gearsix <gearsix@tuta.io>
