Document .Bk and .Ek; reminded by kristaps@.

[mandoc.git] / mdoc.7

diff --git a/mdoc.7 b/mdoc.7
index c52dae19b796c4dee4c7f4183eb1d72bff8b697f..deee615adba919dd1af8f03c41e565135b904363 100644 (file)
--- a/mdoc.7
+++ b/mdoc.7
@@ -1,4 +1,4 @@
-.\"    $Id: mdoc.7,v 1.125 2010/06/12 10:09:19 kristaps Exp $
+.\"    $Id: mdoc.7,v 1.127 2010/06/27 13:30:51 schwarze Exp $
 .\"
 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@bsd.lv>
 .\"
@@ -14,7 +14,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 12 2010 $
+.Dd $Mdocdate: June 27 2010 $
 .Dt MDOC 7
 .Os
 .Sh NAME
@@ -1094,10 +1094,7 @@ As a scaling unit following the syntax described in
 As the calculated string length of the opaque string.
 .El
 .Pp
-If unset, it will revert to the value of
-.Ar 8n
-as described in
-.Sx Scaling Widths .
+If not provided an argument, it will be ignored.
 .It Fl compact
 Do not assert a vertical space before the block.
 .It Fl file Ar file
@@ -1119,6 +1116,25 @@ and
 .Sx \&Dl .
 .Ss \&Bf
 .Ss \&Bk
+Begins a keep block, containing a collection of macros or text
+to be kept together in the output.
+One argument is required; additional arguments are ignored.
+Currently, the only argument implemented is
+.Fl words ,
+requesting to keep together all words of the contained text
+on the same output line.
+A
+.Fl lines
+argument to keep together all lines of the contained text
+on the same page has been desired for a long time,
+but has never been implemented.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Bk \-words
+\&.Op o Ar output_file
+\&.Ek
+.Ed
 .Ss \&Bl
 Begins a list composed of one or more list entries.
 A list is associated with a type, which is a required argument.
@@ -1592,6 +1608,8 @@ and
 .Ss \&Ed
 .Ss \&Ef
 .Ss \&Ek
+Ends a keep context started by
+.Sx \&Bk .
 .Ss \&El
 Ends a list context started by
 .Sx \&Bl .
@@ -2169,11 +2187,8 @@ Heirloom troff, the other significant troff implementation accepting
 .Pp
 .Bl -dash -compact
 .It
-groff supports a
-.Fl file Ar filename
-argument to
-.Sx \&Bd .
-mandoc does not.
+Old groff fails to assert a newline before
+.Sx \&Bd Fl ragged compact .
 .It
 groff behaves inconsistently when encountering
 .Pf non- Sx \&Fa
@@ -2249,16 +2264,15 @@ In quoted literals, groff allowed pair-wise double-quotes to produce a
 standalone double-quote in formatted output.
 This idiosyncratic behaviour is not applicable in mandoc.
 .It
-Display types
+Display offsets
 .Sx \&Bd
-.Fl center
+.Fl offset Ar center
 and
-.Fl right
-are aliases for
-.Fl left
-in mandoc.  Furthermore, the
+.Fl offset Ar right
+are disregarded in mandoc.
+Furthermore, the
 .Fl file Ar file
-argument is ignored.
+argument is not supported in mandoc.
 Lastly, since text is not right-justified in mandoc (or even groff),
 .Fl ragged
 and