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

Some man pages.

Browse source
This commit is contained in:
rsc 2005-01-03 06:40:20 +00:00
parent 2600337aa7
commit 058b0118a5
214 changed files with 17112 additions and 1999 deletions
Download patch file Download diff file Expand all files Collapse all files

18
man/man7/INDEX Normal file
View file

@ -0,0 +1,18 @@
color color.7
face face.7
font font.7
subfont font.7
image image.7
man man.7
map map.7
ms ms.7
plot plot.7
plumb plumb.7
regexp regexp.7
regexp9 regexp9.7
thumbprint thumbprint.7
ASCII utf.7
UTF utf.7
Unicode utf.7
rune utf.7
utf utf.7

150
man/man7/color.7 Normal file
View file

@ -0,0 +1,150 @@
.TH COLOR 7
.SH NAME
color \- representation of pixels and colors
.SH DESCRIPTION
To address problems of consistency and portability among applications,
Plan 9 uses a fixed color map, called
.BR rgbv ,
on 8-bit-per-pixel displays.
Although this avoids problems caused by multiplexing color maps between
applications, it requires that the color map chosen be suitable for most purposes
and usable for all.
Other systems that use fixed color maps tend to sample the color cube
uniformly, which has advantages\(emmapping from a (red, green, blue) triple
to the color map and back again is easy\(embut ignores an important property
of the human visual system: eyes are
much more sensitive to small changes in intensity than
to changes in hue.
Sampling the color cube uniformly gives a color map with many different
hues, but only a few shades of each.
Continuous tone images converted into such maps demonstrate conspicuous
artifacts.
.PP
Rather than dice the color cube into subregions of
size 6\(mu6\(mu6 (as in Netscape Navigator) or 8\(mu8\(mu4
(as in previous releases of Plan 9), picking 1 color in each,
the
.B rgbv
color map uses a 4\(mu4\(mu4 subdivision, with
4 shades in each subcube.
The idea is to reduce the color resolution by dicing
the color cube into fewer cells, and to use the extra space to increase the intensity
resolution.
This results in 16 grey shades (4 grey subcubes with
4 samples in each), 13 shades of each primary and secondary color (3 subcubes
with 4 samples plus black) and a reasonable selection of colors covering the
rest of the color cube.
The advantage is better representation of
continuous tones.
.PP
The following function computes the 256 3-byte entries in the color map:
.IP
.EX
.ta 6n +6n +6n +6n
void
setmaprgbv(uchar cmap[256][3])
{
uchar *c;
int r, g, b, v;
int num, den;
int i, j;
for(r=0,i=0; r!=4; r++)
for(v=0; v!=4; v++,i+=16)
for(g=0,j=v-r; g!=4; g++)
for(b=0; b!=4; b++,j++){
c = cmap[i+(j&15)];
den = r;
if(g > den)
den = g;
if(b > den)
den = b;
if(den == 0) /* would divide check; pick grey shades */
c[0] = c[1] = c[2] = 17*v;
else{
num = 17*(4*den+v);
c[0] = r*num/den;
c[1] = g*num/den;
c[2] = b*num/den;
}
}
}
.EE
.PP
There are 4 nested loops to pick the (red,green,blue) coordinates of the subcube,
and the value (intensity) within the subcube, indexed by
.BR r ,
.BR g ,
.BR b ,
and
.BR v ,
whence
the name
.IR rgbv .
The peculiar order in which the color map is indexed is designed to distribute the
grey shades uniformly through the map\(emthe
.IR i 'th
grey shade,
.RI 0<= i <=15
has index
.IR i ×17,
with black going to 0 and white to 255.
Therefore, when a call to
.B draw
converts a 1, 2 or 4 bit-per-pixel picture to 8 bits per pixel (which it does
by replicating the pixels' bits), the converted pixel values are the appropriate
grey shades.
.PP
The
.B rgbv
map is not gamma-corrected, for two reasons. First, photographic
film and television are both normally under-corrected, the former by an
accident of physics and the latter by NTSC's design.
Second, we require extra color resolution at low intensities because of the
non-linear response and adaptation of the human visual system.
Properly
gamma-corrected displays with adequate low-intensity resolution pack the
high-intensity parts of the color cube with colors whose differences are
almost imperceptible.
Either reason suggests concentrating
the available intensities at the low end of the range.
.PP
On `true-color' displays with separate values for the red, green, and blue
components of a pixel, the values are chosen so 0 represents no intensity (black) and the
maximum value (255 for an 8-bit-per-color display) represents full intensity (e.g., full red).
Common display depths are 24 bits per pixel, with 8 bits per color in order
red, green, blue, and 16 bits per pixel, with 5 bits of red, 6 bits of green, and 5 bits of blue.
.PP
Colors may also be created with an opacity factor called
.BR alpha ,
which is scaled so 0 represents fully transparent and 255 represents opaque color.
The alpha is
.I premultiplied
into the other channels, as described in the paper by Porter and Duff cited in
.IR draw (3).
The function
.B setalpha
(see
.IR allocimage (3))
aids the initialization of color values with non-trivial alpha.
.PP
The packing of pixels into bytes and words is odd.
For compatibility with VGA frame buffers, the bits within a
pixel byte are in big-endian order (leftmost pixel is most
significant bits in byte), while bytes within a pixel are packed in little-endian
order. Pixels are stored in contiguous bytes. This results
in unintuitive pixel formats. For example, for the RGB24 format,
the byte ordering is blue, green, red.
.PP
To maintain a constant external representation,
the
.IR draw (3)
interface
as well as the
various graphics libraries represent colors
by 32-bit numbers, as described in
.IR color (3).
.SH "SEE ALSO"
.IR color (3),
.IR graphics (3),
.IR draw (3)

115
man/man7/face.7 Normal file
View file

@ -0,0 +1,115 @@
.TH FACE 7
.SH NAME
face \- face files
.SH DESCRIPTION
The directories
.B /usr/$user/lib/face
and
.B /lib/face
contain a hierarchy of images of people.
In those directories are subdirectories named by the sizes of
the corresponding image files:
.B 48x48x1
(48 by 48 pixels, one bit per pixel);
.B 48x48x2
(48 by 48 pixels, two (grey) bits per pixel);
.B 48x48x4
(48 by 48 pixels, four (grey) bits per pixel);
.B 48x48x8
(48 by 48 pixels, eight (color-mapped) bits per pixel);
.B 512x512x8
(512 by 512 pixels, eight (color-mapped) bits per pixel);
.B 512x512x24
(512 by 512 pixels, twenty-four bits per pixel (3 times 8 bits
per color)).
The large files serve no special purpose; they are stored
as images
(see
.IR image (7)).
The small files are the `icons' displayed by
.B faces
and
.B seemail
(see Plan 9's
\fIfaces\fR(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
of display.
Each line is divided into 8-bit, 16-bit, or 32-bit big-endian words,
stored as a list of comma-separated hexadecimal C constants,
such as:
.IP
.EX
0x9200, 0x1bb0, 0x003e,
.EE
.PP
This odd format is historical and the programs that read it
are somewhat forgiving about blanks and the need for commas.
.PP
The files
.BR lib/face/*/.dict
hold a correspondence between users at machines
and face files.
The format is
.IP
.EX
.I machine\fB/\fPuser directory\fB/\fPfile\fB.\fPver
.EE
.PP
The
.I machine
is the domain name of the machine sending the message,
and
.I user
the name of the user sending it.
The
.I directory
is a further subdirectory of (say)
.BR /lib/face/48x48x1 ,
named by a single letter corresponding to the first character
of the user names. The
.I file
is the name of the file, typically but not always the user name,
and
.I ver
is a number to distinguish different images, for example to
distinguish the image for Bill Gates from the image for Bill Joy,
both of which might otherwise be called
.BR b/bill .
For example, Bill Gates might be represented by the line
.IP
.EX
microsoft.com/bill b/bill.1
.EE
.PP
If multiple entries exist for a user in the various
.B .dict
files,
.I faces
chooses the highest pixel size less than or equal to that of the
display on which it is running.
.PP
Finally, or rather firstly, the file
.B /lib/face/.machinelist
contains a list of machine/domain pairs, one per line,
to map any of a set of machines to a single domain name to
be looked up in the
.B .dict
files. The machine name may be a regular expression,
so for example the entry
.IP
.EX
\&.*research\e.bell-labs\e.com astro
.EE
.PP
maps any of the machines in Bell Labs Research into the
shorthand name
.BR astro ,
which then appears as a domain name in the
.B .dict
files.
.SH "SEE ALSO"
.IR mail (1),
.IR tweak (1),
.IR image (7)

87
man/man7/font.7 Normal file
View file

@ -0,0 +1,87 @@
.TH FONT 7
.SH NAME
font, subfont \- external format for fonts and subfonts
.SH SYNOPSIS
.B #include <draw.h>
.SH DESCRIPTION
Fonts and subfonts are described in
.IR cachechars (3).
.PP
External fonts are described by a plain text file that can be read using
.IR openfont .
The format of the file is a header followed by any number of
subfont range specifications.
The header contains two numbers: the height and the ascent, both in pixels.
The height is the inter-line spacing and the ascent is the distance
from the top of the line to the baseline. These numbers are chosen
to display consistently all the subfonts of the font.
A subfont range specification contains two or three numbers and a file name.
The numbers are the inclusive range of characters covered by the subfont,
with an optional starting position within the subfont,
and the file name names an external file suitable for
.I readsubfont
(see
.IR graphics (3)).
The minimum number of a covered range is mapped to the specified starting position
(default zero) of the
corresponding subfont.
If the subfont file name does not begin with a slash, it is taken relative to the
directory containing the font file.
Each field must be followed by some white space.
Each numeric field may be C-format decimal, octal, or hexadecimal.
.PP
External subfonts are represented in a more rigid format
that can be read and written using
.I readsubfont
and
.I writesubfont
(see
.IR 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).
The subfont header has 3
decimal strings:
.BR n ,
.BR height ,
and
.BR ascent .
Each number is right-justified and blank padded in 11 characters, followed by a blank.
The character
.B info
consists of
.BR n +1
6-byte entries, each giving the
.B Fontchar
.B x
(2 bytes, low order byte first),
.BR top ,
.BR bottom ,
.BR left ,
and
.BR width .
The
.B x
field of the last
.B Fontchar
is used to calculate the image width
of the previous character; the other fields in the last
.B Fontchar
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))
means that fonts should have, as their zeroth character,
one with non-zero width.
.SH FILES
.TF /lib/font/bit/*
.TP
.B /lib/font/bit/*
font directories
.SH "SEE ALSO"
.IR graphics (3),
.IR draw (3),
.IR cachechars (3),
.IR subfont (3)

205
man/man7/image.7 Normal file
View file

@ -0,0 +1,205 @@
.TH IMAGE 7
.SH NAME
image \- external format for images
.SH SYNOPSIS
.B #include <draw.h>
.SH DESCRIPTION
Images are described in
.IR graphics (3),
and the definition of pixel values is in
.IR color (7).
Fonts and images are stored in external files
in machine-independent formats.
.PP
Image files are read and written using
.B readimage
and
.B writeimage
(see
.IR allocimage (3)), or
.B readmemimage
and
.B writememimage
(see
.IR memdraw (3)).
An uncompressed image file starts with 5
strings:
.BR chan ,
.BR r.min.x ,
.BR r.min.y ,
.BR r.max.x ,
and
.BR r.max.y .
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
.B strtochan
in
.IR graphics (3)
and the discussion of channel descriptors below),
and the rectangle coordinates are decimal strings.
The rest of the file contains the
.B r.max.y-r.min.y
rows of pixel data.
A
.I row
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
.I d
less than eight, a pixel with x-coordinate =
.I x
will appear as
.I d
contiguous bits in a byte, with the pixel's high order bit
starting at the byte's bit number
.if t \fIw\fP\(mu(\fIx\fP mod (8/\fIw\fP)),
.if n w*(x mod (8/w)),
where bits within a byte are numbered 0 to 7 from the
high order to the low order bit.
Rows contain integral number of bytes, so there may be some unused
pixels at either end of a row.
If
.I d
is greater than 8, the definition of images requires that it will a multiple of 8, so
pixel values take up an integral number of bytes.
.PP
The
.B loadimage
and
.B unloadimage
functions described in
.IR 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
.RB ( r
for red,
.B g
for green,
.B b
for blue,
.B a
for alpha,
.B m
for color-mapped,
.B k
for greyscale,
and
.B x
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
a divisor or a multiple of eight.
It is an error to have more than
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.
If the alpha channel is present, it must be at least as deep as any other channel.
.PP
The channel string defines the format of the pixels in the file,
and should not be confused with ordering of bytes in the file.
In particular
.B 'r8g8b8'
pixels have byte ordering blue, green, and red within the file.
See
.IR 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
of bits per pixel in the image.
In this case,
.IR ldepth s
0, 1, 2, and 3
correspond to channel descriptors
.BR k1 ,
.BR k2 ,
.BR k4 ,
and
.BR m8 ,
respectively.
.PP
Compressed image files start with a line of text containing the word
.BR compressed ,
followed by a header as described above, followed by the image data.
The data, when uncompressed, is laid out in the usual form.
.PP
The data is represented by a string of compression blocks, each encoding
a number of rows of the image's pixel data. Compression blocks
are at most 6024 bytes long, so that they fit comfortably in a
single 9P message. Since a compression block must encode a
whole number of rows, there is a limit (about 5825 bytes) to the width of images
that may be encoded. Most wide images are in subfonts,
which, at 1 bit per pixel (the usual case for fonts), can be 46600 pixels wide.
.PP
A compression block begins with two decimal strings of twelve bytes each.
The first number is one more than the
.B y
coordinate of the last row in the block. The second is the number
of bytes of compressed data in the block, not including the two decimal strings.
This number must not be larger than 6000.
.PP
Pixels are encoded using a version of Lempel & Ziv's sliding window scheme LZ77,
best described in J A Storer & T G Szymanski
`Data Compression via Textual Substitution',
JACM 29#4, pp. 928-951.
.PP
The compression block is a string of variable-length
code words encoding substrings of the pixel data. A code word either gives the
substring directly or indicates that it is a copy of data occurring
previously in the pixel stream.
.PP
In a code word whose first byte has the high-order bit set, the rest of the
byte indicates the length of a substring encoded directly.
Values from 0 to 127 encode lengths from 1 to 128 bytes.
Subsequent bytes are the literal pixel data.
.PP
If the high-order bit is zero, the next 5 bits encode
the length of a substring copied from previous pixels. Values from 0 to 31
encode lengths from 3 to 34 bytes. The bottom two bits of the first byte and
the 8 bits of the next byte encode an offset backward from the current
position in the pixel data at which the copy is to be found. Values from
0 to 1023 encode offsets from 1 to 1024. The encoding may be `prescient',
with the length larger than the offset, which works just fine: the new data
is identical to the data at the given offset, even though the two strings overlap.
.PP
Some small images, in particular 48\(mu48 face files
as used by
.I seemail
(see Plan 9's
\fIfaces\fR(1)
and
.IR 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
comma-separated sequence of hexadecimal
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).)
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)

249
man/man7/man.7 Normal file
View file

@ -0,0 +1,249 @@
.TH MAN 7
.SH NAME
man \- macros to typeset manual
.SH SYNOPSIS
.B nroff -man
.I file ...
.PP
.B troff -man
.I file ...
.SH DESCRIPTION
These macros are used to format pages of this manual.
.PP
Except in
.L .LR
and
.L .RL
requests, any text argument denoted
.I t
in the request summary may be zero to six words.
Quotes
\fL"\fP ... \fL"\fP
may be used to include blanks in a `word'.
If
.I t
is empty,
the special treatment is applied to
the next text input line (the next line that doesn't begin with dot).
In this way, for example,
.B .I
may be used to italicize a line of more than 6 words, or
.B .SM
followed by
.B .B
to make small letters in `bold' font.
.PP
A prevailing indent distance is remembered between
successive indented paragraphs,
and is reset to default value upon reaching a non-indented paragraph.
Default units for indents
.I i
are ens.
.PP
The fonts are
.TP
.B R
roman, the main font, preferred for diagnostics
.PD 0
.TP
.B I
italic, preferred for parameters, short names of commands,
names of manual pages,
and naked function names
.TP
.L B
`bold', actually the constant width font,
preferred for examples, file names, declarations, keywords, names of
.B struct
members, and literals
(numbers are rarely literals)
.TP
.B L
also the constant width font.
In
.I troff
.BR L = B ;
in
.I nroff
arguments of the macros
.BR .L ,
.BR .LR ,
and
.B .RL
are printed in quotes;
preferred only where quotes really help (e.g. lower-case literals and
punctuation).
.PD
.LP
Type font and size are reset to default values
before each paragraph, and after processing
font- or size-setting macros.
.PP
The
.B -man
macros admit equations and tables in the style of
.IR eqn (1)
and
.IR tbl (1),
but do not support arguments on
.B .EQ
and
.B .TS
macros.
.PP
These strings are predefined by
.BR -man :
.TP
.B \e*R
.if t `\*R', `(Reg)' in
.if t .IR nroff .
.if n `(Reg)', trademark symbol in
.if n .IR troff .
.br
.ns
.TP
.B \e*S
Change to default type size.
.SH FILES
.B /sys/lib/tmac/tmac.an
.SH SEE ALSO
.IR troff (1),
.IR man (1)
.SH REQUESTS
.ta \w'.TH n c x 'u +\w'Cause 'u +\w'Argument\ 'u
.di xx
\ka
.br
.di
.in \nau
.ti0
Request Cause If no Explanation
.ti0
Break Argument
.ti0
\&\fL.B\fR \fIt\fR no \fIt\fR=n.t.l.* Text
.I t
is `bold'.
.ti0
\&\fL.BI\fR \fIt\fR no \fIt\fR=n.t.l. Join
words of
.I t
alternating bold and italic.
.ti0
\&\fL.BR\fR \fIt\fR no \fIt\fR=n.t.l. Join
words of
.I t
alternating bold and Roman.
.ti0
\&\fL.DT\fR no Restore default tabs.
.ti0
\&\fL.EE\fR yes End displayed example
.ti0
\&\fL.EX\fR yes Begin displayed example
.ti0
\&\fL.HP\fR \fIi\fR yes \fIi\fR=p.i.* Set prevailing indent to
.IR i .
Begin paragraph with hanging indent.
.ti0
\&\fL.I\fR \fIt\fR no \fIt\fR=n.t.l. Text
.I t
is italic.
.ti0
\&\fL.IB\fR \fIt\fR no \fIt\fR=n.t.l. Join
words of
.I t
alternating italic and bold.
.ti0
\&\fL.IP\fR \fIx i\fR yes \fIx\fR="" Same as \fL.TP\fP with tag
.IR x .
.ti0
\&\fL.IR\fR \fIt\fR no \fIt\fR=n.t.l. Join
words of
.I t
alternating italic and Roman.
.ti0
\&\fL.L\fR \fIt\fR no \fIt\fR=n.t.l. Text
.I t
is literal.
.ti0
\&\fL.LP\fR yes Same as \fL.PP\fP.
.ti0
\&\fL.LR\fR \fIt\fR no Join 2
words of
.I t
alternating literal and Roman.
.ti0
\&\fL.PD\fR \fId\fR no \fId\fR=\fL.4v\fP Interparagraph distance is
.IR d .
.ti0
\&\fL.PP\fR yes Begin paragraph.
Set prevailing indent to default.
.ti0
\&\fL.RE\fR yes End of relative indent.
Set prevailing indent to amount of starting \fL.RS\fP.
.ti0
\&\fL.RI\fR \fIt\fR no \fIt\fR=n.t.l. Join
words of
.I t
alternating Roman and italic.
.ti0
\&\fL.RL\fR \fIt\fR no Join 2 or 3
words of
.I t
alternating Roman and literal.
.ti0
\&\fL.RS\fR \fIi\fR yes \fIi\fR=p.i. Start relative indent,
move left margin in distance
.IR i .
Set prevailing indent to default for nested indents.
.ti0
\&\fL.SH\fR \fIt\fR yes \fIt\fR="" Subhead; reset paragraph distance.
.ti0
\&\fL.SM\fR \fIt\fR no \fIt\fR=n.t.l. Text
.I t
is small.
.ti0
\&\fL.SS\fR \fIt\fR no \fIt\fR="" Secondary subhead.
.ti0
\&\fL.TF\fR \fIs\fR yes Prevailing indent is wide as
string
.I s
in font
.BR L ;
paragraph distance is 0.
.ti0
\&\fL.TH\fR \fIn c x\fR yes Begin page named
.I n
of chapter
.IR c;
.I x
is extra commentary, e.g. `local', for page head.
Set prevailing indent and tabs to default.
.ti0
\&\fL.TP\fR \fIi\fR yes \fIi\fR=p.i. Set prevailing indent to
.IR i .
Restore default indent if
.IR i =0.
Begin indented paragraph
with hanging tag given by next text line.
If tag doesn't fit, place it on separate line.
.ti0
\&\fL.1C\fR yes Equalize columns and return to 1-column output
.ti0
\&\fL.2C\fR yes Start 2-column nofill output
.PP
.ti0
* n.t.l. = next text line; p.i. = prevailing indent
.SH BUGS
There's no way to fool
.I troff
into handling literal double quote marks
.B \&"
in font-alternation macros, such as
.LR .BI .
.br
There is no direct way to suppress column widows in 2-column
output; the column lengths may be adjusted by inserting
.L .sp
requests before the closing
.LR .1C .

87
man/man7/map.7 Normal file
View file

@ -0,0 +1,87 @@
.TH MAP 7
.SH NAME
map \- digitized map formats
.SH DESCRIPTION
Files used by
.IR map (7)
are a sequence of structures of the form:
.PP
.EX
struct {
signed char patchlatitude;
signed char patchlongitude;
short n;
union {
struct {
short latitude;
short longitude;
} point[n];
struct {
short latitude;
short longitude;
struct {
signed char latdiff;
signed char londiff;
} point[\-n];
} highres;
} segment;
};
.EE
where
.B short
stands for 16-bit integers and there is no padding within or between
.BR structs .
Shorts are stored in little-endian order, low byte first.
To assure portability,
.I map
accesses them bytewise.
.PP
Fields
.L patchlatitude
and
.L patchlongitude
tell to what
10-degree by 10-degree
patch of the earth's surface a segment belongs.
Their values range from \-9 to 8 and from \-18 to 17,
respectively, and indicate the coordinates of the
southeast corner of the patch in units of 10 degrees.
.PP
Each segment of
.RB | n |
points is connected; consecutive segments
are not necessarily related.
Latitude and longitude
are measured in units of 0.0001 radian.
If
.B n
is negative, then
differences to the first and succeeding points
are measured in units of 0.00001 radian.
Latitude is counted positive to the north and
longitude positive to the west.
.PP
The patches are ordered lexicographically by
.L patchlatitude
then
.LR patchlongitude .
A printable
index to the first segment of each patch
in a file named
.I data
is kept in an associated file named
.IB data .x\f1.
Each line of an index file contains
.L patchlatitude,
.L patchlongitude
and the byte position
of the patch
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)
.br
The data comes from the World Data Bank I and II and
U.S. Government sources: the Census Bureau, Geological
Survey, and CIA.

308
man/man7/ms.7 Normal file
View file

@ -0,0 +1,308 @@
.TH MS 7
.hc %
.SH NAME
ms \- macros for formatting manuscripts
.SH SYNOPSIS
.B "nroff -ms"
[
.I options
]
.I file ...
.br
.B "troff -ms"
[
.I options
]
.I file ...
.SH DESCRIPTION
This package of
.I nroff
and
.IR troff (1)
macro definitions provides a canned formatting
facility for tech%nical papers in various formats.
.PP
The macro requests are defined below.
Many
.I nroff
and
.I troff
requests are unsafe in conjunction with
this package, but the following requests may be used with
impunity after the first
.BR .PP :
.LR .bp ,
.LR .br ,
.LR .sp ,
.LR .ls ,
.LR .na .
.PP
Output of the
.IR eqn (1),
.IR tbl (1),
.IR pic (1)
and
.IR grap (1)
preprocessors
for equations, tables, pictures, and graphs is acceptable as input.
.SH FILES
.B /sys/lib/tmac/tmac.s
.SH "SEE ALSO"
.br
M. E. Lesk,
``Typing Documents on the UNIX System: Using the \-ms Macros with Troff and Nroff'',
.I
Unix Research System Programmer's Manual,
Tenth Edition, Volume 2.
.br
.IR eqn (1),
.IR troff (1),
.IR tbl (1),
.IR pic (1)
.SH REQUESTS
.ta \w'..ND \fIdate\fR 'u +\w'Initial 'u +\w'Cause 'u
.br
.di x
\ka
.br
.di
.in \nau
.ti0
Request Initial Cause Explanation
.ti0
Value Break
.br
.in \nau
.ti0
\fL\&.1C\fP yes yes One column format on a new page.
.ti0
\fL\&.2C\fP no yes Two column format.
.ti0
\fL\&.AB\fP no yes Begin abstract.
.ti0
\fL\&.AE\fP - yes End abstract.
.ti0
\fL\&.AI\fP no yes Author's institution follows.
Suppressed in
.BR .TM .
.ti0
\fL\&.AT\fP no yes Print `Attached' and turn off line filling.
.ti0
\fL\&.AU\fP\fP\fP \fIx y\fR no yes Author's name follows.
.IR x " is location and " y " is"
extension, ignored except in
.BR TM .
.ti0
\fL\&.B\fP \fIx y\fR no no Print
.I x
in boldface, append
.IR y ;
if no argument switch to boldface.
.ti0
\fL\&.B1\fP no yes Begin text to be enclosed in a box.
.ti0
\fL\&.B2\fP no yes End boxed text.
.ti0
\fL\&.BI\fP \fIx y\fR no no Print
.I x
in bold italic and append
.IR y ;
if no argument switch to bold italic.
.ti0
\fL\&.BT\fP date no Bottom title, automatically invoked at
foot of page.
May be redefined.
.ti0
\fL\&.BX\fP \fIx\fR no no Print
.I x
in a box.
.ti0
\fL\&.CW\fP \fIx y\fR no no Constant width font for
.IR x ,
append
.IR y ;
if no argument switch to constant width.
.ti0
\fL\&.CT\fP no yes Print `Copies to' and turn off line filling.
.ti0
\fL\&.DA\fP \fIx\fR nroff no `Date line' at bottom of page
is
.IR x .
Default is today.
.ti0
\fL\&.DE\fP - yes End displayed text.
Implies
.BR .KE .
.ti0
\fL\&.DS\fP \fIx\fR no yes Start of displayed text,
to appear verbatim line-by-line:
.L I
indented (default),
.L L
left-justified,
.L C
centered,
.L B
(block) centered with straight left margin.
Implies
.BR .KS .
.ti0
\fL\&.EG\fP no - Print document in BTL format for `Engineer's Notes.' Must be first.
.ti0
\fL\&.EN\fP - yes Space after equation
produced by
.I neqn
or
.IR eqn (1).
.ti0
\fL\&.EQ\fP \fIx y\fR - yes Display equation.
Equation number is
.IR y .
Optional
.I x
is
.BR I ", " L ", " C
as in
.BR .DS .
.ti0
\fL\&.FE\fP - yes End footnote.
.ti0
\fL\&.FP\fP \fIx\fR - no Set font positions for a family, e.g.,
.L .FP lucidasans
.ti0
\fL\&.FS\fP no no Start footnote.
The note will be moved to the bottom of the page.
.ti0
\fL\&.HO\fP - no `Bell Laboratories, Holmdel,
New Jersey 07733'.
.ti0
\fL\&.I\fP \fIx y\fR no no Italicize
.IR x ,
append
.IR y ;
if no argument switch to italic.
.ti0
\fL\&.IH\fP no no `Bell Laboratories, Naperville, Illinois 60540'
.ti0
\fL\&.IM\fP no no Print document in BTL format for an internal memorandum. Must be first.
.ti0
\fL\&.IP\fP \fIx y\fR no yes Start indented paragraph,
with hanging tag
.IR x .
Indentation is
.I y
ens (default 5).
.ti0
\fL\&.KE\fP - yes End keep.
Put kept text on next page if not enough room.
.ti0
\fL\&.KF\fP no yes Start floating keep.
If the kept text must be moved to the next page,
float later text back to this page.
.ti0
\fL\&.KS\fP no yes Start keeping following text.
.ti0
\fL\&.LG\fP no no Make letters larger.
.ti0
\fL\&.LP\fP yes yes Start left-blocked paragraph.
.ti0
\fL\&.LT\fP no yes Start a letter; a non-empty first argument
produces a full Lucent letterhead, a second argument is a room number,
a third argument is a telephone number.
.ti0
\fL\&.MF\fP - - Print document in BTL format for `Memorandum for File.' Must be first.
.ti0
\fL\&.MH\fP - no `Bell Laboratories, Murray Hill,
New Jersey 07974'.
.ti0
\fL\&.MR\fP - - Print document in BTL format for `Memorandum for Record.' Must be first.
.ti0
\fL\&.ND\fP \fIdate\fR troff no Use date supplied (if any) only in
special BTL format positions; omit from page footer.
.ti0
\fL\&.NH\fP \fIn\fR - yes Same as
.BR .SH ,
with automatic section
numbers like `1.2.3';
.I n
is subsection level (default 1).
.ti0
\fL\&.NL\fP yes no Make letters normal size.
.ti0
\fL\&.P1\fP - yes Begin program display in constant width font.
.ti0
\fL\&.P2\fP - yes End program display.
.ti0
\fL\&.PE\fP - yes End picture; see
.IR pic (1).
.ti0
\fL\&.PF\fP - yes End picture; restore vertical
position.
.ti0
\fL\&.PP\fP no yes Begin paragraph.
First line indented.
.ti0
\fL\&.PS\fP \fIh w\fR - yes Start picture; height
and width in inches.
.ti0
\fL\&.PY\fP - no `Bell Laboratories, Piscataway, New Jersey 08854'
.ti0
\fL\&.QE\fP - yes End quoted material.
.ti0
\fL\&.QP\fP - yes Begin quoted paragraph (indent both margins).
.ti0
\fL\&.QS\fP - yes Begin quoted material (indent both margins).
.ti0
\fL\&.R\fP yes no Roman text follows.
.ti0
\fL\&.RE\fP - yes End relative indent level.
.ti0
\fL\&.RP\fP no - Cover sheet and first page for released
paper.
Must precede other requests.
.ti0
\fL\&.RS\fP - yes Start level of relative indentation
from which subsequent indentation is measured.
.ti0
\fL\&.SG\fP \fIx\fR no yes Insert signature(s) of author(s),
ignored except in
.B .TM
and
.BR .LT .
.IR x " is the reference line (initials of author and typist)."
.ti0
\fL\&.SH\fP - yes Section head follows,
font automatically bold.
.ti0
\fL\&.SM\fP no no Make letters smaller.
.ti0
\fL\&.TA\fP\ \fIx\fR... 5... no Set tabs in ens.
Default is 5 10 15 ...
.ti0
\fL\&.TE\fP - yes End table; see
.IR tbl (1).
.ti0
\fL\&.TH\fP - yes End heading section of table.
.ti0
\fL\&.TL\fP no yes Title follows.
.ti0
\fL\&.TM\fP\ \fIx\fR... no - Print document in BTL technical memorandum format.
Arguments are TM number, (quoted list of) case number(s), and file number.
Must precede other requests.
.ti0
\fL\&.TR\fP \fIx\fR - - Print in BTL technical report format; report number is \fIx\fR. Must be first.
.ti0
\fL\&.TS\fP \fIx\fR - yes Begin table; if
.I x
is
.B H
table heading is repeated on new pages.
.ti0
\fL\&.UL\fP \fIx\fR - no Underline argument (even in troff).
.ti0
\fL\&.UX\fP\ \fIy z\fP - no `\fIz\fRUNIX\fIy\fP';
first use gives registered trademark notice.
.ti0
\fL\&.WH\fP - no `Bell Laboratories, Whippany,
New Jersey 07981'.
.hc

336
man/man7/plot.7 Normal file
View file

@ -0,0 +1,336 @@
.TH PLOT 7
.SH NAME
plot \- graphics interface
.SH DESCRIPTION
Files of this format are interpreted by
.IR plot (1)
to draw graphics on the screen.
A
.I plot
file is a
.SM UTF
stream of
instruction lines.
Arguments are delimited by spaces, tabs, or commas.
Numbers may be floating point.
Punctuation marks (except
.LR : )
,
spaces, and tabs at the beginning of lines are ignored.
Comments run from
.L :
to newline.
Extra letters appended to a valid instruction are ignored.
Thus
.LR ...line ,
.LR line , and
.L li
all mean the same thing.
Arguments are interpreted as follows:
.TP
1.
If an instruction requires no arguments, the rest of the line is ignored.
.TP
2.
If it requires a string argument, then all the line
after the first field separator is passed as argument.
Quote marks may be used to preserve leading blanks.
Strings may include newlines represented as
.LR \en .
.TP
3.
Between numeric arguments alphabetic characters and
punctuation marks are ignored.
Thus
.L
line from 5 6 to 7 8
draws a line from (5, 6) to (7, 8).
.TP
4.
Instructions with numeric arguments remain in effect until
a new instruction is read.
Such commands may spill over many lines. Thus
the following sequence will draw a polygon
with vertices
(4.5, 6.77), (5.8, 5.6), (7.8, 4.55), and (10.0, 3.6).
.IP
.EX
move 4.5 6.77
vec 5.8, 5.6 7.8
4.55 10.0, 3.6 4.5, 6.77
.EE
.PP
The instructions are executed in order.
The last designated point in a
.BR line ", " move ", " rmove ,
.BR vec ", " rvec ", " arc ,
or
.B point
command becomes the `current point'
.RI ( X,Y )
for the next command.
.SS "Open & Close"
.PD0
.TP 10
.BI o " string"
Open plotting device.
For
.IR troff ,
.I string
specifies the size of the plot
(default is
.LR 6i ).
.TP 10
.B cl
Close plotting device.
.PD
.SS "Basic Plotting Commands"
.PD0
.TP 10
.B e
Start another frame of output.
.TP 10
.BI m " x y"
(move) Current point becomes
.I "x y."
.TP 10
.BI rm " dx dy"
Current point becomes
.I "X+dx Y+dy."
.TP 10
.BI poi " x y"
Plot the point
.I "x y"
and make it the current point.
.TP 10
.BI v " x y"
Draw a vector from the current point to
.I "x y."
.TP 10
.BI rv " dx dy"
Draw vector from current point to
.RI X + dx
.RI Y + dy
.TP 10
.BI li " x1 y1 x2 y2"
Draw a line from
.I "x1 y1"
to
.I "x2 y2."
Make the current point
.I "x2 y2."
.TP 10
.BI t " string"
Place the
.I string
so that its
first character is centered on the current point (default).
If
.I string
begins with
.L \eC
.RL ( \eR ),
it is centered (right-adjusted) on the current point.
A backslash at the beginning of the string may
be escaped with another backslash.
.TP 10
.BI a " x1 y1 x2 y2 xc yc r"
Draw a circular arc from
.I "x1 y1"
to
.I "x2 y2"
with center
.I "xc yc"
and radius
.IR r .
If the radius is positive, the arc is drawn counterclockwise;
negative, clockwise.
The starting point is exact but the ending point is approximate.
.TP 10
.BI ci " xc yc r"
Draw a circle centered at
.I "xc yc"
with radius
.IR r .
If the range and frame parameters do not specify a square,
the `circle' will be elliptical.
.TP 10
.BI di " xc yc r"
Draw a disc centered at
.I "xc yc"
with radius
.I r
using the filling color (see
.B cfill
below).
.TP 10
.BI bo " x1 y1 x2 y2"
Draw a box with lower left corner at
.I "x1 y1"
and upper right corner at
.I "x2 y2."
.TP 10
.BI sb " x1 y1 x2 y2"
Draw a solid box with lower left corner at
.I "x1 y1"
and upper right corner at
.I "x2 y2"
using the filling color (see
.B cfill
below).
.TP 10
.BI par " x1 y1 x2 y2 xg yg"
Draw a parabola from
.I "x1 y1"
to
.I "x2 y2"
`guided' by
.I "xg yg."
The parabola passes through the midpoint of the line joining
.I "xg yg"
with the midpoint of the line
joining
.I "x1 y1"
and
.I "x2 y2"
and is tangent to the lines from
.I "xg yg"
to the endpoints.
.TP 10
.BI "pol { {" "x1 y1 ... xn yn" } " ... " { "X1 Y1 ... Xm Ym\fP} }\fI"
Draw polygons with vertices
.I "x1 y1 ... xn yn"
and
.I "X1 Y1 ... Xm Ym."
If only one polygon is specified, the inner brackets are
not needed.
.TP 10
.BI "fi { {" "x1 y1 ... xn yn" } " ... " { "X1 Y1 ... Xm Ym\fP} }\fI"
Fill a polygon.
The arguments are the same as those for
.B pol
except that the first vertex is automatically repeated to
close each polygon.
The polygons do not have to be connected.
Enclosed polygons appear as holes.
.TP 10
.BI "sp { {" "x1 y1 ... xn yn" } " ... " { "X1 Y1 ... Xm Ym\fL} }\fI"
Draw a parabolic spline guided by
.I "x1 y1 ... xn yn"
with simple endpoints.
.TP 10
.BI "fsp { {" "x1 y1 ... xn yn" } " ... " { "X1 Y1 ... Xm Ym\fL} }\fI"
Draw a parabolic spline guided by
.I "x1 y1 ... xn yn"
with double first endpoint.
.TP 10
.BI "lsp { {" "x1 y1 ... xn yn" } " ... " { "X1 Y1 ... Xm Ym\fL} }\fI"
Draw a parabolic spline guided by
.I "x1 y1 ... xn yn"
with double last endpoint.
.TP 10
.BI "dsp { {" "x1 y1 ... xn yn" } " ... " { "X1 Y1 ... Xm Ym\fL} }\fI"
Draw a parabolic spline guided by
.I "x1 y1 ... xn yn"
with double endpoints.
.TP 10
.BI "csp { {" "x1 y1 ... xn yn" } " ... " { "X1 Y1 ... Xm Ym\fL} }\fI"
.TP 10
.BI in " filename"
(include) Take commands from
.IR filename .
.TP 10
.BI de " string " { " commands " }
Define
.I string
as
.IR commands .
.TP 10
.BI ca " string scale"
Invoke commands defined as
.I string
applying
.I scale
to all coordinates.
.PD
.SS "Commands Controlling the Environment"
.PD0
.TP 10
.BI co " string"
Use color given by first character of
.IR string ,
one of
.BR red ,
.BR yellow ,
.BR green ,
.BR blue ,
.BR cyan ,
.BR magenta ,
.BR white ,
and
.BR kblack .
.TP 10
.BI pe " string"
Use
.I string
as the style for drawing lines.
The available pen styles are:
.BR solid ,
.BR dott [ed],
.BR short ,
.BR long ,
.BR dotd [ashed] ,
.BR cdash ,
.BR ddash
.TP 10
.BI cf " string"
Color for filling (see
.BR co ,
above).
.TP 10
.BI ra " x1 y1 x2 y2"
The data will fall between
.I "x1 y1"
and
.I "x2 y2."
The plot will be magnified or reduced to fit
the device as closely as possible.
.IP
Range settings that exactly fill the plotting area
with unity scaling appear below for
devices supported by the filters of
.IR plot (1).
The upper limit is just outside the plotting area.
In every case the plotting area is taken to be square;
points outside may be displayable on
devices with nonsquare faces.
.TP 10
.BI fr " px1 py1 px2 py2"
Plot the data in the fraction of the display
specified by
.I "px1 py1"
for lower left corner
and
.I "px2 py2"
for upper right corner.
Thus
.L frame .5 0 1. .5
plots in the lower right
quadrant of the display;
.L frame 0. 1. 1. 0.
uses the whole display but
inverts the
.I y
coordinates.
.TP 10
.B sa
Save the current environment, and move to a new one.
The new environment inherits the old one.
There are 7 levels.
.TP 10
.B re
Restore previous environment.
.PD
.SH "SEE ALSO"
.IR plot (1),
.IR graph (1)

417
man/man7/plumb.7 Normal file
View file

@ -0,0 +1,417 @@
.TH PLUMB 7
.SH NAME
plumb \- format of plumb messages and rules
.SH SYNOPSIS
.B #include <plumb.h>
.SH DESCRIPTION
.SS "Message format
The messages formed by the
.IR plumb (3)
library are formatted for transmission between
processes into textual form, using newlines to separate
the fields.
Only the data field may contain embedded newlines.
The fields occur in a specified order,
and each has a name, corresponding to the elements
of the
.B Plumbmsg
structure, that is used in the plumbing rules.
The fields, in order, are:
.RS
.TF ndata
.TP
.B src
application/service generating message
.TP
.B dst
destination `port' for message
.TP
.B wdir
working directory (used if data is a file name)
.TP
.B type
form of the data, e.g.
.B text
.TP
.B attr
attributes of the message, in
.IB name = value
pairs separated by white space
(the value must follow the usual quoting convention if it contains
white space or quote characters or equal signs; it cannot contain a newline)
.TP
.B ndata
number of bytes of data
.TP
.B data
the data itself
.RE
At the moment, only textual data
.RB ( type=text )
is supported.
.PD
.PP
All fields are optional, but
.B type
should usually be set since it describes the form of the data, and
.B ndata
must be an accurate count (possibly zero) of the number of bytes of data.
A missing field is represented by an empty line.
.SS "Plumbing rules
The
.B plumber
(see
.IR plumb (1))
receives messages on its
.B send
port (applications
.I send
messages there), interprets and reformats them, and (typically) emits them from a destination port.
Its behavior is determined by a plumbing rules file, default
.BR /usr/$user/lib/plumbing ,
which defines a set of pattern/action rules with which to analyze, rewrite, and dispatch
received messages.
.PP
The file is a sequence of rule sets, each of which is a set of one-line rules
called patterns and actions.
There must be at least one pattern and one action in each rule set.
(The only exception is that a rule set may contain nothing but
.B plumb
.B to
rules; such a rule set declares the named ports but has no other effect.)
A blank line terminates a rule set.
Lines beginning with a
.B #
character are commentary and are regarded as blank lines.
.PP
A line of the form
.EX
include \f2file\fP
.EE
substitutes the contents of
.I file
for the line, much as in a C
.B #include
statement. Unlike in C, the file name is not quoted.
If
.I file
is not an absolute path name, or one beginning
.B ./
or
.BR ../ ,
.I file
is looked for first in the directory in which the plumber is executing,
and then in
.BR /sys/lib/plumb .
.PP
When a message is received by the
.BR plumber ,
the rule sets are examined in order.
For each rule set, if the message matches all the patterns in the rule set,
the actions associated with the rule set are triggered to dispose of the message.
If a rule set is triggered, the rest are ignored for this message.
If none is triggered, the message is discarded (giving a write error to the sender)
unless it has a
.B dst
field that specifies an existing port, in which case the message is emitted, unchanged, from there.
.PP
Patterns and actions all consist of three components: an
.IR object ,
a
.IR verb ,
and arguments.
These are separated by white space on the line.
The arguments may contain quoted strings and variable substitutions,
described below, and in some cases contain multiple words.
The object and verb are single words from a pre-defined set.
.PP
The object in a pattern is the name of an element of the message, such as
.B src
or
.BR data ,
or the special case
.BR arg ,
which refers to the argument component of the current rule.
The object in an action is always the word
.BR plumb .
.PP
The verbs in the pattern rules
describe how the objects and arguments are to be interpreted.
Within a rule set, the patterns are evaluated in sequence; if one fails,
the rule set fails.
Some verbs are predicates that check properties of the message; others rewrite
components of the message and implicitly always succeed.
Such rewritings are permanent, so rules that specify them should be placed after
all pattern-matching rules in the rule set.
.RS
.TF delete
.TP
.B add
The object must be
.BR attr .
Append the argument, which must be a sequence of
.IB name = value
pairs, to the list of attributes of the message.
.TP
.B delete
The object must be
.BR attr .
If the message has an attribute whose name is the argument,
delete it from the list of attributes of the message.
(Even if the message does not, the rule matches the message.)
.TP
.B is
If the text of the object is identical to the text of the argument,
the rule matches.
.TP
.B isdir
If the text of the object
is the name of an existing directory, the rule matches and
sets the variable
.B $dir
to that directory name.
.TP
.B isfile
If the text of the object is the name of an existing file (not a directory),
the rule matches and sets the variable
.B $file
to that file name.
.TP
.B matches
If the entire text of the object matches the regular expression
specified in the argument, the rule matches.
This verb is described in more detail below.
.TP
.B set
The value of the object is set to the value of the argument.
.RE
.PP
The
.B matches
verb has special properties that enable the rules to select which portion of the
data is to be sent to the destination.
By default, a
.B data
.B matches
rule requires that the entire text matches the regular expression.
If, however, the message has an attribute named
.BR click ,
that reports that the message was produced by a mouse click within the
text and that the regular expressions in the rule set should be used to
identify what portion of the data the user intended.
Typically, a program such as an editor will send a white-space delimited
block of text containing the mouse click, using the value of the
.B click
attribute (a number starting from 0) to indicate where in the textual data the user pointed.
.PP
When the message has a
.B click
attribute, the
.B data
.B matches
rules extract the longest leftmost match to the regular expression that contains or
abuts the textual location identified by the
.BR click .
For a sequence of such rules within a given rule set, each regular expression, evaluated
by this specification, must match the same subset of the data for the rule set to match
the message.
For example, here is a pair of patterns that identify a message whose data contains
the name of an existing file with a conventional ending for an encoded picture file:
.EX
data matches '[a-zA-Z0-9_\-./]+'
data matches '([a-zA-Z0-9_\-./]+)\.(jpe?g|gif|bit|ps|pdf)'
.EE
The first expression extracts the largest subset of the data around the click that contains
file name characters; the second sees if it ends with, for example,
.BR \&.jpeg .
If only the second pattern were present, a piece of text
.B horse.gift
could be misinterpreted as an image file named
.BR horse.gif .
.PP
If a
.B click
attribute is specified in a message, it will be deleted by the
.B plumber
before sending the message if the
.B data
.B matches
rules expand the selection.
.PP
The action rules all have the object
.BR plumb .
There are only three verbs for action rules:
.RS
.TF client
.TP
.B to
The argument is the name of the port to which the message will be sent.
If the message has a destination specified, it must match the
.B to
port of the rule set or the entire rule set will be skipped.
(This is the only rule that is evaluated out of order.)
.TP
.B client
If no application has the port open, the arguments to a
.B plumb
.B start
rule specify a shell program to run in response to the message.
The message will be held, with the supposition that the program
will eventually open the port to retrieve it.
.TP
.B start
Like
.BR client ,
but the message is discarded.
Only one
.B start
or
.B client
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).
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
.BR rc .
Only one variable assignment may appear on a line.
The
.B plumber
also maintains some built-in variables:
.RS
.TF $wdir
.TP
.B $0
The text that matched the entire regular expression in a previous
.B data
.B matches
rule.
.BR $1 ,
.BR $2 ,
etc. refer to text matching the first, second, etc. parenthesized subexpression.
.TP
.B $attr
The textual representation of the attributes of the message.
.TP
.B $data
The contents of the data field of the message.
.TP
.B $dir
The directory name resulting from a successful
.B isdir
rule.
If no such rule has been applied, it is the string constructed
syntactically by interpreting
.B data
as a file name in
.BR wdir .
.TP
.B $dst
The contents of the
.B dst
field of the message.
.TP
.B $file
The file name resulting from a successful
.B isfile
rule.
If no such rule has been applied, it is the string constructed
syntactically by interpreting
.B data
as a file name in
.BR wdir .
.TP
.B $type
The contents of the
.B type
field of the message.
.TP
.B $src
The contents of the
.B src
field of the message.
.TP
.B $wdir
The contents of the
.B wdir
field of the message.
.RE
.SH EXAMPLE
The following is a modest, representative file of plumbing rules.
.EX
# these are generally in order from most specific to least,
# since first rule that fires wins.
addr=':(#?[0-9]+)'
protocol='(https?|ftp|file|gopher|mailto|news|nntp|telnet|wais)'
domain='[a-zA-Z0-9_@]+([.:][a-zA-Z0-9_@]+)*/?[a-zA-Z0-9_?,%#~&/\e-]+'
file='([:.][a-zA-Z0-9_?,%#~&/\e-]+)*'
# image files go to page
type is text
data matches '[a-zA-Z0-9_\e-./]+'
data matches '([a-zA-Z0-9_\e-./]+)\.(jpe?g|gif|bit)'
arg isfile $0
plumb to image
plumb start page -w $file
# URLs go to web browser
type is text
data matches $protocol://$domain$file
plumb to web
plumb start window webbrowser $0
# existing files, possibly tagged by line number, go to edit/sam
type is text
data matches '([.a-zA-Z0-9_/\-]+[a-zA-Z0-9_/\e-])('$addr')?'
arg isfile $1
data set $file
attr add addr=$3
plumb to edit
plumb start window sam $file
# .h files are looked up in /sys/include and passed to edit/sam
type is text
data matches '([a-zA-Z0-9]+\e.h)('$addr')?'
arg isfile /sys/include/$1
data set $file
attr add addr=$3
plumb to edit
plumb start window sam $file
.EE
.PP
The following simple plumbing rules file is a good beginning set of rules.
.EX
# to update: cp /usr/$user/lib/plumbing /mnt/plumb/rules
editor = acme
# or editor = sam
include basic
.EE
.SH FILES
.TF /usr/$user/lib/plumbing
.TP
.B /usr/$user/lib/plumbing
default rules file.
.TP
.B /mnt/plumb
mount point for
.IR plumber (4).
.TP
.B /sys/lib/plumb
directory for
.B include
files.
.TP
.B /sys/lib/plumb/fileaddr
public macro definitions.
.TP
.B /sys/lib/plumb/basic
basic rule set.
.SH "SEE ALSO"
.IR plumb (1),
.IR plumb (3),
.IR plumber (4),
.IR regexp (7)

8
man/man7/regexp.7
View file

@ -1,4 +1,4 @@
.TH REGEXP9 7
.TH REGEXP 7
.de EX
.nf
.ft B
@ -17,11 +17,11 @@
.if n .RB ` \\$1 '
..
.SH NAME
regexp9 \- Plan 9 regular expression notation
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 regexp9 (3).
.IR regexp (3).
It is the form used by
.IR egrep (1)
before
@ -147,4 +147,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 regexp9 (3)
.IR regexp (3)

150
man/man7/regexp9.7 Normal file
View file

@ -0,0 +1,150 @@
.TH REGEXP9 7
.de EX
.nf
.ft B
..
.de EE
.fi
.ft R
..
.de LR
.if t .BR \\$1 \\$2
.if n .RB ` \\$1 '\\$2
..
.de L
.nh
.if t .B \\$1
.if n .RB ` \\$1 '
..
.SH NAME
regexp9 \- Plan 9 regular expression notation
.SH DESCRIPTION
This manual page describes the regular expression
syntax used by the Plan 9 regular expression library
.IR regexp9 (3).
It is the form used by
.IR egrep (1)
before
.I egrep
got complicated.
.PP
A
.I "regular expression"
specifies
a set of strings of characters.
A member of this set of strings is said to be
.I matched
by the regular expression. In many applications
a delimiter character, commonly
.LR / ,
bounds a regular expression.
In the following specification for regular expressions
the word `character' means any character (rune) but newline.
.PP
The syntax for a regular expression
.B e0
is
.IP
.EX
e3: literal | charclass | '.' | '^' | '$' | '(' e0 ')'
e2: e3
| e2 REP
REP: '*' | '+' | '?'
e1: e2
| e1 e2
e0: e1
| e0 '|' e1
.EE
.PP
A
.B literal
is any non-metacharacter, or a metacharacter
(one of
.BR .*+?[]()|\e^$ ),
or the delimiter
preceded by
.LR \e .
.PP
A
.B charclass
is a nonempty string
.I s
bracketed
.BI [ \|s\| ]
(or
.BI [^ s\| ]\fR);
it matches any character in (or not in)
.IR s .
A negated character class never
matches newline.
A substring
.IB a - b\f1,
with
.I a
and
.I b
in ascending
order, stands for the inclusive
range of
characters between
.I a
and
.IR b .
In
.IR s ,
the metacharacters
.LR - ,
.LR ] ,
an initial
.LR ^ ,
and the regular expression delimiter
must be preceded by a
.LR \e ;
other metacharacters
have no special meaning and
may appear unescaped.
.PP
A
.L .
matches any character.
.PP
A
.L ^
matches the beginning of a line;
.L $
matches the end of the line.
.PP
The
.B REP
operators match zero or more
.RB ( * ),
one or more
.RB ( + ),
zero or one
.RB ( ? ),
instances respectively of the preceding regular expression
.BR e2 .
.PP
A concatenated regular expression,
.BR "e1\|e2" ,
matches a match to
.B e1
followed by a match to
.BR e2 .
.PP
An alternative regular expression,
.BR "e0\||\|e1" ,
matches either a match to
.B e0
or a match to
.BR e1 .
.PP
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 regexp9 (3)

41
man/man7/thumbprint.7 Normal file
View file

@ -0,0 +1,41 @@
.TH THUMBPRINT 7
.SH NAME
thumbprint \- public key thumbprints
.SH DESCRIPTION
.PP
Applications in Plan 9 that use public keys for authentication,
for example by calling
.B tlsClient
and
.B okThumbprint
(see
.IR 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
about which servers can be trusted for which applications,
thereby playing the role taken by certificate authorities
in PKI-based systems.
By convention, these lists are stored as files in
.B /sys/lib/tls/
and protected by normal file system permissions.
.PP
Such a thumbprint file comprises lines made up of
attribute/value pairs of the form
.IB attr = value
or
.IR attr .
The first attribute must be
.B x509
and the second must be
.BI sha1= {hex checksum of binary certificate}.
All other attributes are treated as comments.
The file may also contain lines of the form
.BI #include file
.PP
For example, a web server might have thumbprint
.EX
x509 sha1=8fe472d31b360a8303cd29f92bd734813cbd923c cn=*.cs.bell-labs.com
.EE
.SH "SEE ALSO"
.IR pushtls (3)

2
man/man7/utf.7
View file

@ -57,7 +57,7 @@ in order to work properly with non-\c
.SM ASCII
input.
See
.IR rune (2).
.IR rune (3).
.PP
Letting numbers be binary,
a rune x is converted to a multibyte