From a405b616fc3d1f01254bd632db4f2af1d618ef76 Mon Sep 17 00:00:00 2001
From: Kristaps Dz <kristaps@bsd.lv>
Date: Sun, 24 Nov 2024 22:53:35 -0800
Subject: [PATCH] Add some manpage bits for ongoing progress.

---
 man/lowdown.1 | 117 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 117 insertions(+)

diff --git a/man/lowdown.1 b/man/lowdown.1
index 48a4a18..2a80787 100644
--- a/man/lowdown.1
+++ b/man/lowdown.1
@@ -757,6 +757,123 @@ for the
 .Li section ,
 are not set as metadata values, and will not appear if the metadata key
 is used as a variable.
+.Ss Templates
+Some output modes accept a template
+.Pq Fl -template
+to customise standalone
+.Pq Fl s
+output.
+Parsed input content is filled into templates through control statements
+that support conditionals, loops, and transformation sequences.
+.Pp
+Templates control statements are delimited as
+.Li $statement$
+or
+.Li ${statement} .
+Arbitrary white-space may surround the statement between matching
+delimiters.
+Empty statements are stripped, with the exception of
+.Li $$ ,
+which outputs a literal
+.Li $ .
+Statements without a closing delimiter are considered opaque text.
+.Pp
+The following statements are available:
+.Bl -tag -width Ds
+.It Li $ifdef(expression)$
+Conditional statement.
+There may not be any white-space between the
+.Li ifdef
+and the opening parenthesis.
+Begins a block that is ended by a
+.Li else ,
+.Li endif ,
+or the end of file.
+Its contents are output only if
+.Li expression
+evaluates to a non-empty string.
+.It Li $else$
+Begins a block that is ended by a
+.Li endif
+or end of file.
+Its contents are output only if the condition of a 
+preceding
+.Li ifdef
+evaluates to an empty string.
+An
+.Li else
+without a preceding
+.Li ifdef
+is not output.
+.It Li $endif$
+Closes a block begin with
+.Li ifdef
+or
+.Li else .
+If not preceded by one of those statements, is silently ignored.
+.It Li $for(expression)$
+Looping statement.
+There may not be any white-space between the
+.Li for
+and the opening parenthesis.
+Begins a block that is ended by an
+.Li endfor
+or the end of file.
+Block contents contents are repeatedly output for each list item
+evaluated from
+.Li expression .
+The anaphoric keyword
+.Li this
+may be used to access the current loop expression within the block.
+.It Li $expression$
+Replaced by the result of evaluating a template expression.
+.El
+.Pp
+Expressions consist of
+.Li initial[.transform]* ,
+with
+.Li initial
+being a metadata key,
+.Li this
+.Pq value of a current loop context ,
+or
+.Li body
+.Pq parsed input document body .
+.Pp
+If a metadata key is not specified in the input, or if the anaphoric
+.Li this
+has not initialised by a looping context, the initial value evaluates to an
+empty list.
+The initial value is optionally followed by a series of transformations.
+.Pp
+Expressions are represented by lists of non-empty strings, with
+.Li initial
+being a singleton list.
+Singletons are expanded for use in
+.Li for
+loops by using the
+.Li split
+transformation.
+.Pp
+The following transformations are available:
+.Bl -tag -width Ds
+.It Li lowercase
+Lowercase all list items.
+.It Li uppercase
+Uppercase all list items.
+.It Li split
+Split list items on sequences of two or more white-space tokens (space,
+newline, tab).
+This is usually invoked on a singleton, but may be repeatedly invoked on
+a pre-split list.
+Invokes
+.Li trim
+prior to the first split.
+The resulting list has no items that are only white-space.
+.It Li trim
+Trim white-space from the beginning and end of all list items.
+If an item has no non-white-space, it is discarded.
+.El
 .Sh ENVIRONMENT
 .Bl -tag -width Ds
 .It Ev NO_COLOR