Split q macro into " (inline) and q (block-level)

1 files changed, 103 insertions, 63 deletions

diff --git a/README.t b/README.t
index 36d5b2c..c62be75 100644
--- a/README.t
+++ b/README.t
@@ -124,6 +124,9 @@ With a couple of exceptions, it uses
 default settings.
 The reader is encouraged to inspect the document's source code
 in order to see how the macro package is used in practice.
+.p
+And yes, that table of contents is automatically generated!
+See p. \n[&toc] for more information.
 .
 .
 .he Environments
@@ -159,7 +162,7 @@ the desired font family and point size are automatically restored.
 .p
 The environments are initialized
 as soon as the first
-.q block-level
+." block-level
 macro is called.
 At the initialization of each environment,
 the default environment (0) is copied,
@@ -214,6 +217,7 @@ prefix
 and are going to be explored later.
 For now, we will focus on the external macros provided by
 .i µ .
+.
 .se Inline macros
 .p
 There is a group of macros that provide
@@ -224,6 +228,10 @@ the text to be placed immediately after
 and the text to be placed immediately before.
 The inline macros are the following:
 .n 1
+.c \(dq ,
+quotation (like
+." this )
+.n
 .c b ,
 bold font
 .n
@@ -265,6 +273,9 @@ literal display (for source code)
 .c p ,
 paragraph
 .n
+.c q ,
+indented quotation
+.n
 .c s ,
 subheading
 .n
@@ -296,11 +307,11 @@ an argument describing the desired date format:
 .n 1 a )
 .c i :
 international date, like
-.q 2021-06-21
+." 2021-06-21
 .n
 .c e :
 English date, like
-.q "21 June 2021"
+." "21 June 2021"
 .p
 The formatted dates are defined in strings prefixed with a hash symbol
 .c # ): (
@@ -322,10 +333,6 @@ begin footnote
 .c ) ,
 end footnote
 .n
-.ne 2
-.c q ,
-quotation
-.n
 .c w ,
 want space
 .p
@@ -342,7 +349,7 @@ and
 take an optional argument,
 which is output either immediately before or immediately after
 the inline reference.
-For example, the following code
+For example, the code
 .l
 \&.q
 This is a quotation\\c
@@ -351,7 +358,7 @@ This is a quotation\\c
 This is a footnote.
 \&.) .
 .p
-creates the following reference:
+generates the following output:
 .q
 This is a quotation\c
 .(
@@ -368,20 +375,6 @@ cannot fit on the current page,
 will print the footnotes on the next page instead.
 .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 an alternative to troff's
 .c ne
@@ -531,7 +524,7 @@ 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
 If you are merely configuring the environment
@@ -592,41 +585,6 @@ To change the contents of the footer:
 \&. tl 'left'center'right'
 \&..
 .
-.se How do I prevent a section from being broken up by a page break?
-.p
-Some macro packages have a concept of
-.q keeps ,
-sections that are kept together across page breaks.
-.i µ
-does not (at least yet) define any such macros by default.
-The simplest solution is to use troff's
-.c ne
-request:
-.l
-\&.ne 7 \\" break page if seven lines won't fit on this page
-\&.\\" ... some text ...
-.p
-If you want to keep text of various styles together,
-you can use
-.i µ 's
-own
-.c w
-macro:
-.l
-\&.w s qq \\" break page if a subheading and two lines of a quotation won't fit
-\&.\\" ... some text ...
-.ig
-.p
-For a more general solution, you can use a diversion:
-.l
-\&.di keep
-\&.\\" ... some text ...
-\&.br
-\&.di
-\&.ne \\n(dnu
-\&.keep
-..
-.
 .se How do I define my own environments?
 .p
 Environments are a feature built into troff,
@@ -672,7 +630,88 @@ and defines a corresponding macro:
 \&. @e n \\" activate new environment
 \&..
 .
+.se How do I prevent a section from being broken up by a page break?
+.p
+Some macro packages have a concept of
+." keeps ,
+sections that are kept together across page breaks.
+.i µ
+does not (at least yet) define any such macros by default.
+The simplest solution is to use troff's
+.c ne
+request:
+.l
+\&.ne 7 \\" break page if seven lines won't fit on this page
+\&.\\" ... some text ...
+.p
+If you want to keep text of various styles together,
+you can use
+.i µ 's
+own
+.c w
+macro:
+.l
+\&.w s qq \\" break page if a subheading and two lines of a quotation won't fit
+\&.\\" ... some text ...
+.ig
+.p
+For a more general solution, you can use a diversion:
+.l
+\&.di keep
+\&.\\" ... some text ...
+\&.br
+\&.di
+\&.ne \\n(dnu
+\&.keep
+..
+.
+.se How do I use alternative quotation marks?
+.p
+Redefine
+.c \(dq .
+The following code defines a Swedish quotation style:
+.l
+\&.de "
+\\\\&\\\\$3”\\\\$1”\\\\$2
+\&..
+.p
+Another option is to create new macros for alternative quotation styles:
+.l
+\&.\\" alternative swedish quotation styles
+\&.de ><
+\\\\&\\\\$3»\\\\$1«\\\\$2
+\&..
+\&.de >>
+\\\\&\\\\$3»\\\\$1»\\\\$2
+\&..
+.
+.se How do I create nested inline quotations?
+.p
+Just use the backtick
+.c \(ga ) (
+and apostrophe
+.c \(aq ) (
+directly in the argument to
+.c \(dq .
+.p
+If you need to change the quotation style,
+for example when converting a document from US to British English,
+you can redefine
+.c "
+to translate backticks and apostrophes accordingly:
+.l
+\&.eo
+\&.de "
+\&. char ` \\(lq
+\&. char ' \\(rq
+\\&\\$3\\(oq\\$1\\(cq\\$2
+\&. char ` \\(oq
+\&. char ' \\(cq
+\&..
+\&.ec
+.
 .se How do I include a table of contents in my document?
+.te .nr &toc \n%
 .p
 Included with the
 .i µ
@@ -709,14 +748,12 @@ The following definitions provide a good starting point:
 \&.de he
 \&. h
 \\$*
-\&. tm .the \\n% \\$*
+\&. tm .the \\$*\\t\\n%
 \&..
 \&.de the
-\&. nr _ \\$1
-\&. shift
 \&. ta 0 \\n(.luR
 \&. tc .
-\\$*	\\n_
+\\$*
 \&. tc
 \&. br
 \&..
@@ -745,6 +782,9 @@ Thanks to the multiple passes performed by
 .c to
 can be invoked at any place in the document,
 including the beginning.
+.p
+The macro definition listed above is included in
+.i ux.tmac .
 .
 .se How do I create a reference to a later page?
 .p