sync changes to p9p section 1 man pages back to plan9. mostly minor changes to reduce diff size. some files have not been touched. e.g. acid, calendar, colors, db, gview, jpg, kill, page, rio some files got a previously missing SOURCES section e.g. replica spin lp troff2html faces and one or two more Notes: Sun Apr 17 09:09:06 EDT 2005 rsc Thanks! Three small things that I changed after applying. 1. I took a bunch of .TF requests out of FILES sections in plan9port because the paths are so much longer (e.g., /usr/local/plan9/font instead of /lib/font), but they can stay in the real man pages. 2. There were pieces in the mk man page that didn't belong, for example the HISTORY section (put in for the Unix version long ago), and the reference to DOCPREFIX and the Tenth Edition Unix manuals. 3. If the SOURCES section is many files in one directory, feel free to list just the directory (e.g., replica) Thanks again. It's great to get those updated. Russ Reference: /n/sources/patch/applied/doc-man-1-p9psync Date: Sun Apr 17 12:02:40 CES 2005 Reviewed-by: rsc --- /sys/man/1/acme Sun Apr 17 11:19:39 2005 +++ /sys/man/1/acme Sun Apr 17 11:19:34 2005 @@ -480,7 +480,12 @@ .BR /sys/src/cmd/sam/+Errors . The environment of such commands contains the variable .B $% -with value set to the filename of the window in which the command is run. +with value set to the filename of the window in which the command is run, +and +.B $winid +set to the window's id number +(see +.IR acme (4)). .SS "Mouse button 3 Pointing at text with button 3 instructs .I acme --- /sys/man/1/ascii Sun Apr 17 11:19:53 2005 +++ /sys/man/1/ascii Sun Apr 17 11:19:50 2005 @@ -146,7 +146,6 @@ .B "look 039 /lib/unicode" See the start of the Greek alphabet's encoding in the Unicode Standard. .SH FILES -.TF /lib/unicode .TP .B /lib/unicode table of characters and descriptions. @@ -155,7 +154,7 @@ .br .B /sys/src/cmd/unicode.c .SH "SEE ALSO" -.IR look (1) +.IR look (1), .IR tcs (1), .IR utf (6), .IR font (6) --- /sys/man/1/bc Sun Apr 17 11:20:11 2005 +++ /sys/man/1/bc Sun Apr 17 11:20:08 2005 @@ -281,12 +281,12 @@ or .L ! operators. -.br +.PP A .L for statement must have all three .LR E s. -.br +.PP A .L quit is interpreted when read, not when executed. --- /sys/man/1/bundle Sun Apr 17 11:20:33 2005 +++ /sys/man/1/bundle Sun Apr 17 11:20:30 2005 @@ -49,5 +49,5 @@ .SH BUGS .I Bundle will not create directories and is unsatisfactory for non-text files. -.br +.PP Beware of gift horses. --- /sys/man/1/cal Sun Apr 17 11:20:56 2005 +++ /sys/man/1/cal Sun Apr 17 11:20:53 2005 @@ -39,7 +39,7 @@ .SH BUGS The year is always considered to start in January even though this is historically naive. -.br +.PP Beware that .L "cal 90" refers to the early Christian era, --- /sys/man/1/cat Sun Apr 17 11:21:23 2005 +++ /sys/man/1/cat Sun Apr 17 11:21:20 2005 @@ -57,7 +57,8 @@ .I nline lines. .PP -Read always executes a single +.I Read +always executes a single .B write for each line of input, which can be helpful when preparing input to programs that expect line-at-a-time data. --- /sys/man/1/dc Sun Apr 17 11:21:54 2005 +++ /sys/man/1/dc Sun Apr 17 11:21:51 2005 @@ -223,15 +223,15 @@ \fLv\fR max(\fIs,sa\fR) .fi .SH EXAMPLES +.LP +Print the first ten values of +.IR n ! +.IP .EX [la1+dsa*pla10>y]sy 0sa1 lyx .EE -.ns -.IP -Print the first ten values of -.IR n ! .SH SOURCE .B /sys/src/cmd/dc.c .SH "SEE ALSO" --- /sys/man/1/deroff Sun Apr 17 11:22:29 2005 +++ /sys/man/1/deroff Sun Apr 17 11:22:26 2005 @@ -112,6 +112,6 @@ delimiters for .I eqn are in effect. -.br +.PP Text inside macros is emitted at place of definition, not place of call. --- /sys/man/1/doctype Sun Apr 17 11:23:05 2005 +++ /sys/man/1/doctype Sun Apr 17 11:23:02 2005 @@ -4,8 +4,13 @@ .SH SYNOPSIS .B doctype [ -.I option ... -] [ +.B -n +] +[ +.B -T +.I dev +] +[ .I file ] \&... @@ -32,7 +37,9 @@ .I nroff instead of .IR troff . -Other options are passed to +The +.B -T +option is passed to .IR troff . .SH EXAMPLES .TP --- /sys/man/1/idiff Sun Apr 17 11:23:44 2005 +++ /sys/man/1/idiff Sun Apr 17 11:23:41 2005 @@ -14,7 +14,8 @@ merges .I file1 and -.IR file2 . +.I file2 +onto standard output. Wherever .I file1 and @@ -23,7 +24,8 @@ .I idiff displays the differences in the style of .RB `` diff -.RB -n '' +.BR -n '' +on standard error and prompts the user to select a chunk. Valid responses are: .TP @@ -54,9 +56,10 @@ .B -b and .B -w -flags -are simply -passed through to +flags, +if passed, +are +passed to .IR diff . .SH FILES .B /tmp/idiff.* @@ -68,5 +71,3 @@ Kernighan and Pike, .IR "The Unix Programming Environment" , Prentice-Hall, 1984. -.SH BUGS -This is a poorly-written manual page. --- /sys/man/1/join Sun Apr 17 11:24:27 2005 +++ /sys/man/1/join Sun Apr 17 11:24:25 2005 @@ -143,6 +143,5 @@ the sequence is that of .BI "sort -t" x .BI -k y , y\f1. -.br +.PP One of the files must be randomly accessible. - --- /sys/man/1/jpg Sun Apr 17 11:25:13 2005 +++ /sys/man/1/jpg Sun Apr 17 11:25:10 2005 @@ -1,6 +1,6 @@ .TH JPG 1 .SH NAME -jpg, gif, png, ppm, ico, togif, toppm, topng, toico \- view and convert pictures +jpg, gif, png, ppm, bmp, yuv, ico, togif, toppm, topng, toico \- view and convert pictures .SH SYNOPSIS .B jpg [ @@ -8,26 +8,37 @@ ] [ .I file ... ] -.PP +.br .B gif [ .B -39cdektv ] [ .I file ... ] -.PP +.br .B png [ .B -39cdektv ] [ .I file ... ] +.br .B ppm [ .B -39cdektv ] [ .I file ... ] +.br +.B bmp +[ +.I file +] +.br +.B yuv +[ +.I file +] .PP .B togif [ @@ -50,7 +61,7 @@ ] .I file ... ] -.PP +.br .B toppm [ .B -c @@ -58,7 +69,7 @@ ] [ .I file ] -.PP +.br .B topng [ .B -c @@ -75,7 +86,7 @@ [ .I file ] -.PP +.br .B toico [ .I file ... @@ -85,8 +96,10 @@ .IR Jpg , .IR gif , .IR png , +.IR ppm , +.IR bmp , and -.I ppm +.IR yuv . read files in the corresponding formats and, by default, display them in the current window; options cause them instead to convert the images to Plan 9 image format and write them to standard output. --- /sys/man/1/lex Sun Apr 17 11:26:00 2005 +++ /sys/man/1/lex Sun Apr 17 11:25:58 2005 @@ -77,5 +77,5 @@ .SH BUGS Cannot handle .SM UTF. -.br +.PP The asteroid to kill this dinosaur is still in orbit. --- /sys/man/1/look Sun Apr 17 11:26:53 2005 +++ /sys/man/1/look Sun Apr 17 11:26:50 2005 @@ -77,10 +77,9 @@ .IR grep (1) .SH DIAGNOSTICS The exit status is -.B \&"not found" +.RB `` "not found" '' if no match is found, and -.B \&"no dictionary" +.RB `` "no dictionary" '' if .I file or the default dictionary cannot be opened. - --- /sys/man/1/ls Sun Apr 17 11:27:50 2005 +++ /sys/man/1/ls Sun Apr 17 11:27:47 2005 @@ -111,14 +111,13 @@ as follows: the first character is .TP -.B d +.B d if the entry is a directory; -.PD 0 .TP -.B a +.B a if the entry is an append-only file; .TP -.B - +.B - if the entry is a plain file. .PD .PP @@ -157,5 +156,5 @@ .br .B /rc/bin/lc .SH SEE ALSO -.IR stat (2) +.IR stat (2), .IR mc (1) --- /sys/man/1/man Sun Apr 17 11:28:49 2005 +++ /sys/man/1/man Sun Apr 17 11:28:46 2005 @@ -4,7 +4,7 @@ .SH SYNOPSIS .B man [ -.I option ... +.B -ntpP ] [ .I section ... @@ -40,6 +40,11 @@ .PP The options are: .TP +.B -n +(Default) +Print the pages on the standard output using +.IR nroff . +.TP .B -p Run .IR proof (1) @@ -52,14 +57,10 @@ .TP .B -t Run -.I troff +.IR troff (1) and send its output to standard output. -.TP -.B -n -(Default) -Print the pages on the standard output using -.IR nroff . +.PD .PP .B Lookman prints the names of all manual sections that contain @@ -69,10 +70,9 @@ .PP .B Sig prints the signature (i.e. C definition) of the -.IR functions +.IR function 's given on the command line. .SH FILES -.TF /sys/lib/man/lookman/index .TP .B /sys/man/?/* .I troff @@ -93,13 +93,16 @@ .br .B /rc/bin/lookman .SH "SEE ALSO" +.IR page (1), .IR proof (1) .SH BUGS The manual was intended to be typeset; some detail is sacrificed on text terminals. -.br +.PP There is no automatic mechanism to keep the indices up to date. -.br -Except for special cases, it doesn't recognize things that should be run through +.PP +Except for special cases, +.I man +doesn't recognize things that should be run through .I tbl and/or .IR eqn . --- /sys/man/1/mc Sun Apr 17 11:29:51 2005 +++ /sys/man/1/mc Sun Apr 17 11:29:48 2005 @@ -19,6 +19,8 @@ print positions. If run in a .IR rio (1) +or +.IR acme (1) window, the default .I N is the number of blanks that will fit across the window; @@ -34,6 +36,8 @@ .B /sys/src/cmd/mc.c .SH "SEE ALSO" .IR rio (1), +.IR acme (1), +.IR acme (4), .IR pr (1), .I lc in --- /sys/man/1/mk Sun Apr 17 11:31:01 2005 +++ /sys/man/1/mk Sun Apr 17 11:30:58 2005 @@ -133,7 +133,7 @@ .IP .EX target: prereq1 prereq2 - rc \f2recipe using\fP prereq1, prereq2 \f2to build\fP target + \f2recipe using\fP prereq1, prereq2 \f2to build\fP target .EE .PP When the recipe is executed, @@ -254,6 +254,8 @@ environment variables. A legal reference of the form .B $OBJ +or +.B ${name} is expanded as in .IR rc (1). A reference of the form @@ -303,6 +305,7 @@ .IR mk . A variable assignment argument overrides the first (but not any subsequent) assignment to that variable. +.PP The variable .B MKFLAGS contains all the option arguments (arguments starting with @@ -628,21 +631,29 @@ .SH SEE ALSO .IR rc (1), .IR regexp (6) -.br +.PP A. Hume, -``Mk: a Successor to Make''. -.br -Bob Flandrena, -``Plan 9 Mkfiles''. +``Mk: a Successor to Make'' +(Tenth Edition Research Unix Manuals). +.PP +Andrew G. Hume and Bob Flandrena, +``Maintaining Files on Plan 9 with Mk''. +DOCPREFIX/doc/mk.pdf +.SH HISTORY +Andrew Hume wrote +.I mk +for Tenth Edition Research Unix. +It was later ported to Plan 9. +This software is a port of the Plan 9 version back to Unix. .SH BUGS Identical recipes for regular expression meta-rules only have one target. -.br +.PP Seemingly appropriate input like .B CFLAGS=-DHZ=60 is parsed as an erroneous attribute; correct it by inserting a space after the first .LR = . -.br +.PP The recipes printed by .I mk before being passed to --- /sys/man/1/news Sun Apr 17 11:32:13 2005 +++ /sys/man/1/news Sun Apr 17 11:32:09 2005 @@ -49,7 +49,6 @@ .B dead.letter are ignored. .SH FILES -.TF /sys/lib/subscribers .TP .B /lib/news/* articles --- /sys/man/1/passwd Sun Apr 17 11:33:25 2005 +++ /sys/man/1/passwd Sun Apr 17 11:33:22 2005 @@ -29,7 +29,7 @@ They may be of any length greater than seven characters. .PP .I Netkey -uses the password to encrypt network challenges. +prompts for a password to encrypt network challenges. It is a substitute for a SecureNet box. .PP These commands may be run only on a terminal, to avoid --- /sys/man/1/proof Sun Apr 17 11:34:41 2005 +++ /sys/man/1/proof Sun Apr 17 11:34:38 2005 @@ -115,7 +115,6 @@ .B d commands are also available as command line options. .SH FILES -.TF /lib/font/bit/MAP .TP .B /lib/font/bit/* fonts --- /sys/man/1/ps Sun Apr 17 11:36:00 2005 +++ /sys/man/1/ps Sun Apr 17 11:35:57 2005 @@ -94,8 +94,6 @@ .I ps to print the arguments for the process. Newlines in arguments will be translated to spaces for display. .SH FILES -.TF /proc/*/status -.TP .B /proc/*/status .SH SOURCE .B /sys/src/cmd/ps.c --- /sys/man/1/rc Sun Apr 17 11:37:25 2005 +++ /sys/man/1/rc Sun Apr 17 11:37:21 2005 @@ -962,14 +962,14 @@ .SH BUGS There should be a way to match patterns against whole lists rather than just single strings. -.br +.PP Using .B ~ to check the value of .B $status changes .BR $status . -.br +.PP Functions that use here documents don't work. -.br +.PP Free carets don't get inserted next to keywords. --- /sys/man/1/sam Sun Apr 17 11:38:52 2005 +++ /sys/man/1/sam Sun Apr 17 11:38:47 2005 @@ -44,7 +44,7 @@ Autoindent. In this mode, when a newline character is typed in the terminal interface, .I samterm -copies leading white space from the current line to the new line. +copies leading white space on the current line to the new line. .TP .B -d Do not `download' the terminal part of @@ -101,7 +101,7 @@ All files always have a current substring, called dot, that is the default address. .SS Simple Addresses -.PD0 +.PD 0 .TP .BI # n The empty string after character @@ -116,7 +116,7 @@ is the beginning of the file. .TP .BI / regexp / -.PD0 +.PD 0 .TP .BI ? regexp ? The substring that matches the regular expression, @@ -154,7 +154,7 @@ .B k command below). .TP -\fL"\f2regexp\fL"\f1\f1 +\fB"\f2regexp\fB"\f1\f1 Preceding a simple address (default .BR . ), refers to the address evaluated in the unique file whose menu line @@ -249,7 +249,7 @@ It is an error for a compound address to represent a malformed substring. Some useful idioms: .IB a1 +- -\%(\f2a1\fL-+\f1) +\%(\f2a1\fB-+\f1) selects the line containing the end (beginning) of a1. .BI 0/ regexp / @@ -307,7 +307,7 @@ .br .ne 1.2i .SS Text commands -.PD0 +.PD 0 .TP .BI a/ text / .TP @@ -403,7 +403,7 @@ Print just the character address of the range. .PD .SS File commands -.PD0 +.PD 0 .TP .BI \*ab " file-list Set the current file to the first file named in the list @@ -453,7 +453,7 @@ will delete such a file. .PD .SS I/O Commands -.PD0 +.PD 0 .TP .BI \*ae " filename Replace the file by the contents of the named external file. @@ -535,7 +535,7 @@ .B /tmp/sam.err and the first few lines are printed. .SS Loops and Conditionals -.PD0 +.PD 0 .TP .BI x/ regexp / " command For each match of the regular expression in the range, run the command --- /sys/man/1/secstore Sun Apr 17 11:40:24 2005 +++ /sys/man/1/secstore Sun Apr 17 11:40:20 2005 @@ -1,6 +1,6 @@ .TH SECSTORE 1 .SH NAME -aescbc, secstore, ipso \- secstore commands +aescbc, ipso, secstore \- secstore commands .SH SYNOPSIS .B auth/secstore [ @@ -50,7 +50,6 @@ .I file \&... ] -.PP .SH DESCRIPTION .PP .I Secstore @@ -103,7 +102,7 @@ .BR /dev/cons . .PP The server is -.BR tcp!$auth!5356 , +.BR tcp!$auth!secstore , or the server specified by option .BR -s . .PP @@ -157,16 +156,16 @@ files and, if one of them is named .BR factotum , -flush your current keys from factotum and load +flush current keys from factotum and load the new ones from the file. -If you supply any of the +If the .BR -e , .BR -f , or .BR -l -options, +options are given, .I ipso -will just perform the operations you requested, i.e., +will just perform only the requested operations, i.e., edit, flush, and/or load. .PP The @@ -197,6 +196,8 @@ encrypts and decrypts using AES (Rijndael) in cipher block chaining (CBC) mode. .SH SOURCE +.B /rc/bin/ipso +.br .B /sys/src/cmd/auth/secstore .SH SEE ALSO .IR factotum (4), --- /sys/man/1/sort Sun Apr 17 11:41:57 2005 +++ /sys/man/1/sort Sun Apr 17 11:41:54 2005 @@ -19,6 +19,8 @@ .I ,pos2 ] ] ... +.br +\h'0.5in [ .B -o .I output --- /sys/man/1/spell Sun Apr 17 11:43:34 2005 +++ /sys/man/1/spell Sun Apr 17 11:43:31 2005 @@ -60,7 +60,6 @@ cede to `crew member' and `back yard' (noun) or `back-yard' (adjective). .SH FILES -.TF /sys/lib/brspell .TP .B /sys/lib/amspell American spelling list @@ -88,7 +87,7 @@ The heuristics of .IR deroff (1) used to excise formatting information are imperfect. -.br +.PP The spelling list's coverage is uneven; in particular biology, medicine, and chemistry, and perforce proper names, --- /sys/man/1/tail Sun Apr 17 11:45:16 2005 +++ /sys/man/1/tail Sun Apr 17 11:45:13 2005 @@ -77,11 +77,11 @@ Tails relative to the end of the file are treasured up in a buffer, and thus are limited in length. -.br +.PP According to custom, option .BI + number counts lines from 1, and counts blocks and bytes from 0. -.br +.PP .I Tail is ignorant of UTF. --- /sys/man/1/tar Sun Apr 17 11:47:00 2005 +++ /sys/man/1/tar Sun Apr 17 11:46:56 2005 @@ -158,10 +158,10 @@ .SH BUGS There is no way to ask for any but the last occurrence of a file. -.br +.PP File path names are limited to 100 characters (256 when using ustar format). -.br +.PP The tar format allows specification of links and symbolic links, concepts foreign to Plan 9: they are ignored. --- /sys/man/1/troff2html Sun Apr 17 11:48:45 2005 +++ /sys/man/1/troff2html Sun Apr 17 11:48:43 2005 @@ -57,7 +57,7 @@ x X html manref end cp 1 .EE .PP -which are used to create HTML anchors of the form +which are used to create HTML hyperlinks around text of the form .IR cp (1) pointing to .BR /magic/man2html/1/cp . @@ -82,6 +82,8 @@ .I Troff2html has the reverse properties: it does not handle the preprocessors but its output is reliable and (modulo helper annotations) is independent of macro package. +.SH SOURCE +.B /sys/src/cmd/troff2html .SH SEE ALSO .IR troff (1), .IR ms2html (1), --- /sys/man/1/units Sun Apr 17 11:50:34 2005 +++ /sys/man/1/units Sun Apr 17 11:50:31 2005 @@ -102,7 +102,6 @@ does only multiplicative scale changes, it can convert Kelvin to Rankine but not Centigrade to Fahrenheit. -.br +.PP Currency conversions are only as accurate as the last time someone -updated -.BR /lib/units . +updated the database. --- /sys/man/1/wc Sun Apr 17 11:52:28 2005 +++ /sys/man/1/wc Sun Apr 17 11:52:25 2005 @@ -43,7 +43,7 @@ looks for only .SM ASCII space, tab and newline. -.br +.PP .I Wc should have options to count suboptimal .SM UTF --- /sys/man/1/faces Sun Apr 17 11:54:24 2005 +++ /sys/man/1/faces Sun Apr 17 11:54:21 2005 @@ -109,6 +109,12 @@ without sending a message. .SH FILES .BR /mail/fs/mbox " mail directory. +.SH SOURCE +.B /sys/src/cmd/faces +.br +.B /rc/bin/seemail +.br +.B /rc/bin/vwhois .SH "SEE ALSO" .IR mail (1), .IR marshal (1), --- /sys/man/1/lp Sun Apr 17 11:56:22 2005 +++ /sys/man/1/lp Sun Apr 17 11:56:19 2005 @@ -175,6 +175,8 @@ .L lp -dstdout /dev/windows/3/window > doc.ps Convert an image to a postscript file. +.SH SOURCE +.B /rc/bin/lp .SH SEE ALSO .IR lp (8) .br --- /sys/man/1/replica Sun Apr 17 11:58:22 2005 +++ /sys/man/1/replica Sun Apr 17 11:58:20 2005 @@ -298,5 +298,13 @@ since .I changes is a local-only operation, the network need not be configured.) +.SH SOURCE +.B /rc/bin/replica/pull +.br +.B /rc/bin/replica/push +.br +.B /rc/bin/replica/changes +.br +.B /rc/bin/replica/scan .SH SEE ALSO .IR replica (8) --- /sys/man/1/spin Sun Apr 17 12:00:37 2005 +++ /sys/man/1/spin Sun Apr 17 12:00:34 2005 @@ -138,6 +138,8 @@ .TP .B V Print the version number and exit. +.SH SOURCE +.B /sys/src/cmd/spin .SH SEE ALSO G.J. Holzmann, .I