20061220

8 files changed, 275 insertions, 22 deletions

diff --git a/man/1/INDEX b/man/1/INDEX
index 3c7c3d90..58815344 100644
--- a/man/1/INDEX
+++ b/man/1/INDEX
@@ -10,6 +10,7 @@ alphabet-grid alphabet-grid
 grid alphabet-grid
 alphabet-main alphabet-main
 main alphabet-main
+ar ar
 asm asm
 disdump asm
 auhdr auplay
@@ -103,6 +104,7 @@ look look
 ls ls
 lookman man
 man man
+man2html man
 man2txt man
 wm/man man
 mash mash
diff --git a/man/1/ar b/man/1/ar
new file mode 100644
index 00000000..fcd68f98
--- /dev/null
+++ b/man/1/ar
@@ -0,0 +1,163 @@
+.TH AR 1
+.SH NAME
+ar \- archive maintainer
+.SH SYNOPSIS
+.B ar
+.I key
+[
+.I posname
+]
+.I afile
+[
+.I file ...
+]
+.SH DESCRIPTION
+.I Ar
+maintains groups of files
+combined into a single archive file,
+.IR afile .
+The main use of
+.I ar
+is to produce and manipulate UNIX archive files, for instance to create
+program packages for Debian Linux.
+Note that only
+.IR iar (10.1)
+can manage archives used as object file libraries by the Inferno and Plan 9 loaders.
+.PP
+.I Key
+is one character from the set
+.BR drqtpmx ,
+optionally concatenated with
+one or more of
+.BR vuaibclo .
+The
+.I files
+are constituents of the archive
+.IR afile .
+The meanings of the
+.I key
+characters are:
+.TP
+.B d
+Delete 
+.I files 
+from the archive file.
+.TP
+.B r
+Replace
+.I files 
+in the archive file, or add them if missing.
+Optional modifiers are
+.RS
+.PD0
+.TP
+.B u
+Replace only files with
+modified dates later than that of
+the archive.
+.TP
+.B a
+Place new files after
+.I posname
+in the archive rather than at the end.
+.TP
+.BR b " or " i
+Place new files before
+.I posname
+in the archive.
+.RE
+.PD
+.TP
+.B q
+Quick.  Append
+.I files 
+to the end of the archive without checking for duplicates.
+Avoids quadratic behavior in
+.LR "for (i in *.v) ar r lib.a $i" .
+.TP
+.B t
+List a table of contents of the archive.
+If names are given, only those files are listed.
+.TP
+.B p
+Print the named files in the archive.
+.TP
+.B m
+Move the named files to the end or elsewhere,
+specified as with 
+.LR r .
+.TP
+.B o
+Preserve the access and modification times of files
+extracted with the
+.B x
+command.
+.TP
+.B x
+Extract the named files.
+If no names are given, all files in the archive are
+extracted.
+In neither case does
+.B x
+alter the archive file.
+.TP
+.B v
+Verbose.
+Give a file-by-file
+description of the making of a
+new archive file from the old archive and the constituent files.
+With
+.BR p ,
+precede each file with a name.
+With
+.BR t ,
+give a long listing of all information about the files,
+somewhat like a listing by
+.IR ls (1),
+showing
+.br
+.ns
+.IP
+.B
+	mode uid/gid size date name
+.TP
+.B c
+Create.
+Normally
+.I ar
+will create a new archive when
+.I afile
+does not exist, and give a warning.
+Option 
+.B c
+discards any old contents and suppresses the warning.
+.SH EXAMPLE
+.TP
+.L
+ar cr arch.a manifest *.tar.gz
+Replace the contents of
+.L arch.a
+with the
+.B manifest
+file and all the
+.IR gzip (1)'d
+.I tar
+files in the current directory.
+.SH FILES
+.TF /tmp/art.*.*
+.TP
+.B /tmp/art.*.*
+temporaries
+.SH SOURCE
+.B /appl/cmd/ar.b
+.SH "SEE ALSO"
+.IR 2l (10.1),
+.IR iar (10.1),
+.IR ar (10.6)
+.SH BUGS
+If the same file is mentioned twice in an argument list,
+it may be put in the archive twice.
+.br
+The file format used by this command is taken from UNIX, and
+makes some invalid assumptions,
+for instance that user IDs are numeric.
diff --git a/man/1/man b/man/1/man
index abf4d50e..f9138900 100644
--- a/man/1/man
+++ b/man/1/man
@@ -1,6 +1,6 @@
 .TH MAN 1
 .SH NAME
