NAME

help − make and control help windows

SYNOPSIS

­help/help

Help(1) serves a variety of files for reading, writing, and controlling its windows. The files are mounted on the directory /mnt/help and are also unioned into the beginning of /dev.  At the top level of that directory are files cons, consctl, and mouse, much like those of 8½(1). ­Help’s versions of these files have restricted utility, however: ­cons may be written to but not read and both ­consctl and ­mouse draw an error when opened.  When a program is run from within help, its standard input is connected to ­/dev/null and its standard output to /mnt/help/cons.  Text written to ­cons will appear in ­help’s ­Errors window.  ­Consctl and ­mouse are there to prevent access to the files ­help is itself using. 

Another file in ­/mnt/help is index, which holds one line of text for each ­help window.  Each line has the numeric window id for the window, a tab, and the tag of the window. 

The rest of the files in ­/mnt/help are directories, one per window, named by the numeric window id of the corresponding window.  Each directory contains the following files:

­body This read-only file contains the text of the body of the window. 

­bodyapp Text written to this write-only file is appended to the body. 

­bodypos This read-only file contains the starting and ending byte offsets of the selection in the body, formatted as two textual numbers in 12-byte blank padded fields. 

­bodysel This read-only file contains the selected text in the body. 

­tag This read-only file contains the text of the tag of the window. 

­tagpos Like ­bodypos but for the tag. 

­tagsel Like ­bodysel but for the tag. 

­ctl A read of this file returns the textual numeric id of the window.  Messages written to ­ctl change the contents of the window.  Each message must be contained in a single 9P write message (see read(5)) and must begin with an ASCII letter, possibly an address, and a newline.  An address is one or two comma-separated positions in the file, either line numbers or character positions.  The address syntax is a subset of that in sam(1). If the message contains text to be added to the window, the text follows the newline and need not be newline-terminated. This description mentions only the upper case versions.  The symbol ­\n stands for a literal newline:

a\n<text> Append the text to the tag. 

A\n<text> Append the text to the body. 

d<address>\n Delete the addressed text from the tag. 

D<address>\n Delete the addressed text from the body. 

i<address>\n<text> Insert the text in the tag at the addressed location.  If the address has two components, the second is ignored. 

I<address>\n<text> Like i, but insert in the body.

u\n Mark the window ‘not dirty’, that is, remove the ­Put!  string from the tag. 

A single directory /mnt/help/new, when accessed, creates a new window.  The easiest way to manage a new window is to open /mnt/help/new/ctl, which will create it automatically, and then read the file to retrieve the numeric id.  The other files in the window may then be opened as usual. 

EXAMPLE

Create a new window and run date(1) in it.

id = ‘{cat /mnt/help/new/ctl}
echo ’a
Current time    Close!’ > /mnt/help/$id/ctl
date > /mnt/help/$id/bodyapp

SEE ALSO

help(1), 8½(4)

Plan 9  —  January 03, 1993