diff options
| -rw-r--r-- | Makefile | 5 | ||||
| -rw-r--r-- | README.pdf | bin | 62089 -> 62043 bytes | |||
| -rw-r--r-- | README.t | 299 | ||||
| -rwxr-xr-x | list/list | 17 | ||||
| -rw-r--r-- | list/list.1 | 43 | ||||
| -rw-r--r-- | toc/README.pdf | bin | 28728 -> 28572 bytes | |||
| -rw-r--r-- | toc/README.t | 2 |
7 files changed, 227 insertions, 139 deletions
@@ -9,7 +9,8 @@ all: README.pdf HACKING.pdf install: install -m 644 u.tmac t/toc.tmac $(TMACDIR) - install t/toc $(BINDIR) + install -m 644 toc/toc.1 list/list.1 $(MANDIR)/man1 + install toc/toc list/list $(BINDIR) HACKING.pdf: HACKING.t u.tmac perl -pe '$$_=`$$_` if s/^\!//' HACKING.t |\ @@ -17,4 +18,4 @@ HACKING.pdf: HACKING.t u.tmac README.pdf: README.t u.tmac TROFFONTS=/usr/pkg/share/fonts/X11/TTF/ \ - <README.t toc/toc $(PDFROFF) > README.pdf + <README.t toc/toc list/list -p=.l \| $(PDFROFF) > README.pdf Binary files differ@@ -3,6 +3,7 @@ .so toc/toc.tmac .mediasize letter .fp 0 M DejaVuSansMono ttf +.hw Eng-lish . .\" configure table of contents .eo @@ -150,11 +151,12 @@ If the user wishes to modify the default font size, he or she can simply switch to the relevant environment and set the font size as desired using regular troff requests: -.l -\&.\\" set heading font -\&.h -\&.fam H -\&.ps +1p +.l( +.\" set heading font +.h +.fam H +.ps +1p +.l) .p Troff saves the font settings in the environment, so that the next time the environment is invoked, @@ -173,12 +175,13 @@ are applied to all environments. It is thus remarkably simple and intuitive to set, for example, the default font of a document: -.l -\&.fam N -\&.t +.l( +.fam N +.t Document title -\&.p +.p First paragraph. +.l) .p In addition to the normal environment-relevant settings, .i µ @@ -246,8 +249,9 @@ bold italic font .p For example, the following request outputs .i µ .\(rq: \(lq -.l -\&.i µ . +.l( +.i µ . +.l) . .p Note that @@ -288,14 +292,15 @@ and .c d macros can be used at the beginning of a document to create a centered header: -.l -\&.t +.l( +.t Document title -\&.d +.d First author -\&.br +.br Second author -\&.d i \\" current date formatted as YYYY-MM-DD +.d i \" current date formatted as YYYY-MM-DD +.l) .p In the example above, you can see that the .c d @@ -350,13 +355,14 @@ take an optional argument, which is output either immediately before or immediately after the inline reference. For example, the code -.l -\&.q -This is a quotation\\c -\&.( -.ne 1 +.l( +.q +This is a quotation\c +.( +\!.ne 1 This is a footnote. -\&.) . +.) +.l) .p generates the following output: .q @@ -391,11 +397,12 @@ in terms of .i µ environments. For example: -.l -\&.\\" want space for... -\&.w s p \\" a subheading of one line + a paragraph of one line -\&.w s pp \\" a subheading of one line + a paragraph of two lines -\&.w ss p \\" a subheading of two lines + a paragraph of one line +.l( +.\" want space for... +.w s p \" a subheading of one line + a paragraph of one line +.w s pp \" a subheading of one line + a paragraph of two lines +.w ss p \" a subheading of two lines + a paragraph of one line +.l) . . .he Internal macros @@ -513,33 +520,37 @@ you would start the document like this (before you call any .i µ macros): -.l -\&.fam N -\&.ps 9p -\&.vs 12p +.l( +.fam N +.ps 9p +.vs 12p +.l) . .se How do I customize the default appearance of a given environment? .p 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 -\&." -\&.ps +1p +.l( +\!.ne 1 +.q +.ps +1p +.l) .p If you are merely configuring the environment without printing anything in it, you can also use .c @e : -.l -\&.@e q -\&.ps +1p +.l( +.@e q +.ps +1p +.l) . .w s ll .se How do I customize the default appearance of the margin text? -.l -\&.(e @m \\" margin environment -\&.ps +1p +.l( +.(e @m \" margin environment +.ps +1p +.l) .p You can also set such settings in your redefinition of .c @h @@ -548,42 +559,46 @@ or . .w s ll .se How do I customize the default appearance of footnotes? -.l -\&.(e @f \\" footnote environment -\&.ps +1p +.l( +.(e @f \" footnote environment +.ps +1p +.l) . .w s ll .se How do I redefine the page header? -.l -\&.de @h -\&. \\" set position of header text -\&. sp |36p -\&. \\" set header text -\&. tl 'left'center'right' -\&. \\" set position of page text -.ne 1 -\&. sp |1i -\&.. +.l( +.de @h +. \" set position of header text +. sp |36p +. \" set header text +. tl 'left'center'right' +. \" set position of page text +\!.ne 1 +. sp |1i +.. +.l) . .w s ll .se How do I redefine the page footer? .p To change the position of the footer: -.l -\&.\\" set position of footer trap -\&.\\" (must be done before any macros have been called) -\&.wh -1i @tf -\&. +.l( +.\" set position of footer trap +.\" (must be done before any macros have been called) +.wh -1i @tf +. +.l) .p To change the contents of the footer: -.l -\&.de @f -\&. \\" set position of footer text -\&. \\" (must be below the footer trap) -\&. sp |\\\\n(.pu-48p -\&. \\" set footer text -\&. tl 'left'center'right' -\&.. +.l( +.de @f +. \" set position of footer text +. \" (must be below the footer trap) +. sp |\\n(.pu-48p +. \" set footer text +. tl 'left'center'right' +.. +.l) . .se How do I define my own environments? .p @@ -618,17 +633,18 @@ p. \n[&env]). The following code configures an environment called .c n and defines a corresponding macro: -.l -\&.@e n -\&. @c 0 \\" copy default environment -\&. ps -1p -\&.@e -\&. -\&.de n -\&. br \\" finish current environment -.ne 1 -\&. @e n \\" activate new environment -\&.. +.l( +.@e n +. @c 0 \" copy default environment +. ps -1p +.@e +. +.de n +. br \" finish current environment +\!.ne 1 +. @e n \" activate new environment +.. +.l) . .se How do I prevent a section from being broken up by a page break? .p @@ -640,9 +656,10 @@ 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 ... +.l( +.ne 7 \" break page if seven lines won't fit on this page +.\" ... some text ... +.l) .p If you want to keep text of various styles together, you can use @@ -650,19 +667,21 @@ you can use own .c w macro: -.l -\&.w s qq \\" break page if a subheading and two lines of a quotation won't fit -\&.\\" ... some text ... +.l( +.w s qq \" break page if a subheading and two lines of a quotation won't fit +.\" ... some text ... +.l) .ig .p For a more general solution, you can use a diversion: -.l -\&.di keep -\&.\\" ... some text ... -\&.br -\&.di -\&.ne \\n(dnu -\&.keep +.l( +.di keep +.\" ... some text ... +.br +.di +.ne \n(dnu +.keep +.l) .. . .se How do I use alternative quotation marks? @@ -670,20 +689,22 @@ For a more general solution, you can use a diversion: Redefine .c \(dq . The following code defines a Swedish quotation style: -.l -\&.de " -\\\\&\\\\$3”\\\\$1”\\\\$2 -\&.. +.l( +.de " +\\&\\$3”\\$1”\\$2 +.. +.l) .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 -\&.. +.l( +.\" alternative swedish quotation styles +.de >< +\\&\\$3»\\$1«\\$2 +.. +.de >> +\\&\\$3»\\$1»\\$2 +.. +.l) . .se How do I create nested inline quotations? .p @@ -699,16 +720,17 @@ 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 +.l( +.eo +.de " +. char ` \(lq +. char ' \(rq +\&\$3\(oq\$1\(cq\$2 +. char ` \\(oq +. char ' \\(cq +.. +.ec +.l) . .se How do I include a table of contents in my document? .te .nr &toc \n% @@ -743,29 +765,31 @@ Note that the argument given to will be interpreted as a troff input line. .p The following definitions provide a good starting point: -.l -\&.eo -\&.de he -\&. h -\\$* -\&. tm .the \\$*\\t\\n% -\&.. -\&.de the -\&. ta 0 \\n(.luR -\&. tc . -\\$* -\&. tc -\&. br -\&.. -\&.ec +.l( +.eo +.de he +. h +\$* +. tm .the \$*\t\n% +.. +.de the +. ta 0 \n(.luR +. tc . +\$* +. tc +. br +.. +.ec +.l) .p Now, instead of .c h , you may use .c he to create a heading to be included in the table of contents: -.l -\&.he A heading +.l( +.he A heading +.l) .p Wherever you want the table of contents to be inserted, you may simply invoke @@ -774,8 +798,9 @@ you may simply invoke Just remember to use .c toc to run your processing pipeline: -.l -<example.t toc refer \\| troff -Tps >example.ps +.l( +<example.t toc refer \| troff -Tps >example.ps +.l) .p Thanks to the multiple passes performed by .i toc , @@ -799,11 +824,13 @@ Then, at each position you want to reference, invoke .c .te like this: -.l -\&.te .nr &refname \\n% +.l( +.te .nr &refname \n% +.l) .p To refer to that position, interpolate the register: -.l -See page \\n[&refname]. +.l( +See page \n[&refname]. +.l) .p (I prefer prefixing my references with an ampersand.) diff --git a/list/list b/list/list new file mode 100755 index 0000000..64ec8ac --- /dev/null +++ b/list/list @@ -0,0 +1,17 @@ +#!/usr/bin/perl -ps + +# list -- escape code listing for troff + +if (/^\.\s*l\(\s*$/ .. /^\.\s*l\)\s*$/) { + not $E and s/^\\!// and next; + if (/^\.\s*l\(\s*$/) { + print "$p\n" if $p; + } elsif (/^\.\s*l\)\s*$/) { + print "$s\n" if $s; + } else { + s/\\/\\$&/g; + s/^/\\&/g; + s/'/\\(aq/g; + s/\`/\\(ga/g; + } +} diff --git a/list/list.1 b/list/list.1 new file mode 100644 index 0000000..085bb20 --- /dev/null +++ b/list/list.1 @@ -0,0 +1,43 @@ +.Dd $Mdocdate$ +.Dt list 1 +.Os +.Sh NAME +.Nm list +.Nd escape code listings for troff +. +.Sh SYNOPSIS +.Nm +.Op Fl p=prefix +.Op Fl s=suffix +.Op Fl E +.Op Ar file +.Sh DESCRIPTION +.Pp +.Nm +escapes text between +.Ql .l( +and +.Ql .l) +lines for +.Xr troff 1 . +.Pp +Lines beginning with +.Ql \\\\! +are copied verbatim, unless the +.Fl E +flag is given. +.Pp +Text given to +.Fl p +and +.Fl s +is inserted on a new line before and after each code block. +This text is not escaped and can contain arbitrary +.Xr troff 1 +requests. +. +.Sh AUTHORS +.Pp +.Nm +is written by John Ankarström +.Aq Mt "john (at) ankarstrom.se" . diff --git a/toc/README.pdf b/toc/README.pdf Binary files differindex cfa2f6d..317cbc4 100644 --- a/toc/README.pdf +++ b/toc/README.pdf diff --git a/toc/README.t b/toc/README.t index 318adf3..f4d9687 100644 --- a/toc/README.t +++ b/toc/README.t @@ -32,7 +32,7 @@ The .i toc script is a wrapper around troff, passing the document through the typesetter three times. -In every pass, it sets the values of a registers and a string named +In every pass, it sets the values of a register and a string named .i te and .i tf , |