-man, wm/man, man2txt, lookman \-
+man, wm/man, man2html, man2txt, lookman \-
 print or find manual pages
 .SH SYNOPSIS
 .B man
@@ -21,6 +21,12 @@ print or find manual pages
 .B wm/man -f
 .I file ...
 .br
+.B man2html
+.I file
+[
+.I section
+]
+.br
 .B man2txt
 [
 .B -p
@@ -31,6 +37,9 @@ print or find manual pages
 ]
 .br
 .B lookman
+[
+.B -f
+]
 .I keyword ...
 .SH DESCRIPTION
 Both
@@ -72,9 +81,20 @@ some detail is lost in conversion to plain text.
 displays the pages in a graphical Wm window, providing a more faithful
 reproduction of the intended layout.
 .PP
+.I Man2html
+converts
+.B "troff -man"
+macro markup to an approximation in HTML on standard output.
+Only one file is processed at a time.
+It is assumed the input
+.I file
+is a manual page, in the given
+.I section
+(default: 1).
+.PP
 .I Man2txt
 converts
-.I "troff -man"
+.B "troff -man"
 macro markup
 to plain text.
 Each file is processed separately.
@@ -87,10 +107,27 @@ option to
 specifies the page width in characters.
 .PP
 .I Lookman
-prints the file names of manual pages, from any section, that
+finds the manual pages, in any section, that
 contain all of the
 .I keywords
-given as arguments.
+given as arguments, and prints
+.I man
+commands and manual references for them, one per line.
+In a
+.IR wm-sh (1)
+window,
+any of the
+.I man
+commands can be selected with mouse button 2 and
+sent
+as a command; a manual reference can simply be
+.IR plumb (1)'d
+using mouse button 3.
+The
+.B -f
+option causes
+.I lookman
+just to list the file names.
 .SH FILES
 .TF /man/1/INDEX
 .TP
@@ -118,7 +155,9 @@ index.
 .br
 .B /appl/cmd/man2txt.b
 .br
-.B /appl/cmd/lookman.b
+.B /dis/lookman
+.IR sh (1)
+script
 .br
 .B /appl/lib/parseman.b
 .SH "SEE ALSO"
