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

7 files changed, 126 insertions, 93 deletions

diff --git a/hacking.pdf b/HACKING.pdf
index 6e88531..a7da708 100644
--- a/hacking.pdf
+++ b/HACKING.pdf
diff --git a/hacking.t b/HACKING.t
index 629b976..10d2a31 100644
--- a/hacking.t
+++ b/HACKING.t
@@ -64,16 +64,14 @@ The former are to be used within
 itself, while the latter are to be used in
 .i µ
 documents.
-Among the external macros, there are inline, environment (or block-level),
-hybrid and other macros.
+Among the external macros, there are inline, environment (or block-level)
+and other macros.
 .p
 The inline macros all follow the same pattern.
 They take three arguments:
 the string to be formatted,
 an optional suffix
 and an optional prefix.
-The hybrid macros act as inline macros when given arguments;
-otherwise they act as environment macros.
 .p
 The environment or block-level macros generally take no arguments
 (except
@@ -130,7 +128,7 @@ has been invoked).
 The
 .c @m
 register is non-zero if
-.q "manual footer"
+." "manual footer"
 mode is active.
 If
 .c @m
diff --git a/Makefile b/Makefile
index 22b55f3..6aa8fa8 100644
--- a/Makefile
+++ b/Makefile
@@ -5,15 +5,15 @@ MANDIR ?= /usr/local/man
 TROFF ?= troff
 PDFROFF ?= troff | dpost | ps2pdf -
 
-all: README.pdf hacking.pdf
+all: README.pdf HACKING.pdf
 
 install:
 	install -m 644 u.tmac t/toc.tmac $(TMACDIR)
 	install t/toc $(BINDIR)
 
-hacking.pdf: hacking.t u.tmac
-	perl -pe '$$_=`$$_` if s/^\!//' hacking.t |\
-	$(PDFROFF) > hacking.pdf
+HACKING.pdf: HACKING.t u.tmac
+	perl -pe '$$_=`$$_` if s/^\!//' HACKING.t |\
+	$(PDFROFF) > HACKING.pdf
 
 README.pdf: README.t u.tmac
 	TROFFONTS=/usr/pkg/share/fonts/X11/TTF/ \
diff --git a/README.pdf b/README.pdf
index 8dc235b..3db0084 100644
--- a/README.pdf
+++ b/README.pdf
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
diff --git a/toc/README.t b/toc/README.t
index ccb06f3..318adf3 100644
--- a/toc/README.t
+++ b/toc/README.t
@@ -52,7 +52,7 @@ macro hands its argument to the
 .c tm
 request, which prints it on standard error,
 prefixed by
-.q (toc) .
+." (toc) .
 If the
 .i tf
 string is non-empty, the
@@ -77,12 +77,12 @@ This enables the
 .c te
 macro, printing its arguments on standard error.
 The lines prefixed with
-.q (toc) ,
+." (toc) ,
 printed on standard error,
 are written to the file
 .i $g
 with the
-.q (toc)
+." (toc)
 prefix removed.
 .p
 In the second pass,
@@ -162,7 +162,7 @@ will print
 .p
 on standard error.
 The
-.q (toc)
+." (toc)
 prefix is removed before the line is written to the temporary file.
 .p
 When
diff --git a/u.tmac b/u.tmac
index 52bfbab..2091474 100644
--- a/u.tmac
+++ b/u.tmac
@@ -243,6 +243,11 @@ ___________________
 .
 .\" Inline macros ------------------------------
 .
+.\" " -- inline quotation
+.de "
+\&\$3\(lq\$1\(rq\$2
+..
+.
 .\" b -- bold font
 .de b
 \&\$3\fB\$1\fP\$2
@@ -287,23 +292,6 @@ ___________________
 ..
 .
 .
-.\" Hybrid macros ------------------------------
-.
-.\" q -- quotation
-.de q
-.
-. \" inline
-. ie !'\$1'' \&\$3\(lq\$1\(rq\$2
-.
-. \" block
-. el \{\
-.  br
-.  @e q
-.  ti \n(tiu
-. \}
-..
-.
-.
 .\" Environment macros -------------------------
 .
 .
@@ -335,6 +323,13 @@ ___________________
 . if '\*[%penv]'p' .ti \n(tiu
 ..
 .
+.\" q -- quotation
+.de q
+. br
+. @e q
+. ti \n(tiu
+..
+.
 .\" s -- subheading
 .de s
 . br