From e5c14ab3ff2622315235bd6b64eb5a8c9da00a5f Mon Sep 17 00:00:00 2001 From: Qrius Date: Wed, 30 Apr 2025 21:02:51 +0200 Subject: Update man pages, remove unused parameter --- skaldpress.1 | 41 +++++------------ smp.1 | 108 ++++++++++++++++++++++++++++++++++----------- src/skaldpress/main.py | 3 -- src/smp/macro_processor.py | 4 ++ 4 files changed, 99 insertions(+), 57 deletions(-) diff --git a/skaldpress.1 b/skaldpress.1 index a0cf224..d274b1c 100644 --- a/skaldpress.1 +++ b/skaldpress.1 @@ -6,7 +6,8 @@ Skaldpress \- Templating engine .SH DESCRIPTION .B smp -smp is a macro processor, made specifically for a usecase when doing templating of websites. +is a macro processor, made specifically for a usecase when doing templating of websites. +But it is useful for many other things as well. Macros which are available using skaldpress, in addition to the builtin smp(1)-macros @@ -16,34 +17,6 @@ Will output all documents which had the specified tag, using the specified templ 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_\fR. -There are a few special keys which has a specific effect: - -.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_\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. @@ -65,10 +38,20 @@ will be compiled. Comma-separated list of files to exclude, if not specified, all files in \fB--source\fR will be compiled. +.IP "\fB-x, --xclude\fR \fIfilter\fR +Comma-separated list of static files to exclude, if not specified, all files in \fB--static\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. +.IP "\fB-D, --define\fR \fIkey\fR=\fIvalue\fR +Define macros, these will be interpreted as strings. + +.IP "\fB-P, --prefix-builtins\fR +Prefix all builtin macros with `smp_` + .SH EXAMPLES To run skaldpress on a simple project, simply call it with no arguments diff --git a/smp.1 b/smp.1 index 1b616e4..33a96dc 100644 --- a/smp.1 +++ b/smp.1 @@ -2,7 +2,7 @@ .SH name Skaldpress Macro Processor \- Macro processor .SH SYNOPSIS -.B smp [\fIinput_file\fB] +.B smp [OPTION]... [\fIinput_file\fB] .SH DESCRIPTION .B smp @@ -22,6 +22,9 @@ This defines a macro, optionally with some content. The optional content will be expanded immediately, and later the already processed content will be included in the output. +.IP "\fBundefine()\fR" +Delete the macro. + .IP "\fBifdef(, [, ])\fR" .IP "\fBifndef(, [, ])\fR" @@ -33,6 +36,9 @@ and later the already processed content will be included in the output. .IP "\fBshell()\fR" Runs command on shell, and includes the command output in the output +.IP "\fBeval()\fR" +Run a python command, write return value to output. + .IP "\fBexpr(, , ..., )\fR" Shorthand for running the expr command, expands all arguments, and executes it on the shell. @@ -63,43 +69,95 @@ It will process it's input twice before actually doing the conversion. This is t So you should probably always quote arguments to this. .IP "\fBwodl()\fR" -If compiled with \fBdeadlinks\fR, this macro will always return it's argument. +This macro will always return it's argument. But it will also perform a request to the link, and emit a warning if it it doesn't return HTTP 200 OK. This will significantly slow down compile times! -.SS "\fBCompile-Time Feature Flags\fR" -There are some compile-time flags that can enable/disable features, most are enabled by default, -and exist either because they trigger a external dependency, or because they are unlikely to work without glibc. +.IP "\fBtemplate(, )\fR" +Will read the file in \fIfilename\fR, and process it replacing \fBCONTENT\fR with the \fIcontent\fR. + +.IP "\fBiftruthy()\fR" +Returns python True if content is evaluated to \fItruthy\fR. + +.IP "\fBindent(, )\fR" +Indents each line of the \fIcontent\fR with \fIspaces\R spaces. + +.IP "\fBdumpenv\fR" +Debugging macro for printing smp internals. + +.SS "\fBSpecial macros\fR" +There is a syntax for special macros, which takes more data in once. + +.IP "\fB@template \fI