commit 8014ab9d4ff4f4467668c0e3318327bcc7ef6633
Author: gearsix <gearsix@tuta.io>
Date: Wed, 10 Feb 2021 20:47:10 +0000
git init; added man1 .txt spec
Diffstat:
| A | suti.txt | | | 121 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
1 file changed, 121 insertions(+), 0 deletions(-)
diff --git a/suti.txt b/suti.txt
@@ -0,0 +1,121 @@
+// FIRST-DRAFT
+
+NAME
+ suti - simple unified templating interface
+
+USAGE
+ suti [OPTIONS]
+
+DESCRIPTION
+ suti aims to provide a universal interface for executing data (written in
+ any supported data-serialisation language) against any template file
+ (written in any of the supported templating languages). Ideally suti
+ supports any language you want to use.
+
+ suti works by using various libraries that do all the hard work to generate
+ a data structure of your combined data files and then executes that
+ structure against a set of templates, generated by parsing the passed
+ template files. These 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
+ -t path..., -template path...
+ path of (multiple) template files to execute against. If a directory is
+ passed then all files within that directory will (recursively) be loaded.
+
+ -gd path..., -globaldata 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, -datakey name
+ set the name of the key used for the generated array of data (default:
+ "data")
+
+ -sd attribute, -sortdata attribute
+ The attribute to set the order to load data files. Accepted values:
+ "filename", "modified". (default: "filename"). A suffix can be appended
+ to each value to set the sort order: "-asc" (for ascending), "-desc"
+ (for descending). By default, the sort order will be descending. See
+ EXAMPLES.
+
+ -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), see EXAMPLES.
+
+DATA
+ suti generates a single super-structure of all the data files passed to it
+ (that have a recognised data file extension). This array will be sorted by
+ the value of the "sortdata" option. The super-structure is executed
+ against each root template (see TEMPLATES).
+
+ The super-structure generated by suti will only have 1 definite key: "data"
+ (or the value of the "datakey" option). This key will overwrite any global
+ keys in the root of the super-structure and its value will be an array,
+ where each element is the data structure parsed from each data file passed
+ in the "data" option.
+
+ "global data" passed to suti will be parsed to the root of the
+ super-structure and also into each object of the generated "data" array.
+ These keys will be overwritten if they overlap with any keys in the "data"
+ structures or by the set "datakey" value in the root of the generated
+ super-structure.
+
+TEMPLATES
+ All 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. A "root template" is defined as any
+ templates that are not called in by another template as a "partial".
+
+ // discuss combining templates of different languages ? - see how impl. works out first
+
+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/
+
+ templating languages:
+ - 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
+ Writing a config file is very simple, here's one called "suti.toml":
+
+ template="~/templates/blog.mst"
+ d="./blogs/cat-memes/"
+ sd="modified-desc"
+ dk="content"
+
+ // TODO more
+
+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.
+
+ // ...
+
+SEE ALSO
+ suti-lib(1)
+
+AUTHORS
+ - gearsix <gearsix@tuta.io>
