* stream.c (vformat): Implement ~! format directive for indentation.

Allow negative widths to be specified with a leading minus sign,
so that we can indent to the left.

* txr.1: Document ~! format directive.

1 files changed, 35 insertions, 3 deletions

diff --git a/txr.1 b/txr.1
index 327e4947..78893dc8 100644
--- a/txr.1
+++ b/txr.1
@@ -26887,13 +26887,14 @@ this field. If the
 character is present, the printing will be centered within the field.
 Otherwise it will be right-adjusted by default.
 
-The width can be specified as a decimal integer, or as the character
+The width can be specified as a decimal integer with an optional leading
+minus sign, or as the character
 .codn * .
 The
 .code *
 notation means that instead of digits, the value of the next argument is
-consumed, and expected to be an integer which specifies the width. If that
-integer value is negative, then the field will be left-adjusted.
+consumed, and expected to be an integer which specifies the width. If the
+width, specified either way, is negative, then the field will be left-adjusted.
 If the value is positive, but either the
 .code <
 or
@@ -27090,6 +27091,37 @@ of \*(TX.  If the object is a pointer to heaped data, that value
 has a correspondence to its address.
 .RE
 
+.coIP !
+The
+.code !
+directive establishes hanging indentation, and turns on the stream's
+indentation mode. Subsequent lines printed within the execution of the
+same
+.code format
+call will be automatically indented. If no width is specified, then
+the directive sets the hanging indentation to the current printing
+column position. If a width is specified, then it represents an offset
+(positive or negative). If the
+.code <
+prefix character is present, the hanging indentation is set to the
+specified offset relative to the current printing column.
+If the
+.code <
+prefix is present on the width field, then the offset is applied
+relative to the indentation which was saved on entry into the
+.code format
+function.
+
+The indentation mode and indentation column are automatically restored to their
+previous values when
+.code format
+function terminates, naturally or via an exception or non-local jump.
+
+The effect of a precision field (even if zero) combined with the
+.code !
+directive is currently not specified, and reserved for future extension.
+The precision field is processed syntactically, and no error occurs, however.
+
 .PP
 
 .coNP Functions @, print @, pprint @, prinl @, pprinl @ tostring and @ tostringp