.TH WEBROWSE 1 1.6.2
.SH NAME
webrowse \- browse the given input in a local web browser, with markup
.SH SYNOPSIS
.B webrowse
[
.B \-N
|
.B \-M
] [
.B \-s
|
.B \-mq
|
.B \-u
|
.B \-c
] [
.B \-k
.I minutes
] [
.B \-p
|
.B \-a
] [
.B \-i
.I id
] [
.B \-w
|
.B \-t
] [
.B \-rnvo
] [
.B \-h
] [
.I file
]
.SH DESCRIPTION
\fIWebrowse\fP can be used for convenient file or URL loading remote
control of \fINetscape\fP, \fIMozilla\fP or \fIMosaic\fP browsers,
for textual reference HTML markup, and, for example, for interfacing
a browser to news and mail readers as a hypertextual external viewer
for mail messages or news articles containing HTML or containing text
with embedded URLs, mail addresses and other references.  See the
\fBEXAMPLES\fP section below.
.PP
Simply given a file argument, \fIwebrowse\fP will direct a browser already
running on the user's display to load the given file.  With \fINetscape\fP
or \fIMozilla\fP, the browser may be automatically deiconified and raised
as well.  The browser must be running on the same (network) filesystem.
If the \fB\-m\fP is supplied, \fIwebrowse\fP will interpret the file
as text and create and load a temporary copy of the file containing
HTML markup to hyperlink the URLs, FTP locations, mail addresses,
header newsgroups, news article IDs, and filesystem pathnames in the
text to their references.  A temporary file is used to hold and load the
standard input if no file argument is given.  By default, the temporary
files are deleted 10 minutes after they've been first loaded by the
browser.  This delay can be set or disabled with the \fB\-k\fP option or
\fBWB_KEEP\fP environment variable.  If a \fB\-u\fP or \fB\-c\fP option
is supplied, \fIwebrowse\fP will interpret the command line argument,
or the standard input if there isn't one, as a URL to browse or as a
Netscape/Mozilla remote control command to run, respectively.
.SH OPTIONS
.PP
.TP 10
\-N
Use a \fINetscape\fP or \fIMozilla\fP browser.  This is the default
unless the \fBWB_BROWSER\fP environment variable is set to \fBmosaic\fP.
The \fBWB_NETSCAPE\fP environment variable can be set to select which
browser command to use.
.TP 10
\-M
Use a \fIMosaic\fP browser.  This is the default only if the
\fBWB_BROWSER\fP environment variable is set to \fBmosaic\fP.
.TP 10
\-s
Tag and treat the standard input as HTML instead of text.
.TP 10
\-m
Markup and load a text copy of the input (whether a file or the standard
input) with heuristically identified hyperlinks to Web, FTP, mail,
news and file references.
.TP 10
\-q
Markup and load a text copy of the input (whether a file or the
standard input) with quoted mail/news message lines in italic or bold,
alternating by depth of nesting.
.TP 10
\-u
Take the command line argument, or the standard input if there isn't one,
as a URL to browse, instead of as a file.
.TP 10
\-c
Take the command line argument, or the standard input if there isn't one,
as a remote control command to run, instead of as a file.  This works
with Netscape or Mozilla only.
.TP 10
\-k minutes
Keep (ie, don't delete) any temporary files for the given integer number
of minutes.  If the minutes is the string \fBforever\fP, then the
temporary files aren't ever deleted by \fIwebrowse\fP, under the
assumption they will be cleaned up later by some other means.  Once
temporary files are deleted, the browser will not be able to reload or
re-enter them.  The default is the value of the \fBWB_KEEP\fP
environment variable, or 10 minutes if it isn't set.
.TP 10
\-p
Use a sleeping background shell process to delete any kept temporary
files.  This will fail to complete should the process be killed while
sleeping, and is only recommended for short temporary file lifetimes.
This method is the default unless the \fBWB_SLEEP\fP environment
variable is set to \fBat\fP.
.TP 10
\-a
Use an \fIat\fP(1) job to delete any kept temporary files.  This method
is the default only if the \fBWB_SLEEP\fP environment variable is set to
\fBat\fP.
.TP 10
\-i id
The window ID (with \fINetscape\fP/\fIMozilla\fP) or process ID (with
\fIMosaic\fP) of an existing browser to use for loading.  The default is
any value of the \fBWB_ID\fP environment variable (see for more details).
.TP 10
\-w
Open a new browser window, off of an already running browser, for loading
the input.  By default, any running browser window may be used.
.TP 10
\-t
Open a new browser tab, inside an already running browser window,
for loading the input.  This works with newer versions of
\fINetscape\fP/\fIMozilla\fP only.
.TP 10
\-r
Don't deiconify/raise the browser window.  The default for
\fINetscape\fP/\fIMozilla\fP is to raise the window, while \fIMosaic\fP
will never raise the window.
.TP 10
\-n
Don't actually use the browser at all.  This is useful if only what is
printed is of interest.
.TP 10
\-v
Prints the shell command to run for remote control of the browser.
This works with \fINetscape\fP/\fIMozilla\fP only.
.TP 10
\-o
Prints the input (whether a file or the standard input, or whether
marked up or not), perhaps in addition to loading it into the browser.
This can be used to capture the marked up version of the input for other
uses.
.TP 10
\-h
Prints a helpful usage message.
.SH "ENVIRONMENT VARIABLES"
.PP
.TP 10
WB_BROWSER
The default browser to use, \fINetscape\fP/\fIMozilla\fP by default,
unless set to \fBmosaic\fP.  This may be overridden by the \fB\-N\fP or
\fB\-M\fP options.
.PP
.TP 10
WB_NETSCAPE
The \fINetscape\fP or \fIMozilla\fP browser command name to use,
\fBnetscape\fP by default. \fBmozilla\fP could be a common setting.
.PP
.TP 10
WB_TMP
The directory in which to create any temporary files for use with either
browser.  The default depends on the browser in use.  This may be
overridden by the \fBWB_NSTMP\fP or \fBWB_MSTMP\fP environment
variables.
.PP
.TP 10
WB_NSTMP
The directory in which to create any temporary files for use with
\fINetscape\fP/\fIMozilla\fP, \fB$HOME/.mozilla\fP, \fB$HOME/.netscape\fP,
\fB$HOME/tmp\fP or \fB/tmp\fP (the first which exists) by default.
This overrides \fBWB_TMP\fP.
.PP
.TP 10
WB_MSTMP
The directory in which to create any temporary files for use with
\fIMosaic\fP, \fB$HOME/tmp\fP or \fB/tmp\fP (the first which exists)
by default.  This overrides \fBWB_TMP\fP.
.PP
.TP 10
WB_UMASK
\fIwebrowse\fP uses a \fIumask\fP of \fB077\fP when creating temporary
files, unless overriden with this.
.PP
.TP 10
WB_KEEP
The number of minutes to wait before deleting any temporary files, or
the string \fBforever\fP if they're not ever to be deleted.  10 minutes
is the default.  This may be overridden by the \fB\-k\fP option.
.PP
.TP 10
WB_SLEEP
The default method to use to delete kept temporary files, \fBsleep\fP by
default, unless set to \fBat\fP.  This may be overridden by the \fB\-p\fP
or \fB\-a\fP options.
.PP
.TP 10
WB_ID
With \fINetscape\fP/\fIMozilla\fP, this can be set to the window
ID of an existing browser window to specify the use of that window
for loading, instead of just the first one found on the display.
For example, under X Windows, \fIxwininfo\fP(1) or \fIxlswins\fP(1)
can identify window IDs.  \fIxwinid\fP(1) is a supplementary script
to \fIwebrowse\fP to conveniently interface these programs, so one can
simply use the output of, eg, \fBxwinid -i $WB_NETSCAPE\fP to set this
value.  With \fIMosaic\fP, this can be set to the process ID of a running
browser to specify the use of that browser for loading, instead of the one
associated with the process ID listed in the file \fB$HOME/.mosaicpid\fP.
This variable may be overridden by the \fB\-i\fP option.
.PP
.TP 10
WB_PWD
The command to run to determine the current working directory, instead
of the configured default command (usually \fIpwd\fP(1)).
.SH EXAMPLES
.PP
Besides its usage directly from the command line, \fIwebrowse\fP can be
useful as a tool within other scripts and, creatively, as an interface
between a web browser and other applications.  Most usages fall into
two categories.  One, based on \fBwebrowse \-s\fP, is useful for sending
HTML that is found outside a web context into a browser so it may be
viewed properly.  The other, based on \fBwebrowse \-m\fP, is useful for
sending text that contains URLs, mail addresses, filesystem pathnames,
etc into a browser with these items conveniently hyperlinked.
.PP
The following \fIvi\fP(1) macros, for your \fB.exrc\fP file, may be used
to view the currently editted text in a browser with markup (and perhaps
in a new window), or to (re)load the currently editted file into a browser
from \fIvi\fP.  The latter can facilitate HTML development with \fIvi\fP
using a browser for WYSIWYG-like viewing of the developing HTML source.
(Control characters are shown in carat-notation.)
.PP
.ft C
.nf
     map _wb :w !webrowse -m 
     map _wm :w !webrowse -mw^M^M
     map _ws :w !webrowse -sw^M^M
     map _wn :!webrowse -w %^M^M
     map _wl :!webrowse %^M^M
     map _ww :!webrowse -c reload^M^M
.fi
.ft P
.PP
The following \fIvim\fP(1) one-line macro, for your \fB.vimrc\fP file,
may be used to (re)set the editor's \fBWB_ID\fP environment variable to
a selected \fINetscape\fP browsing window.  It requires \fIxwinid\fP(1)
to be installed and \fBWB_NETSCAPE\fP to be defined.
.PP
.ft C
.nf
     noremap _wi mp:r!xwinid -i $WB_NETSCAPE<CR>0"iy$u`p
     :let $WB_ID=@i<Bar>ec $WB_ID<CR>
.fi
.ft P
.PP
If you receive a mail message in HTML with \fImailx\fP(1), the following
configuration in your \fB.mailrc\fP file will allow you to view the
message in your browser via \fImailx\fP's \fBpipe\fP command.
.PP
.ft C
.nf
     set cmd='webrowse -sw'
.fi
.ft P
.PP
If you receive a news article containing URLs with \fInn\fP(1), the
following configuration in your \fB.nn/init\fP file will allow you to view
the article with markup in your browser via \fInn\fP's \fBI\fP command.
.PP
.ft C
.nf
     map both I (
             save-full "|webrowse -mqw"
     )
.fi
.ft P
.PP
\fIWebrowse\fP may also come in handy as part of a browser
startup command.  For example, the following Bourne-shell
command in a shell alias, windowing system initialization file or
window manager configuration file will allow you to create a new
\fINetscape\fP/\fIMozilla\fP window by spawning one off an already
running \fINetscape\fP/\fIMozilla\fP browser, if there is one.  If not,
it starts a new \fINetscape\fP/\fIMozilla\fP entirely.  \fBWWW_HOME\fP is
assumed to be set to your starting URL.
.PP
.ft C
.nf
     case "`webrowse -uw $WWW_HOME 2>&1`" in
     *[Nn]o*running*)   exec ${WB_NETSCAPE-netscape} &;;
     esac
