===================================================================
RCS file: /cvs/mandoc/roff.7,v
retrieving revision 1.10
retrieving revision 1.14
diff -u -p -r1.10 -r1.14
--- mandoc/roff.7	2010/06/26 15:22:19	1.10
+++ mandoc/roff.7	2010/07/27 13:16:00	1.14
@@ -1,6 +1,7 @@
-.\"	$Id: roff.7,v 1.10 2010/06/26 15:22:19 kristaps Exp $
+.\"	$Id: roff.7,v 1.14 2010/07/27 13:16:00 kristaps Exp $
 .\"
 .\" Copyright (c) 2010 Kristaps Dzonsons <kristaps@bsd.lv>
+.\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org>
 .\"
 .\" Permission to use, copy, modify, and distribute this software for any
 .\" purpose with or without fee is hereby granted, provided that the above
@@ -14,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: June 26 2010 $
+.Dd $Mdocdate: July 27 2010 $
 .Dt ROFF 7
 .Os
 .Sh NAME
@@ -91,11 +92,29 @@ The syntax of this macro is the same as that of
 except that a leading argument must be specified.
 It is ignored, as are its children.
 .Ss \&ds
-Define a string.
-This macro is intended to have two arguments,
-the name of the string to define and its content.
-Currently, it is ignored including its arguments,
-and the number of arguments is not checked.
+Define a reserved word.
+Its syntax is as follows:
+.Pp
+.D1 Pf \. Sx \&ds No Cm key val
+.Pp
+The
+.Cm key
+and
+.Cm val
+strings are space-separated.
+The
+.Cm key
+values may be invoked in subsequent text by using \e*(NN for two-letter
+pairs, \e*N for one-letter, and \e*[NNN] for arbitrary-length values.
+.Pp
+If
+.Cm val
+is begun with a double-quote mark, the mark is passed over.
+.Cm val
+consists of
+.Em all
+text following this point, including whitespace and trailing
+double-quotes.
 .Ss \&de1
 The syntax of this macro is the same as that of
 .Sx \&ig ,
@@ -289,12 +308,15 @@ requests are recognised:
 .It Cm nS
 If set to a positive integer value, certain
 .Xr mdoc 7
-macros will behave as if they are defined in the
+macros will behave as if they were defined in the
 .Em SYNOPSIS
-section to a manual.
+section.
 Otherwise, this behaviour is unset (even if called within the
 .Em SYNOPSIS
 section itself).
+Note that invoking a new
+.Xr mdoc 7
+section will unset this value.
 .El
 .Ss \&tr
 Output character translation.