diff --git a/man/1/os b/man/1/os
index 7b7f8996..38e8a8ba 100644
--- a/man/1/os
+++ b/man/1/os
@@ -6,6 +6,8 @@ os \- interface to host OS commands (hosted Inferno only)
 .br
 .B os
 [
+.B -b
+] [
 .B -m
 .I mountpoint
 ] [
@@ -43,7 +45,10 @@ option causes the command to run in directory
 an error results and the command will not run if
 .I dir
 does not exist or is inaccessible.
-The standard output and standard error of the command are merged on the standard output.
+The standard output and standard error of the command appear on the standard output
+and standard error streams of the
+.I os
+command itself.
 .I Os
 copies the standard input to the remote command's standard input; redirect
 .IR os 's
@@ -56,6 +61,17 @@ terminates when
 does, and its exit status reflects the status of
 .I cmd
 (if available).
+.PP
+If the
+.I os
+command is killed or exits (eg, for lack of input and output),
+the host's own process control operations are used to (attempt to) kill
+.IR cmd ,
+if it is still running.
+The
+.B -b
+(background) option suppresses that behaviour.
+.PP
 The
 .B -n
 option causes
diff --git a/man/1/sh b/man/1/sh
index 951f168a..4dd30d14 100644
--- a/man/1/sh
+++ b/man/1/sh
@@ -588,6 +588,18 @@ for the module.
 If a load fails, a
 .B bad module
 exception is raised.
+The environment variable
+.B $autoload
+can be set to a list of Shell modules that
+each instance of
+.I sh
+should load automatically during its initialisation.
+(More precisely, the modules are loaded
+when a new
+.B Sh->Context
+is created: see
+.IR sh (2)
+for details.)
 .HP
 .BI unload " path..."
 .br
diff --git a/man/1/sh-expr b/man/1/sh-expr
index b640e339..976e6c04 100644
--- a/man/1/sh-expr
+++ b/man/1/sh-expr
@@ -18,23 +18,26 @@ expr, ntest \- shell module for simple arithmetic.
 .I num
 .br
 .SH DESCRIPTION
-.B Expr
+.I Expr
 is a loadable module for
 .IR sh (1)
 that provides support for simple integer arithmetic.
 It provides one command,
-.BR ntest ,
+.IR ntest ,
 which performs a simple boolean test
 on its integer argument, and the
 substitution operator
-.BR expr ,
+.IR expr ,
 which takes an expression in Reverse Polish
 notation, and yields its result.
-.B Ntest
+.PP
+.I Ntest
 returns true if its argument
 .I num
-is non-zero.
-.B Expr
+is non-zero,
+and false otherwise.
+.PP
+.I Expr
 evaluates each
 .I arg
 in turn; if it is an integer it gets pushed onto
@@ -50,7 +53,7 @@ yields 1, not -1.
 Alternative names are given for some operators;
 this is to avoid the necessity of quoting operators
 that contain
-.I sh
+.IR sh (1)
 metacharacters. All operations use 64-bit signed
 integers; integers are given in the same form acceptable
 to Limbo. The relational operators yield either
@@ -59,10 +62,10 @@ to Limbo. The relational operators yield either
 option is given,
 .I radix
 specifies an output base for numbers yielded by
-.BR expr .
+.IR expr .
 Numbers are printed in a form suitable for re-interpretation
 by
-.BR expr .
+.IR expr .
 .PP
 When all its arguments have been evaluated,
 .B expr
diff --git a/man/1/sh-std b/man/1/sh-std
index efb650cc..87ed676b 100644
--- a/man/1/sh-std
+++ b/man/1/sh-std
@@ -76,13 +76,6 @@ std, if, while, ~, no, !, apply, getlines, status, pctl, fn, and, or, raise, res
 .B subfn
 .I name command
 .br
-.B if
-[
-.I condition action
-]... [
-.I elseaction
-]
-.br
 .B while
 .I condition command
 .br
diff --git a/man/1/sh-tk b/man/1/sh-tk
index 8777dac7..e45bd9a6 100644
--- a/man/1/sh-tk
+++ b/man/1/sh-tk
@@ -41,6 +41,13 @@ tk, chan, send, recv, alt \- loadable tk module for sh.
 ]
 .B }
 .br
+.B ${tk onscreen
+.I winid
+[
+.I how
+]
+.B }
+.br
 .B ${tk
 .I winid tkcmd
 .B }
@@ -128,6 +135,22 @@ the window manager arrive on this channel, and
 should be responded to appropriately using
 .BR "tk winctl" .
 .TP
+.B tk onscreen
+.B Tk onscreen
+must be called to make window
+.I winid
+visible for the first time, the same as
+.I onscreen
+in
+.IR tkclient (2).
+.I How
+is the same as for that call - if given, it must be one of
+.BR place ,
+.BR onscreen
+or
+.BR exact .
+.BR 
+.TP
 .B tk winctl
 .B Tk winctl
 is used to communicate requests to the window manager.
@@ -241,6 +264,7 @@ sh
 load std tk
 pctl newpgrp
 wid=${tk window 'My window'}
+tk onscreen $wid
 tk $wid update
 while {} {tk winctl $wid ${recv $wid}} &
 .EE
@@ -252,5 +276,6 @@ while {} {tk winctl $wid ${recv $wid}} &
 .IR sh-expr (1),
 .IR tkcmd (1),
 .IR tk (2),
+.IR tkclient (2),
 .IR wmlib (2),
 ``The Tk Reference Manual''