diff options
| -rw-r--r-- | HACKING.pdf (renamed from hacking.pdf) | bin | 24683 -> 24518 bytes | |||
| -rw-r--r-- | HACKING.t (renamed from hacking.t) | 8 | ||||
| -rw-r--r-- | Makefile | 8 | ||||
| -rw-r--r-- | README.pdf | bin | 59334 -> 62089 bytes | |||
| -rw-r--r-- | README.t | 166 | ||||
| -rw-r--r-- | toc/README.t | 8 | ||||
| -rw-r--r-- | u.tmac | 29 |
7 files changed, 126 insertions, 93 deletions
diff --git a/hacking.pdf b/HACKING.pdf Binary files differindex 6e88531..a7da708 100644 --- a/hacking.pdf +++ b/HACKING.pdf @@ -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 @@ -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/ \ Binary files differ@@ -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 @@ -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 |