.fi
.ft P
.SH FILES
.PP
.TP 10
$HOME/{.mozilla,.netscape,tmp}/webrowse*, /tmp/webrowse*
Possible temporary files for markup and loading.  The defaults with
\fINetscape\fP/\fIMozilla\fP unless the directory is changed via
\fBWB_NSTMP\fP or \fBWB_TMP\fP.
.PP
.TP 10
$HOME/tmp/webrowse*, /tmp/webrowse*
Possible temporary files for markup and loading.  The defaults with
\fIMosaic\fP unless the directory is changed via \fBWB_MSTMP\fP or
\fBWB_TMP\fP.
.PP
.TP 10
$HOME/.mosaicpid
Used to determine the process ID of a \fIMosaic\fP browser.  Created by
\fIMosaic\fP.
.PP
.TP 10
/tmp/Mosaic.*
Created, used and kept to communicate loading information to \fIMosaic\fP.
.SH CAVEATS
The textual pattern matching used to identify URLs, FTP locations,
mail addresses, header newsgroups, news article IDs, and filesystem
pathnames is completely heuristic and can easily misidentify items.
In practice, it's quite accurate, but occasionally text is identified
as an FTP location (eg, \fIhostname:path\fP) or a filesystem pathname
when it really isn't.  \fIWebrowse\fP is designed to err on the side of
overidentifying such references, to make it most useful when browsing
temporary markup.  Also, if the input text is exceptionally large,
the pattern matching can become prohibitively expensive to compute.
In such cases as these, a different program may be used to perform the
markup, with its output piped into \fIwebrowse\fP.
.PP
Not all \fINetscape\fP remote control features may work with
\fIMozilla\fP, too, since \fIMozilla\fP's support for \fINetscape\fP-style
remote control is still under development.  See the URLs in the \fBSEE
ALSO\fP section below for current details.
.SH VERSION
1.6.2
.SH AUTHOR
Steve Kinzler, kinzler@cs.indiana.edu, May 96/Jan 98
.SH URL
http://www.cs.indiana.edu/~kinzler/webrowse/
http://www.cs.duke.edu/~des/webrowse.html
.SH "SEE ALSO"
netscape(1), mozilla(1), Mosaic(1), umask(1), sleep(1), at(1),
xwinid(1), xwininfo(1), xlswins(1),
pwd(1), kill(1), vi(1), mailx(1), nn(1),
http://home.netscape.com/newsref/std/x-remote.html,
http://www.mozilla.org/unix/remote.html