From e8086631ecabb0018062c1b8a519a2fa265c92f9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?John=20Ankarstr=C3=B6m?= <john@ankarstrom.se>
Date: Thu, 24 Jun 2021 22:38:08 +0200
Subject: Split q macro into " (inline) and q (block-level)

---
 HACKING.pdf  | Bin 0 -> 24518 bytes
 HACKING.t    | 162 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 Makefile     |   8 +--
 README.pdf   | Bin 59334 -> 62089 bytes
 README.t     | 166 ++++++++++++++++++++++++++++++++++++-----------------------
 hacking.pdf  | Bin 24683 -> 0 bytes
 hacking.t    | 164 ----------------------------------------------------------
 toc/README.t |   8 +--
 u.tmac       |  29 +++++------
 9 files changed, 285 insertions(+), 252 deletions(-)
 create mode 100644 HACKING.pdf
 create mode 100644 HACKING.t
 delete mode 100644 hacking.pdf
 delete mode 100644 hacking.t

diff --git a/HACKING.pdf b/HACKING.pdf
new file mode 100644
index 0000000..a7da708
Binary files /dev/null and b/HACKING.pdf differ
diff --git a/HACKING.t b/HACKING.t
new file mode 100644
index 0000000..10d2a31
--- /dev/null
+++ b/HACKING.t
@@ -0,0 +1,162 @@
+.so u.tmac
+.
+.de @h
+. sp |36p
+. if \\n%>1 .tl ''-%-''
+. sp |1i
+..
+.de @f
+.sp |\\n(.pu-36p
+.tl ''\\*(#e''
+..
+.
+.t
+Hacking on the
+.x µ
+macro package
+.d
+John Ankarström
+.
+.
+.h
+What is
+.x µ ?
+.p
+.i µ
+or
+.i mu
+is a simple macro package for troff
+designed to abstract as little as possible from troff itself,
+while still providing a powerful framework for
+writing advanced documents.
+.
+.
+.h
+How is the source code of
+.x µ
+organized?
+.p
+If you run
+.c "grep -n [-]-"
+on the
+.i u.tmac
+source file, you are presented with an overview of
+.i µ 's
+macros:
+.l
+.eo
+!grep -n [-]- u.tmac
+.ec
+.p
+This is a sufficient summary of the entire
+.i µ
+source code, as nothing is performed outside of these macros.
+All initialization is performed in the
+.c @a
+macro, which is automatically called at the first invocation
+of any other macro.
+.p
+The above summary reflects a categorization in the macros defined by
+.i µ .
+There are internal and external macros.
+The former are to be used within
+.i u.tmac
+itself, while the latter are to be used in
+.i µ
+documents.
+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.
+.p
+The environment or block-level macros generally take no arguments
+(except
+.c d ).
+Instead, they activate a given environment,
+affecting the formatting of the following text.
+Each environment macro is associated with a specific environment,
+carrying the same one-letter name as the macro itself.
+.p
+As you can see,
+the macros in each category are arranged alphabetically.
+.
+.
+.h
+Where is document state stored?
+.p
+Most state is stored by troff itself within the different environments.
+In addition,
+.i µ
+associates three extra registers with each environment:
+.c sp ,
+the amount of space to be added by
+.c @e
+before an environment;
+.c sq ,
+the same (except the space is not added
+if the new environment is identical to the previous one); and
+.c ti ,
+the indentation of the first line in the
+.c p
+environment.
+These are stored in registers named
+.c @ENV_sp ,
+.c @ENV_sq
+and
+.c @ENV_ti ,
+where
+.c ENV
+is the name of the associated environment.
+.p
+The strings
+.c %env
+and
+.c %penv
+contain the name of the current and previous environment.
+.p
+The
+.c @a
+register is set to 1 if the document has been initialized
+(i.e. if
+.c @a
+has been invoked).
+.p
+The
+.c @m
+register is non-zero if
+." "manual footer"
+mode is active.
+If
+.c @m
+is non-zero,
+.c @tf
+decrements it by one and exits when invoked,
+unless called with the
+.c f
+(force) argument.
+This is useful if you want to trigger the footer manually,
+but do not want the printed footer to trigger the footer trap again.
+.p
+.c @.t
+contains the absolute vertical position of the first trap
+following the first footnote reference on a page;
+it is set and used by
+.c )
+to place the footnote trap in the correct vertical position.
+.c @dn
+contains the height of all collected footnotes on a page;
+it is set by
+.c )
+and reset to zero by
+.c @tn .
+.c @n
+contains the total number of collected footnotes.
+.p
+Note that none of these registers and strings should be
+directly accessed or modified by
+.i µ
+documents.
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
Binary files a/README.pdf and b/README.pdf differ
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/hacking.pdf b/hacking.pdf
deleted file mode 100644
index 6e88531..0000000
Binary files a/hacking.pdf and /dev/null differ
diff --git a/hacking.t b/hacking.t
deleted file mode 100644
index 629b976..0000000
--- a/hacking.t
+++ /dev/null
@@ -1,164 +0,0 @@
-.so u.tmac
-.
-.de @h
-. sp |36p
-. if \\n%>1 .tl ''-%-''
-. sp |1i
-..
-.de @f
-.sp |\\n(.pu-36p
-.tl ''\\*(#e''
-..
-.
-.t
-Hacking on the
-.x µ
-macro package
-.d
-John Ankarström
-.
-.
-.h
-What is
-.x µ ?
-.p
-.i µ
-or
-.i mu
-is a simple macro package for troff
-designed to abstract as little as possible from troff itself,
-while still providing a powerful framework for
-writing advanced documents.
-.
-.
-.h
-How is the source code of
-.x µ
-organized?
-.p
-If you run
-.c "grep -n [-]-"
-on the
-.i u.tmac
-source file, you are presented with an overview of
-.i µ 's
-macros:
-.l
-.eo
-!grep -n [-]- u.tmac
-.ec
-.p
-This is a sufficient summary of the entire
-.i µ
-source code, as nothing is performed outside of these macros.
-All initialization is performed in the
-.c @a
-macro, which is automatically called at the first invocation
-of any other macro.
-.p
-The above summary reflects a categorization in the macros defined by
-.i µ .
-There are internal and external macros.
-The former are to be used within
-.i u.tmac
-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.
-.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
-.c d ).
-Instead, they activate a given environment,
-affecting the formatting of the following text.
-Each environment macro is associated with a specific environment,
-carrying the same one-letter name as the macro itself.
-.p
-As you can see,
-the macros in each category are arranged alphabetically.
-.
-.
-.h
-Where is document state stored?
-.p
-Most state is stored by troff itself within the different environments.
-In addition,
-.i µ
-associates three extra registers with each environment:
-.c sp ,
-the amount of space to be added by
-.c @e
-before an environment;
-.c sq ,
-the same (except the space is not added
-if the new environment is identical to the previous one); and
-.c ti ,
-the indentation of the first line in the
-.c p
-environment.
-These are stored in registers named
-.c @ENV_sp ,
-.c @ENV_sq
-and
-.c @ENV_ti ,
-where
-.c ENV
-is the name of the associated environment.
-.p
-The strings
-.c %env
-and
-.c %penv
-contain the name of the current and previous environment.
-.p
-The
-.c @a
-register is set to 1 if the document has been initialized
-(i.e. if
-.c @a
-has been invoked).
-.p
-The
-.c @m
-register is non-zero if
-.q "manual footer"
-mode is active.
-If
-.c @m
-is non-zero,
-.c @tf
-decrements it by one and exits when invoked,
-unless called with the
-.c f
-(force) argument.
-This is useful if you want to trigger the footer manually,
-but do not want the printed footer to trigger the footer trap again.
-.p
-.c @.t
-contains the absolute vertical position of the first trap
-following the first footnote reference on a page;
-it is set and used by
-.c )
-to place the footnote trap in the correct vertical position.
-.c @dn
-contains the height of all collected footnotes on a page;
-it is set by
-.c )
-and reset to zero by
-.c @tn .
-.c @n
-contains the total number of collected footnotes.
-.p
-Note that none of these registers and strings should be
-directly accessed or modified by
-.i µ
-documents.
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
-- 
cgit v1.2.3