From 058b0118a52061ad57694c01fc8763b22b789c4d Mon Sep 17 00:00:00 2001 From: rsc Date: Mon, 3 Jan 2005 06:40:20 +0000 Subject: Some man pages. --- man/man7/INDEX | 18 +++ man/man7/color.7 | 150 ++++++++++++++++++ man/man7/face.7 | 115 ++++++++++++++ man/man7/font.7 | 87 +++++++++++ man/man7/image.7 | 205 +++++++++++++++++++++++++ man/man7/man.7 | 249 ++++++++++++++++++++++++++++++ man/man7/map.7 | 87 +++++++++++ man/man7/ms.7 | 308 +++++++++++++++++++++++++++++++++++++ man/man7/plot.7 | 336 ++++++++++++++++++++++++++++++++++++++++ man/man7/plumb.7 | 417 ++++++++++++++++++++++++++++++++++++++++++++++++++ man/man7/regexp.7 | 8 +- man/man7/regexp9.7 | 150 ++++++++++++++++++ man/man7/thumbprint.7 | 41 +++++ man/man7/utf.7 | 2 +- 14 files changed, 2168 insertions(+), 5 deletions(-) create mode 100644 man/man7/INDEX create mode 100644 man/man7/color.7 create mode 100644 man/man7/face.7 create mode 100644 man/man7/font.7 create mode 100644 man/man7/image.7 create mode 100644 man/man7/man.7 create mode 100644 man/man7/map.7 create mode 100644 man/man7/ms.7 create mode 100644 man/man7/plot.7 create mode 100644 man/man7/plumb.7 create mode 100644 man/man7/regexp9.7 create mode 100644 man/man7/thumbprint.7 (limited to 'man/man7') diff --git a/man/man7/INDEX b/man/man7/INDEX new file mode 100644 index 00000000..79302660 --- /dev/null +++ b/man/man7/INDEX @@ -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 diff --git a/man/man7/color.7 b/man/man7/color.7 new file mode 100644 index 00000000..c8b536a0 --- /dev/null +++ b/man/man7/color.7 @@ -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) diff --git a/man/man7/face.7 b/man/man7/face.7 new file mode 100644 index 00000000..08b04a46 --- /dev/null +++ b/man/man7/face.7 @@ -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) diff --git a/man/man7/font.7 b/man/man7/font.7 new file mode 100644 index 00000000..f651a58a --- /dev/null +++ b/man/man7/font.7 @@ -0,0 +1,87 @@ +.TH FONT 7 +.SH NAME +font, subfont \- external format for fonts and subfonts +.SH SYNOPSIS +.B #include +.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) diff --git a/man/man7/image.7 b/man/man7/image.7 new file mode 100644 index 00000000..6e613f9c --- /dev/null +++ b/man/man7/image.7 @@ -0,0 +1,205 @@ +.TH IMAGE 7 +.SH NAME +image \- external format for images +.SH SYNOPSIS +.B #include +.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) diff --git a/man/man7/man.7 b/man/man7/man.7 new file mode 100644 index 00000000..fbfa9f2a --- /dev/null +++ b/man/man7/man.7 @@ -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 . diff --git a/man/man7/map.7 b/man/man7/map.7 new file mode 100644 index 00000000..80e1eebf --- /dev/null +++ b/man/man7/map.7 @@ -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. diff --git a/man/man7/ms.7 b/man/man7/ms.7 new file mode 100644 index 00000000..b6c6788e --- /dev/null +++ b/man/man7/ms.7 @@ -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 diff --git a/man/man7/plot.7 b/man/man7/plot.7 new file mode 100644 index 00000000..452ab197 --- /dev/null +++ b/man/man7/plot.7 @@ -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) diff --git a/man/man7/plumb.7 b/man/man7/plumb.7 new file mode 100644 index 00000000..a3c10e11 --- /dev/null +++ b/man/man7/plumb.7 @@ -0,0 +1,417 @@ +.TH PLUMB 7 +.SH NAME +plumb \- format of plumb messages and rules +.SH SYNOPSIS +.B #include +.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) diff --git a/man/man7/regexp.7 b/man/man7/regexp.7 index 14a90d0f..75640b9c 100644 --- a/man/man7/regexp.7 +++ b/man/man7/regexp.7 @@ -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) diff --git a/man/man7/regexp9.7 b/man/man7/regexp9.7 new file mode 100644 index 00000000..14a90d0f --- /dev/null +++ b/man/man7/regexp9.7 @@ -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) diff --git a/man/man7/thumbprint.7 b/man/man7/thumbprint.7 new file mode 100644 index 00000000..743172de --- /dev/null +++ b/man/man7/thumbprint.7 @@ -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) diff --git a/man/man7/utf.7 b/man/man7/utf.7 index 97b7b1e7..a2409457 100644 --- a/man/man7/utf.7 +++ b/man/man7/utf.7 @@ -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 -- cgit v1.2.3