o5r/plan9port
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

tmac: introduce real manual reference macro instead of overloading IR

Browse source 
The overloading of IR emits magic \X'...' sequences that turn into HTML manual links.
But not all such IR invocations should be manual links;
those had to be written to avoid the IR macro before.
Worse, the \X'...' ending the IR causes troff to emit only a single space after a period.

Defining a new IM macro for manual references fixes both problems.

Fixes #441.
This commit is contained in:
Russ Cox 2020-08-13 23:41:59 -04:00
parent a1c4307800
commit 977b25a76a
297 changed files with 1790 additions and 1774 deletions
Download patch file Download diff file Expand all files Collapse all files

14
man/man7/color.7
View file

@ -121,11 +121,11 @@ which is scaled so 0 represents fully transparent and 255 represents opaque colo
The alpha is
.I premultiplied
into the other channels, as described in the paper by Porter and Duff cited in
.IR draw (3).
.IM draw (3) .
The function
.B setalpha
(see
.IR allocimage (3))
.IM allocimage (3) )
aids the initialization of color values with non-trivial alpha.
.PP
The packing of pixels into bytes and words is odd.
@ -138,13 +138,13 @@ the byte ordering is blue, green, red.
.PP
To maintain a constant external representation,
the
.IR draw (3)
.IM draw (3)
interface
as well as the
various graphics libraries represent colors
by 32-bit numbers, as described in
.IR color (3).
.IM color (3) .
.SH "SEE ALSO"
.IR color (3),
.IR graphics (3),
.IR draw (3)
.IM color (3) ,
.IM graphics (3) ,
.IM draw (3)

10
man/man7/face.7
View file

