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>
 .\"
 .\"
 .\" 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.
 .\"
 .\" 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
 .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
 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
 .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
 .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.
 .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
 .Ss \&Ed
 .Ss \&Ef
 .Ss \&Ek

+Ends a keep context started by
+.Sx \&Bk .

 .Ss \&El
 Ends a list context started by
 .Sx \&Bl .
 .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
 .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
 .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
 standalone double-quote in formatted output.
 This idiosyncratic behaviour is not applicable in mandoc.
 .It

-Display types
+Display offsets

 .Sx \&Bd
 .Sx \&Bd

-.Fl center
+.Fl offset Ar center

 and
 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
 .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
 Lastly, since text is not right-justified in mandoc (or even groff),
 .Fl ragged
 and