[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] 39/53: doc/meref.me: Revise "Displays" section.
From: |
G. Branden Robinson |
Subject: |
[groff] 39/53: doc/meref.me: Revise "Displays" section. |
Date: |
Tue, 14 Dec 2021 01:21:59 -0500 (EST) |
gbranden pushed a commit to branch master
in repository groff.
commit fb8bff6862b97802c5eea6d2259e8b93e2e361ad
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sat Dec 11 14:22:04 2021 +1100
doc/meref.me: Revise "Displays" section.
* Expand introductory paragraph to present the naming convention.
* Undermine assumptions about display nesting behavior.
* Introduce and define "vertical spacing".
* Migrate term used for quotation displays to "long quotation",
disambiguating it from the name and function of the `q` macro.
* Move unconditional stuff near the beginning of a macro description and
conditional stuff toward the end.
* Introduce and define "block threshold" (a me(7) concept).
---
doc/meref.me | 209 ++++++++++++++++++++++++++++-------------------------------
1 file changed, 98 insertions(+), 111 deletions(-)
diff --git a/doc/meref.me b/doc/meref.me
index 75dda54..04067f3 100644
--- a/doc/meref.me
+++ b/doc/meref.me
@@ -732,23 +732,37 @@ pending floating keeps are emitted)
and of each column when in multi-column mode.
It can be used for column headings
and the like.
+.br
+.ne 9v
.sh 1 "Displays"
.pp
+Display macros enclose material;
+their names are of the form
+.b .( \c
+.bi x
+and
+.b .) \c
+.bi x ,
+and must be paired.
+Not all display types can nest
+with themselves or each other.
All displays except centered blocks
-and block quotes
+and long quotations
are preceded and followed
by an extra
.NR (bs
[same as
.NR (ps ]
-space.
-Quote spacing is stored in a separate register;
-centered blocks have no default initial or trailing space.
-The vertical spacing of all displays except quotes
-and centered blocks
-is stored in register
-.NR ($V
-instead of
+of vertical space
+and use a
+vertical spacing
+(distance between text baselines)
+of
+.NR ($V .
+Long quotation spacing is stored in a dedicated register;
+centered blocks have no pre- or post-spacing.
+They use the vertical spacing register for
+non-displayed text,
.NR ($v .
.TL
.b .(l
@@ -756,60 +770,59 @@ instead of
.i f
.DE
Begin list.
-Lists are single spaced,
-unfilled text.
-If
-.i f
-is
-.b F ,
-the list will be filled.
+Text until
+.b .)l
+is set in font
+.NR (df
+[0]
+and single-spaced
+with filling disabled.
If
.i m
[\c
.b I ]
is
-.b I
+.b I ,
the list is indented by
.NR (bi
[4m];
if
-.b M
-the list is indented to the left margin;
+.b M ,
+it is set at the left margin;
if
-.b L
-the list is left justified with respect to the text
-(different from
+.b L ,
+it is left-aligned with respect to the text
+(distinguishable from
.b M
-only if the base indent
-(stored in
+only if the base indentation\(em\c
+stored in
.NR ($i
and set with
-.b .ba )
+.b .ba \(em\c
is not zero);
and if
-.b C
+.b C ,
the list is centered on a line-by-line basis.
-The list is set in font
-.NR (df
-[0].
-Must be matched by a
-.b .)l .
-This macro is almost like
-.b .(b
-except that no attempt is made
-to keep the display on one page.
+If
+.i f
+is
+.b F ,
+filling is enabled.
.TL
.b .)l
.DE
End list.
+.br
+.ne 4v
.TL
.b .(q
.DE
-Begin major quote.
-These are single spaced,
+Begin long quotation.
+Text until
+.b .)q
+is single-spaced,
filled,
-moved in from the text
-on both sides
+indented on the left and right
by
.NR (qi
[4n],
@@ -819,13 +832,13 @@ by
[same as
.NR (bs ]
space,
-and are set at type size
+and set at type size
.NR (qp
[one point smaller than surrounding text].
.TL
.b .)q
.DE
-End major quote.
+End long quotation.
.TL
.b .(b
.i m
@@ -833,61 +846,34 @@ End major quote.
.DE
Begin block.
Blocks are a form of
-.i keep ,
-where the text of a keep
-is kept together on one page
-if possible
-(keeps are useful
-for tables and figures
-which should not be broken
-over a page).
+.i keep,
+where material
+is kept together on a page
+if possible.
+Keeps are useful
+for figures
+and some tables.
If the block will not fit
-on the current page
-a new page is begun,
-.i unless
-that would leave more than
+on the current page,
+a new one is begun,
+unless that would leave more than
.NR (bt
[0]
-white space
-at the bottom of the text.
+vees of blank space
+at the bottom of the page;
+this is the
+.i "block threshold."
If
.NR (bt
-is zero, the threshold feature
+is zero,
+the threshold feature
is turned off.
-Blocks are not filled
-unless
-.i f
-is
-.b F ,
-when they are filled.
-The block will be left-justified
-if
-.i m
-is
-.b L ,
-indented by
-.NR (bi
-[4m]
-if
+The font and handling of
.i m
-is
-.b I
-or absent,
-centered
-(line-for-line)
-if
-.i m
-is
-.b C ,
-and left justified to the margin
-(not to the base indent)
-if
-.i m
-is
-.b M .
-The block is set in font
-.NR (df
-[0].
+and
+.i f
+are as in
+.b .(l .
.TL
.b .)b
.DE
@@ -899,21 +885,24 @@ End block.
.DE
Begin floating keep.
Like
-.b .(b
-except that the keep is
-.i floated
+.b .(b ,
+except that
+.i m
+defaults to
+.b M
+and the keep
+.i floats
to the bottom of the page
-or the top of the next page.
+if it fits,
+or the top of the next otherwise.
Therefore,
-its position relative to the text changes.
-The floating keep is preceded and followed
-by
+its position relative to adjacent formatted text
+is flexible.
.NR (zs
[1v]
-space.
-Also,
-it defaults to mode
-.b M .
+space
+precedes and follows
+a floating keep.
.TL
.b .)z
.DE
@@ -925,10 +914,8 @@ Begin centered block.
The next keep
is centered as a block,
rather than on a line-by-line basis
-as with
-.b ".(b C" .
-This call may be nested
-inside keeps.
+as with \(lq\c
+.b ".(b C" \(rq.
.TL
.b .)c
.DE
@@ -1164,7 +1151,7 @@ Also,
.NR (fp
(footnote point size),
.NR (qp
-(quote point size),
+(long quotation point size),
.NR (sp
(section header point size),
and
@@ -2063,7 +2050,7 @@ NAME TYPE DESCRIPTION
\&.(d M begin delayed text
\&.(f M begin footnote
\&.(l M begin list
-\&.(q M begin quote
+\&.(q M begin long quotation
\&.(x M begin index entry
\&.(z M begin floating keep
\&.)b M end block
@@ -2071,7 +2058,7 @@ NAME TYPE DESCRIPTION
\&.)d M end delayed text
\&.)f M end footnote
\&.)l M end list
-\&.)q M end quote
+\&.)q M end long quotation
\&.)x M end index entry
\&.)z M end floating keep
\e*\fI\&x\fP F\(sc interpolate string \fI\&x\fP
@@ -2130,7 +2117,7 @@ NAME TYPE DESCRIPTION
\&.bp M\(sc begin page
\&.br M\(sc break (start new line)
\en(bs R display (block) pre/post spacing
-\en(bt R block keep threshold
+\en(bt R block threshold for keeps
\&.bx M boxed
\ec F\(sc continue input
\&.ce M\(sc center lines
@@ -2214,9 +2201,9 @@ NAME TYPE DESCRIPTION
\&.q M quoted
\e*(qa S for all
\e*(qe S there exists
-\en(qi R quote indent (also shortens line)
-\en(qp R quote type size in points
-\en(qs R quote pre/post space
+\en(qi R long quotation left/right indentation
+\en(qp R long quotation type size in points
+\en(qs R long quotation pre/post space
\&.r M roman font
\&.rb M real bold font
\&.re M reset tabs
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [groff] 39/53: doc/meref.me: Revise "Displays" section.,
G. Branden Robinson <=