diff options
Diffstat (limited to 'smp.1')
| -rw-r--r-- | smp.1 | 108 |
1 files changed, 83 insertions, 25 deletions
@@ -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(<macro_name>)\fR" +Delete the macro. + .IP "\fBifdef(<macro_name>, <output if defined> [, <output if not defined>])\fR" .IP "\fBifndef(<macro_name>, <output if not defined> [, <output if defined>])\fR" @@ -33,6 +36,9 @@ and later the already processed content will be included in the output. .IP "\fBshell(<command>)\fR" Runs command on shell, and includes the command output in the output +.IP "\fBeval(<python>)\fR" +Run a python command, write return value to output. + .IP "\fBexpr(<arg1>, <arg2>, ..., <argN>)\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(<url>)\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(<filename>, <content>)\fR" +Will read the file in \fIfilename\fR, and process it replacing \fBCONTENT\fR with the \fIcontent\fR. + +.IP "\fBiftruthy(<content>)\fR" +Returns python True if content is evaluated to \fItruthy\fR. + +.IP "\fBindent(<spaces>, <content>)\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<template>\fR" +Passes the rest of the file as content to the \fBtemplate\fR-macro. + +.IP "\fB@html_from_markdown\fR" +Passes the rest of the file as content to the \fBhtml_from_markdown\fR-macro. -.IP "\fBreadline\fR" 2 -\fBEnabled by default\fR. -Enables the use of libc readline in REPL mode. If not enabled, normal stdio will be used for input. -Requires readline to be installed on the system. +.SS "\fBBuiltin macro options\fR" +There are some macros flags that can enable/disable features, +They will be prefixed by `smp_` if \fB-P\fR is set. -.IP "\fBtime\fR" 2 -\fBEnabled by default\fR. -Enables the \fIformat_time\fR-macro, this will compile the chrono dependency to format time. +.IP "\fBparse_file_yaml\fR" 2 +\fB\fItruthy\fR\fB by default\fR. +If set to a truthy value, metadata blocks in the start of files will be parsed, otherwise it will be treated as normal input. -.IP "\fBmarkdown\fR" 2 -\fBEnabled by default\fR. -Enabled the \fIhtml_from_markdown\fR-macro, this will compile the markdown dependency. And can convert markdown into html. +.IP "\fBdraft\fR" 2 +\fB\fIfalsy\fR\fB by default\fR. +If set to a truthy value, some macros may skip expensive steps to save compilation time (e.g. network calls). -.IP "\fBdeadlinks\fR" 2 -\fBEnabled by default\fR. -Enabled the \fIwodl\fR-macro, this will compile the minreq dependency. -Allows testing the return code of links, and warns when the request is unsuccessful. +.IP "\fBtemplate_prefix\fR" 2 +\fB\fItemplates/\fR\fB by default\fR. +The path to search for templates in, this affects metadata wrapping, as well as macros using the template macro. -.IP "\fBguile\fR" 2 -If compiled with guile, the macro processor supports running guile-code inline. -This is enabled with \fI%()%\fR in the input, and anything inside the parantheses will be evaluated as guile. +.IP "\fBmetadata_prefix\fR" 2 +\fB\fIMETADATA_\fR\fB by default\fR. +The prefix used for defining metadata for macros defined in blocks. -Requires libguile-3.0 to be installed on the system. +.IP "\fBsmp_debug\fR" 2 +\fB\fI4\fR\fB by default\fR. +Sets the debug level for the parser, higher number means more verbosity. +Level 1 and 2 is the most basic error messaging, 5 and up will print parser internals. + +.IP "\fBsynclines\fR" 2 +\fB\fIfalsy\fR\fB by default\fR. +If truthy, synclines will be included in output, along with filename. + +.SS Metadata block +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 "\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). -\fBExperimental feature!\fR .SH OPTIONS + +.IP "\fBinput_file\fR If a input file is provided, that will be processed. -If not, a sort of interactive REPL will be started instead. +If it is `-`, or not specified and something is piped, it will process stdin. + +.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 SEE ALSO skaldpress(1) |