===================================================================
RCS file: /cvs/mandoc/roff.7,v
retrieving revision 1.100
retrieving revision 1.105
diff -u -p -r1.100 -r1.105
--- mandoc/roff.7	2018/08/18 21:37:01	1.100
+++ mandoc/roff.7	2018/08/25 16:53:39	1.105
@@ -1,4 +1,4 @@
-.\"	$Id: roff.7,v 1.100 2018/08/18 21:37:01 schwarze Exp $
+.\"	$Id: roff.7,v 1.105 2018/08/25 16:53:39 schwarze Exp $
 .\"
 .\" Copyright (c) 2010, 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2010-2018 Ingo Schwarze <schwarze@openbsd.org>
@@ -15,7 +15,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: August 18 2018 $
+.Dd $Mdocdate: August 25 2018 $
 .Dt ROFF 7
 .Os
 .Sh NAME
@@ -507,9 +507,16 @@ This is a groff extension and currently ignored.
 .It Ic \&ch Ar macroname Op Ar dist
 Change a trap location.
 Currently ignored.
-.It Ic \&char Ar glyphname Op Ar string
-Define a new glyph.
-Currently unsupported.
+.It Ic \&char Ar glyph Op Ar string
+Define or redefine the ASCII character or character escape sequence
+.Ar glyph
+to be rendered as
+.Ar string ,
+which can be empty.
+Only partially supported in
+.Xr mandoc 1 ;
+may interact incorrectly with
+.Ic \&tr .
 .It Ic \&chop Ar stringname
 Remove the last character from a macro, string, or diversion.
 Currently unsupported.
@@ -634,6 +641,8 @@ produces
 in the input stream, and thus in the output: \fI\^XtFree\^\fP.
 Each occurrence of \e\e$* is replaced with all the arguments,
 joined together with single space characters.
+The variant \e\e$@ is similar, except that each argument is
+individually quoted.
 .Pp
 Since macros and user-defined strings share a common string table,
 defining a macro
@@ -1005,13 +1014,13 @@ is
 or
 .Sq o
 .Pq odd page ,
-it evaluates to true.
+it evaluates to true, and the
+.Ar body
+starts with the next character.
 .It
 If the first character of
 .Ar condition
 is
-.Sq c
-.Pq character available ,
 .Sq e
 .Pq even page ,
 .Sq t
@@ -1019,11 +1028,24 @@ is
 or
 .Sq v
 .Pq vroff mode ,
-it evaluates to false.
+it evaluates to false, and the
+.Ar body
+starts with the next character.
 .It
 If the first character of
 .Ar condition
 is
+.Sq c
+.Pq character available ,
+it evaluates to true if the following character is an ASCII character
+or a valid character escape sequence, or to false otherwise.
+The
+.Ar body
+starts with the character following that next character.
+.It
+If the first character of
+.Ar condition
+is
 .Sq d ,
 it evaluates to true if the rest of
 .Ar condition
@@ -1187,7 +1209,7 @@ While evaluating the
 the unit suffixes described below
 .Sx Scaling Widths
 are ignored.
-.It Ic \&it Ar expression macro
+.It Ic \&itc Ar expression macro
 Set an input line trap, not counting lines ending with \ec.
 Currently unsupported.
 .It Ic \&IX Ar class keystring
@@ -1457,8 +1479,8 @@ Currently ignored.
 Set the maximum stack depth for recursive macros.
 This is a Heirloom extension and currently ignored.
 .It Ic \&return Op Ar twice
-Exit a macro and return to the caller.
-Currently unsupported.
+Exit the presently executed macro and return to the caller.
+The argument is currently ignored.
 .It Ic \&rfschar Ar font glyph ...
 Remove font-specific fallback glyph definitions.
 Currently unsupported.
@@ -1507,8 +1529,11 @@ This is a Heirloom extension and currently ignored.
 Change the soft hyphen character.
 Currently ignored.
 .It Ic \&shift Op Ar number
-Shift macro arguments.
-Currently unsupported.
+Shift macro arguments
+.Ar number
+times, by default once: \e\e$i becomes what \e\e$i+number was.
+Also decrement \en(.$ by
+.Ar number .
 .It Ic \&sizes Ar size ...
 Define permissible point sizes.
 This is a groff extension and currently ignored.
@@ -1697,8 +1722,12 @@ This is a Heirloom extension and currently ignored.
 Set a page location trap.
 Currently unsupported.
 .It Ic \&while Ar condition body
-Repeated execution while a condition is true.
-Currently unsupported.
+Repeated execution while a
+.Ar condition
+is true, with syntax similar to
+.Ic \&if .
+Currently implemented with two restrictions: cannot nest,
+and each loop must start and end in the same scope.
 .It Ic \&write Oo \(dq Oc Ns Ar string
 Write to an open file.
 Ignored because insecure.
@@ -1825,6 +1854,9 @@ Discard the rest of the physical input line and contin
 input line on the next physical input line, joining the text on
 both lines together as if it were on a single input line.
 This is a groff extension.
+.Ss \e$ Ns Ar arg
+Macro argument expansion, see
+.Sx de .
 .Ss \e%
 Hyphenation allowed at this point of the word; ignored by
 .Xr mandoc 1 .
@@ -2128,10 +2160,6 @@ macro control character does not suppress output line 
 .It
 Diversions are not implemented,
 and support for traps is very incomplete.
-.It
-While recursion is supported,
-.Sx \&while
-loops are not.
 .El
 .Pp
 The special semantics of the