First iteration of py skaldpress version

1 files changed, 96 insertions, 0 deletions

diff --git a/skaldpress.1 b/skaldpress.1
new file mode 100644
index 0000000..5ed2046
--- /dev/null
+++ b/skaldpress.1
@@ -0,0 +1,96 @@
+.TH SKALDPRESS 1 2024-06-08
+.SH name
+Skaldpress \- Templating engine
+.SH SYNOPSIS
+.B skaldpress [OPTIONS]
+
+.SH DESCRIPTION
+.B smp
+smp is a macro processor, made specifically for a usecase when doing templating of websites.
+
+
+Macros which are available using skaldpress, in addition to the builtin smp(1)-macros
+.IP "\fBtemplate(<template>,<content>)\fR"
+Will process the content using a template, in-place.
+This macro is used by the \fBall_tagged_by\fR-macro.
+
+.IP "\fBall_tagged_by(<tag_name>,<template>[,<field to sort by>][,<reversed>])\fR"
+Will output all documents which had the specified tag, using the specified template.
+If a field to sort by is specified, it will output ascending based on that field,
+or reversed if a fourth argument \fBreversed\fR is specified.
+
+.PP
+All input files can have a metadata-block at the beginning.
+Any keys will be defined as macros as \fBMETADATA_<key>\fR.
+There are a few special keys which has a specific effect:
+
+.IP "\fBskip_smp\fR"
+If this is \fItrue\fR, macro processing will be skipped for the file, and it will be
+included verbatim.
+
+.IP "\fBskip_build\fR"
+If this is \fItrue\fR, the file will not be written to build-dir, but it will be compiled and available for macros like \fBall_tagged_by\fR.
+
+.IP "\fBtags\fR"
+This is a list, and all files with entries here will be registered during the first compilation round.
+During the second compilation, macros like \fBall_tagged_by\fR will then
+make all files with the relevant content available and compile it in.
+
+.IP "\fBtarget_filename\fR"
+By default, a file will have the same name in the \fIoutput\fR-directory (unless a template has a different extension).
+This overrides the output-filename, but it keeps the file in the same directory, and it will not affect the extension.
+
+.IP "\fBtemplate\fR"
+If specified, the file will be compiled using a template.
+In the template, all \fBMETADATA_<key>\fR macros will be available,
+additionally templates can use the \fBCONTENT\fR-macro to get the expanded content of the file.
+This is recursive, meaning that templates can use other templates, with their own metadata-block,
+since it is recursive, any metadata in templates will overwrite any metadata from their children, 
+but will keep metadata that is not overwritten.
+This means templates can add additional context.
+
+.IP "\fBkeep_states\fR"
+List or string where every listed state/variable will be kept for subsequenct compilations.
+Meaning that you can e.g. construct a array in the first compilation, which is then used the second time around.
+Setting this, means that the file will always be recompiled, regardeless of other instances (unless a \fB--filter\fR is set).
+
+.SH OPTIONS
+.IP "\fB-o, --out, --output\fR \fIpath\fR
+Specifies the directory to output the compiled files to, defaults to \fIbuild\fR.
+
+.IP "\fB-i, --input\fR \fIpath\fR
+Specifies the directory where all files are iterated, defaults to \fIcontent\fR.
+
+.IP "\fB-s, --static\fR \fIpath\fR
+Specifies the directory where all files are iterated, defaults to \fIcontent\fR.
+
+.IP "\fB-t, --templates\fR \fIpath\fR
+Specifies the directory where templates are stored, defaults to \fItemplates\fR.
+
+.IP "\fB-f, --filter\fR \fIfilter\fR
+Comma-separated list of files to compile, if not specified, all files in \fB--source\fR
+will be compiled.
+
+.IP "\fB-e, --exclude\fR \fIfilter\fR
+Comma-separated list of files to exclude, if not specified, all files in \fB--source\fR
+will be compiled.
+
+.IP "\fB-m, --metadata\fR \fIkey\fR=\fIvalue\fR
+Metadata to add to compiled file, this can e.g. set a template for all files if you don't want to manually add YAML-blocks.
+Specify multiple times, to set multiple fields.
+
+.SH EXAMPLES
+
+To run skaldpress on a simple project, simply call it with no arguments
+in a directory where you have a \fBcontent\fR-directory,
+and optionally a \fBtemplates\fR-directory.
+.PP
+.nf
+.RS
+skaldpress
+.RE
+.fi
+.PP
+
+.SH SEE ALSO
+smp(1)