@ -25,13 +25,13 @@ per color)).
The large files serve no special purpose; they are stored
as images
(see
.IR image (7)).
.IM image (7) ).
The small files are the `icons' displayed by
.B faces
and
.B seemail
(see Plan 9's
\fIfaces\fR(1));
.IR faces (1));
for depths less than 4, their format is special.
.PP
One- and two-bit deep icons are stored as text, one line of the file to one scan line
@ -110,6 +110,6 @@ which then appears as a domain name in the
.B .dict
files.
.SH "SEE ALSO"
.IR mail (1),
.IR tweak (1),
.IR image (7)
.IM mail (1) ,
.IM tweak (1) ,
.IM image (7)

22
man/man7/font.7
View file

@ -5,7 +5,7 @@ font, subfont \- external format for fonts and subfonts
.B #include <draw.h>
.SH DESCRIPTION
Fonts and subfonts are described in
.IR cachechars (3).
.IM cachechars (3) .
.PP
External bitmap fonts are described by a plain text file that can be read using
.IR openfont .
@ -21,7 +21,7 @@ with an optional starting position within the subfont,
and the file name names an external file suitable for
.I readsubfont
(see
.IR graphics (3)).
.IM graphics (3) ).
The minimum number of a covered range is mapped to the specified starting position
(default zero) of the
corresponding subfont.
@ -36,11 +36,11 @@ that can be read and written using
and
.I writesubfont
(see
.IR subfont (3)).
.IM subfont (3) ).
The format for subfont files is: an image containing character glyphs,
followed by a subfont header, followed by character information.
The image has the format for external image files described in
.IR image (7).
.IM image (7) .
The subfont header has 3
decimal strings:
.BR n ,
@ -72,7 +72,7 @@ are irrelevant.
.PP
Note that the convention of using the character with value zero (NUL) to represent
characters of zero width (see
.IR draw (3))
.IM draw (3) )
means that fonts should have, as their zeroth character,
one with non-zero width.
.SS "Font Names
@ -121,7 +121,7 @@ The command
.B .
lists the available fonts.
See
.IR fontsrv (4)
.IM fontsrv (4)
for more.
.PP
If the font name has the form
@ -136,7 +136,7 @@ The Plan 9 bitmap fonts were designed for screens with pixel density around 100
When used on screens with pixel density above 200 DPI,
the bitmap fonts are automatically pixel doubled.
Similarly, fonts loaded from
.IR fontsrv (4)
.IM fontsrv (4)
are automatically doubled in size by varying the effective
.I size
path element.
@ -184,7 +184,7 @@ a system-installed vector font on high-density displays:
.B \*9/font/*
font directories
.SH "SEE ALSO"
.IR graphics (3),
.IR draw (3),
.IR cachechars (3),
.IR subfont (3)
.IM graphics (3) ,
.IM draw (3) ,
.IM cachechars (3) ,
.IM subfont (3)

6
man/man7/htmlroff.7
View file

@ -2,7 +2,7 @@
.SH NAME
htmlroff \- HTML formatting and typesetting
.SH DESCRIPTION
.IR Htmlroff (1)
.IM Htmlroff (1)
accepts
.I troff
input with a few extensions and changes.
@ -200,7 +200,7 @@ inside
.B <sub>
tags.
This heuristic handles simple equations formatted by
.IR eqn (1).
.IM eqn (1) .
.SS Conditional input
.PP
To make it easier to write input files that can be formatted by both
@ -315,7 +315,7 @@ For example,
redefines the
.B PS
macro that marks the beginning of a
.IR pic (1)
.IM pic (1)
picture:
.IP
.EX

46
man/man7/image.7
View file

@ -5,9 +5,9 @@ image \- external format for images
.B #include <draw.h>
.SH DESCRIPTION
Images are described in
.IR graphics (3),
.IM graphics (3) ,
and the definition of pixel values is in
.IR color (7).
.IM color (7) .
Fonts and images are stored in external files
in machine-independent formats.
.PP
@ -21,7 +21,7 @@ and
and
.B writememimage
(see
.IR memdraw (3)).
.IM memdraw (3) ).
An uncompressed image file starts with 5
strings:
.BR chan ,
@ -34,10 +34,10 @@ Each is right-justified and blank padded in 11 characters, followed by a blank.
The
.B chan
value is a textual string describing the pixel format
(see
(see
.B strtochan
in
.IR graphics (3)
.IM graphics (3)
and the discussion of channel descriptors below),
and the rectangle coordinates are decimal strings.
The rest of the file contains the
@ -49,7 +49,7 @@ consists of the byte containing pixel
.B r.min.x
and all the bytes up to and including the byte containing pixel
.BR r.max.x -1.
For images with depth
For images with depth
.I d
less than eight, a pixel with x-coordinate =
.I x
@ -73,11 +73,11 @@ The
and
.B unloadimage
functions described in
.IR allocimage (3)
.IM allocimage (3)
also deal with rows in this format, stored in user memory.
.PP
The channel format string is a sequence of two-character channel descriptions,
each comprising a letter
each comprising a letter
.RB ( r
for red,
.B g
@ -95,10 +95,10 @@ and
for ``don't care'')
followed by a number of bits per pixel.
The sum of the channel bits per pixel is the
depth of the image, which must be either
depth of the image, which must be either
a divisor or a multiple of eight.
It is an error to have more than
one of any channel but
one of any channel but
.BR x .
An image must have either a greyscale channel; a color mapped channel;
or red, green, and blue channels.
@ -110,13 +110,13 @@ In particular
.B 'r8g8b8'
pixels have byte ordering blue, green, and red within the file.
See
.IR color (7)
.IM color (7)
for more details of the pixel format.
.PP
A venerable yet deprecated format replaces the channel string
with a decimal
.IR ldepth ,
which is the base two logarithm of the number
which is the base two logarithm of the number
of bits per pixel in the image.
In this case,
.IR ldepth s
@ -177,9 +177,9 @@ Some small images, in particular 48\(mu48 face files
as used by
.I seemail
(see Plan 9's
\fIfaces\fR(1)
.IR faces (1)
and
.IR face (7))
.IM face (7) )
and 16\(mu16
cursors, can be stored textually, suitable for inclusion in C source.
Each line of text represents one scan line as a
@ -188,18 +188,18 @@ bytes, shorts, or words in C format.
For cursors, each line defines a pair of bytes.
(It takes two images to define a cursor; each must be stored separately
to be processed by programs such as
.IR tweak (1).)
.IM tweak (1) .)
Face files of one bit per pixel are stored as a sequence of shorts,
those of larger pixel sizes as a sequence of longs.
Software that reads these files must deduce the image size from
the input; there is no header.
These formats reflect history rather than design.
.SH "SEE ALSO"
.IR jpg (1),
.IR tweak (1),
.IR graphics (3),
.IR draw (3),
.IR allocimage (3),
.IR color (7),
.IR face (7),
.IR font (7)
.IM jpg (1) ,
.IM tweak (1) ,
.IM graphics (3) ,
.IM draw (3) ,
.IM allocimage (3) ,
.IM color (7) ,
.IM face (7) ,
.IM font (7)

28
man/man7/keyboard.7
View file

@ -49,15 +49,15 @@ in particular, control-J is a line feed and control-M a carriage return.
.PP
The down arrow,
used by
.IR 9term (1),
.IR acme (1),
.IM 9term (1) ,
.IM acme (1) ,
and
.IR sam (1),
.IM sam (1) ,
causes windows to scroll forward.
The up arrow scrolls backward.
.PP
Characters in Plan 9 are runes (see
.IR utf (7)).
.IM utf (7) ).
Any rune can be typed using a compose key followed by several
other keys.
The compose key is also generally near the lower right of the main key area:
@ -92,11 +92,11 @@ the compose key followed by a two- or three-character sequence.
The full list is too long to repeat here, but is contained in the file
.L \*9/lib/keyboard
in a format suitable for
.IR grep (1)
.IM grep (1)
or
.IR look (1).
.IM look (1) .
To add a sequence, edit that file and then rebuild
.IR devdraw (1).
.IM devdraw (1) .
.PP
There are several rules guiding the design of the sequences, as
illustrated by the following examples.
@ -235,10 +235,10 @@ to run them automatically at startup.
sorted table of characters and keyboard sequences
.PD
.SH "SEE ALSO"
.IR intro (1),
.IR ascii (1),
.IR tcs (1),
.IR 9term (1),
.IR acme (1),
.IR sam (1),
.IR utf (7)
.IM intro (1) ,
.IM ascii (1) ,
.IM tcs (1) ,
.IM 9term (1) ,
.IM acme (1) ,
.IM sam (1) ,
.IM utf (7)

6
man/man7/man.7
View file

@ -82,9 +82,9 @@ font- or size-setting macros.
The
.B -man
macros admit equations and tables in the style of
.IR eqn (1)
.IM eqn (1)
and
.IR tbl (1),
.IM tbl (1) ,
but do not support arguments on
.B .EQ
and
@ -113,7 +113,7 @@ The root directory of the Plan 9 installation.
.B \*9/tmac/tmac.antimes
.SH SEE ALSO
.IR troff (1),
.IR man (1)
.IM man (1)
.SH REQUESTS
.ta \w'.TH n c x 'u +\w'Cause 'u +\w'Argument\ 'u
.di xx

2
man/man7/map.7
View file

@ -80,7 +80,7 @@ in the map file.
Both the map file and the index file are ordered by
patch latitude and longitude.
.SH "SEE ALSO"
.IR map (7)
.IM map (7)
.br
The data comes from the World Data Bank I and II and
U.S. Government sources: the Census Bureau, Geological

18
man/man7/mhtml.7
View file

@ -19,14 +19,14 @@ mhtml \- macros for formatting HTML
\&...
.SH DESCRIPTION
This package of
.IR htmlroff (1)
.IM htmlroff (1)
macro definitions provides convenient macros for formatting HTML.
It is usually used along with
.IR troff (1)
.IM troff (1)
macro packages such as
.IR man (7)
.IM man (7)
and
.IR ms (7).
.IM ms (7) .
.I Mhtml
replaces some macros defined in the other packages,
so it should be listed after them on the
@ -64,7 +64,7 @@ before invoking
Accumulate footnotes and print them at the end of the
document under a \fBNotes\fP heading.
These replace the macros in
.IR ms (7).
.IM ms (7) .
To emit the notes accumulated so far, invoke
.BR .NOTES .
.TP
@ -75,7 +75,7 @@ and
.B .PE
with a PNG image corresponding to the output of
running
.IR troff (1)
.IM troff (1)
on the input.
.TP
.B .TS\fR, \fP.TE
@ -100,6 +100,6 @@ percent of the current output width.
.SH FILES
.B \*9/tmac/tmac.html
.SH SEE ALSO
.IR htmlroff (1),
.IR htmlroff (7),
.IR ms (7)
.IM htmlroff (1) ,
.IM htmlroff (7) ,
.IM ms (7)

4
man/man7/mpictures.7
View file

@ -10,7 +10,7 @@ mpictures \- picture inclusion macros
.SH DESCRIPTION
.I Mpictures
macros insert PostScript pictures into
.IR troff (1)
.IM troff (1)
documents.
The macros are:
.TP
@ -129,7 +129,7 @@ comment is present, the picture is
assumed to fill an 8.5\(mu11-inch page.
Nothing prevents the picture from being placed off the page.
.SH SEE ALSO
.IR troff (1)
.IM troff (1)
.SH DIAGNOSTICS
A picture file that can't be read by the PostScript
postprocessor is replaced by white space.

20
man/man7/ms.7
View file

@ -18,7 +18,7 @@ ms \- macros for formatting manuscripts
This package of
.I nroff
and
.IR troff (1)
.IM troff (1)
macro definitions provides a canned formatting
facility for tech%nical papers in various formats.
.PP
@ -38,11 +38,11 @@ impunity after the first
.LR .na .
.PP
Output of the
.IR eqn (1),
.IR tbl (1),
.IR pic (1)
.IM eqn (1) ,
.IM tbl (1) ,
.IM pic (1)
and
.IR grap (1)
.IM grap (1)
preprocessors
for equations, tables, pictures, and graphs is acceptable as input.
.SH FILES
@ -57,8 +57,8 @@ Tenth Edition, Volume 2.
.br
.IR eqn (1),
.IR troff (1),
.IR tbl (1),
.IR pic (1)
.IM tbl (1) ,
.IM pic (1)
.SH REQUESTS
.ta \w'..ND \fIdate\fR 'u +\w'Initial 'u +\w'Cause 'u
.br
@ -153,7 +153,7 @@ Implies
produced by
.I neqn
or
.IR eqn (1).
.IM eqn (1) .
.ti0
\fL\&.EQ\fP \fIx y\fR - yes Display equation.
Equation number is
@ -234,7 +234,7 @@ is subsection level (default 1).
\fL\&.P2\fP - yes End program display.
.ti0
\fL\&.PE\fP - yes End picture; see
.IR pic (1).
.IM pic (1) .
.ti0
\fL\&.PF\fP - yes End picture; restore vertical
position.
@ -280,7 +280,7 @@ font automatically bold.
Default is 5 10 15 ...
.ti0
\fL\&.TE\fP - yes End table; see
.IR tbl (1).
.IM tbl (1) .
.ti0
\fL\&.TH\fP - yes End heading section of table.
.ti0

6
man/man7/ndb.7
View file

@ -59,7 +59,7 @@ Within tuples, pairs on the same line bind tighter than
pairs on different lines.
.PP
Programs search the database directly using the routines in
.IR ndb (3).
.IM ndb (3) .
.\" or indirectly using
.\" .B ndb/cs
.\" and
@ -292,8 +292,8 @@ tcp=9fs port=564
first database file searched
.SH "SEE ALSO"
.\" .IR dial (2),
.IR ndb (1),
.IR ndb (3)
.IM ndb (1) ,
.IM ndb (3)
.\" .IR dhcpd (8),
.\" .IR ipconfig (8),
.\" .IR con (1)

2
man/man7/plot.7
View file

@ -340,4 +340,4 @@ Restore previous environment.
.PD
.SH "SEE ALSO"
.IR plot (1),
.IR graph (1)
.IM graph (1)

18
man/man7/plumb.7
View file

@ -6,7 +6,7 @@ plumb \- format of plumb messages and rules
.SH DESCRIPTION
.SS "Message format
The messages formed by the
.IR plumb (3)
.IM plumb (3)
library are formatted for transmission between
processes into textual form, using newlines to separate
the fields.
@ -61,7 +61,7 @@ A missing field is represented by an empty line.
The
.B plumber
(see
.IR plumb (1))
.IM plumb (1) )
receives messages on its
.B send
port (applications
@ -271,7 +271,7 @@ rule should be specified in a rule set.
.RE
.PP
The arguments to all rules may contain quoted strings, exactly as in
.IR rc (1).
.IM rc (1) .
They may also contain simple string variables, identified by a leading dollar sign
.BR $ .
Variables may be set, between rule sets, by assignment statements in the style of
@ -341,7 +341,7 @@ field of the message.
.B $plan9
The root directory of the Plan 9 tree
(see
.IR get9root (3)).
.IM get9root (3) ).
.RE
.SH EXAMPLE
The following is a modest, representative file of plumbing rules.
@ -403,7 +403,7 @@ default rules file.
.TP
.B plumb
service name for
.IR plumber (4).
.IM plumber (4) .
.TP
.B \*9/plumb
directory for
@ -416,7 +416,7 @@ public macro definitions.
.B \*9/plumb/basic
basic rule set.
.SH "SEE ALSO"
.IR plumb (1),
.IR plumb (3),
.IR plumber (4),
.IR regexp (7)
.IM plumb (1) ,
.IM plumb (3) ,
.IM plumber (4) ,
.IM regexp (7)

6
man/man7/regexp.7
View file

@ -4,9 +4,9 @@ regexp \- Plan 9 regular expression notation
.SH DESCRIPTION
This manual page describes the regular expression
syntax used by the Plan 9 regular expression library
.IR regexp (3).
.IM regexp (3) .
It is the form used by
.IR egrep (1)
.IM egrep (1)
before
.I egrep
got complicated.
@ -130,4 +130,4 @@ A match to any part of a regular expression
extends as far as possible without preventing
a match to the remainder of the regular expression.
.SH "SEE ALSO"
.IR regexp (3)
.IM regexp (3)

4
man/man7/thumbprint.7
View file

@ -9,7 +9,7 @@ for example by calling
and
.B okThumbprint
(see
.IR pushtls (3)),
.IM pushtls (3) ),
check the remote side's public key by comparing against
thumbprints from a trusted list.
The list is maintained by people who set local policies
@ -38,4 +38,4 @@ For example, a web server might have thumbprint
x509 sha1=8fe472d31b360a8303cd29f92bd734813cbd923c cn=*.cs.bell-labs.com
.EE
.SH "SEE ALSO"
.IR pushtls (3)
.IM pushtls (3)

8
man/man7/utf.7
View file

@ -57,7 +57,7 @@ in order to work properly with non-\c
.SM ASCII
input.
See
.IR rune (3).
.IM rune (3) .
.PP
Letting numbers be binary,
a rune x is converted to a multibyte
@ -85,7 +85,7 @@ In the inverse mapping,
any sequence except those described above
is incorrect and is converted to rune hexadecimal 0080.
.SH "SEE ALSO"
.IR ascii (1),
.IR tcs (1),
.IR rune (3),
.IM ascii (1) ,
.IM tcs (1) ,
.IM rune (3) ,
.IR "The Unicode Standard" .

28
man/man7/venti.7
View file

@ -14,19 +14,19 @@ of clients.
This manual page documents the basic concepts of
block storage using Venti as well as the Venti network protocol.
.PP
.IR Venti (1)
.IM Venti (1)
documents some simple clients.
.IR Vac (1),
.IR vacfs (4),
.IM Vac (1) ,
.IM vacfs (4) ,
and
.IR vbackup (8)
.IM vbackup (8)
are more complex clients.
.PP
.IR Venti (3)
.IM Venti (3)
describes a C library interface for accessing
Venti servers and manipulating Venti data structures.
.PP
.IR Venti (8)
.IM Venti (8)
describes the programs used to run a Venti server.
.PP
.SS "Scores
@ -40,11 +40,11 @@ Scores may have an optional
prefix, typically used to
describe the format of the data.
For example,
.IR vac (1)
.IM vac (1)
uses a
.B vac:
prefix, while
.IR vbackup (8)
.IM vbackup (8)
uses prefixes corresponding to the file system
types:
.BR ext2: ,
@ -93,7 +93,7 @@ Keeping this parallel representation is a minor annoyance
but makes it possible for general programs like
.I venti/copy
(see
.IR venti (1))
.IM venti (1) )
to traverse the block tree without knowing the specific details
of any particular program's data.
.SS "Block Types
@ -202,7 +202,7 @@ Text strings are represented similarly,
using a two-byte count with
the text itself stored as a UTF-encoded sequence
of Unicode characters (see
.IR utf (7)).
.IM utf (7) ).
Text strings are not
.SM NUL\c
-terminated:
@ -395,7 +395,7 @@ Use
and
.I vtfromdisktype
(see
.IR venti (3))
.IM venti (3) )
to convert a block type enumeration value
.RB ( VtDataType ,
etc.)
@ -457,9 +457,9 @@ in the
packet may be either 2 or 4 bytes;
the total packet length distinguishes the two cases.
.SH SEE ALSO
.IR venti (1),
.IR venti (3),
.IR venti (8)
.IM venti (1) ,
.IM venti (3) ,
.IM venti (8)
.br
Sean Quinlan and Sean Dorward,
``Venti: a new approach to archival storage'',