aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJohn Ankarström <john@ankarstrom.se>2021-06-24 22:38:08 +0200
committerJohn Ankarström <john@ankarstrom.se>2021-06-24 22:38:08 +0200
commite8086631ecabb0018062c1b8a519a2fa265c92f9 (patch)
tree94c82bb6735d6394255b11cca357b998648e1e4d
parent51b0a6c8bfd93e035ca80a46838771972e473600 (diff)
downloadmk-e8086631ecabb0018062c1b8a519a2fa265c92f9.tar.gz
Split q macro into " (inline) and q (block-level)
-rw-r--r--HACKING.pdf (renamed from hacking.pdf)bin24683 -> 24518 bytes
-rw-r--r--HACKING.t (renamed from hacking.t)8
-rw-r--r--Makefile8
-rw-r--r--README.pdfbin59334 -> 62089 bytes
-rw-r--r--README.t166
-rw-r--r--toc/README.t8
-rw-r--r--u.tmac29
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
Binary files differ
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
Binary files 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/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