From ed6d3372fe33dbf964b0c179453526f3682389b7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?John=20Ankarstr=C3=B6m?= <john@ankarstrom.se>
Date: Mon, 21 Jun 2021 00:03:53 +0200
Subject: example.t: Document w

---
 example.pdf | Bin 81600 -> 81347 bytes
 example.t   | 107 +++++++++++++++++++++++++++++++++++++-----------------------
 2 files changed, 67 insertions(+), 40 deletions(-)

diff --git a/example.pdf b/example.pdf
index 7f8683f..0fab32c 100644
Binary files a/example.pdf and b/example.pdf differ
diff --git a/example.t b/example.t
index 650808d..29f0452 100644
--- a/example.t
+++ b/example.t
@@ -35,7 +35,8 @@
 .t
 .x Mg ,
 a simple macro package for troff
-.d John\ Ankarstr\(:om
+.d \&
+John Ankarstr\(:om
 .d
 .
 .
@@ -249,7 +250,8 @@ There is a large group of macros that provide
 block-level formatting:
 .n 1
 .c d ,
-centered date (or given string)
+centered date (or given string, or nothing, if given
+.c \\\\& )
 .n
 .c h ,
 heading
@@ -275,8 +277,10 @@ to create a centered header:
 .l
 \&.t
 Document title
-\&.d "First author"
-\&.d "Second author"
+\&.d \\&
+First author
+\&.d \\&
+Second author
 \&.d \\" current date
 .p
 Here, you can see that the
@@ -287,30 +291,19 @@ macro may be used for other things than dates.
 Other macros
 .p
 Finally, there are a few macros
-that belong to neither category.
+that belong to neither category:
 .n 1
-.c q ,
-quotation
-.n
 .c ( ,
 begin footnote
 .n
 .c ) ,
 end footnote
-.p
-By default,
-.c q
-behaves like an inline macro,
-surrounding text in quotation marks,
-but if no arguments are given to it,
-it starts an indented block quotation instead:
-.l
-.ne 2
-\&.q
-This is an indented quotation.
-\&.p
-This is an inline
-\&.q quotation .
+.n
+.c q ,
+quotation
+.n
+.c w ,
+want space
 .p
 The footnote macros
 .c (
@@ -340,6 +333,42 @@ pushes the place where it is referenced to the next page.
 In such cases, the reference will simply appear on the page
 following the footnote.
 When this happens, the user must account for it manually.
+.p
+The
+.c q
+behaves like an inline macro by default,
+surrounding text in quotation marks,
+but if no arguments are given to it,
+it starts an indented block quotation instead:
+.l
+.ne 2
+\&.q
+This is an indented quotation.
+\&.p
+This is an inline
+\&.q quotation .
+.p
+The
+.c w
+macro is a wrapper around troff's
+.c ne ,
+which ensures that a given amount of space is available on the page
+\(em otherwise, a line break is issued \(em
+but unlike
+.c ne ,
+which takes an exact amount of space as its argument,
+.c w
+takes a declarative specification
+describing the amount of space desired
+in terms of
+.i mg
+environments.
+For example:
+.l
+\\" want space for...
+\&.w s p \\" a subheading of one line + a paragraph of one line
+\&.w s pp \\" a subheading of one line + a paragraph of two lines
+\&.w ss p \\" a subheading of two lines + a paragraph of one line
 .
 .
 .h
@@ -401,6 +430,7 @@ How do I customize the default appearance of a given environment?
 To configure the layout and font settings of a specific environment,
 you can switch to that environment and use the relevant troff requests:
 .l
+.ne 1
 \&.q
 \&.ps +1p
 .p
@@ -413,12 +443,14 @@ macro:
 \&._e q
 \&.ps +1p
 .
+.w s ll
 .s
 How do I customize the default appearance of the margin text?
 .l
 \&._E _m \\" margin environment
 \&.ps +1p
 .
+.w s ll
 .s
 How do I customize the default appearance of footnotes?
 .l
@@ -437,24 +469,19 @@ The user is recommended to use troff's
 .c ne
 request:
 .l
-\&.l
-\&.ne 3
-int
-main(int argc, char *argv[])
-{
-.p
-The request
-.c ne\ 3
-tells troff that it needs three lines of vertical space.
-If it finds that there is not enough space on the current page,
-it will issue a page break.
-While this is not a
-.i general
-solution to the problem,
-as you need to manually count how many lines are needed,
-troff itself is not a general solution to the problem of typesetting;
-in fact, such a solution likely does not exist.
-At the end of the day, all good typesetting requires manual care.
+\&.q
+\&.ne 7
+Four score and seven years ago...
+.p
+In some cases,
+.i mg 's
+own
+.c w
+macro may be useful:
+.l
+\&.w qqqqqqq
+\&.q
+Four score and seven years ago...
 .
 .s
 How do I define my own environments?
-- 
cgit v1.2.3