wiki:ManPage
Last modified 7 years ago Last modified on 2010-07-04 18:54:10

Websourcebrowser documentation

NAME

Websourcebrowser - conveniently browse source code with a webbrowser

SYNOPSIS

wsbrowser [options]

The name of the executable is wsbrowser on Posix and wsbrowser.py on Windows.

DESCRIPTION

Websourcebrowser starts an internal webserver and listens for HTTP requests for directories and files in a project's source code directory. The web interface allows to browse the source code with a left frame containing the directory tree and a right frame a selected file. The directory frame is always accessible.

If Pygments (http://pygments.org) is installed, files may be displayed with syntax highlighting.

To stop Websourcebrowser, type Ctrl-C (on Posix) or Ctrl-Break (on Windows).

WEB INTERFACE

After invoking Websourcebrowser, it outputs the URL you should put in the address line of your webbrowser. After you've done this, you get a display with two frames: The left displays the directory specified by the --root option (or the default), the right shows a placeholder. If you click a link in the left frame denoting a file, it's shown in the right frame. If the file is a binary file for which Websourcebrowser doesn't know to render it, a hexdump is shown instead. At the moment, this happens even for popular formats as PDF, and that will change.

The directory display on the left has several framed links which you can imagine as buttons. "Reset view" resets the display, this is as if you just entered the root URL which Websourcebrowser prints in the terminal upon start. The button "Homepage" opens a new window with the page identified with the command line option --project-homepage. Below the two already described buttons you can control the number of expanded directory levels. By definition, when the level is 1, just a linear list of the directories and files in the project root directory is shown. A level of 2 means that the contained directories and files are also displayed. This is easier to check out than to describe. Note that you won't see a difference after a click if the project directory structure is not that deep. By the way, clicking on a directory link will show a list of its contents if they're not already displayed. If, for your taste, too many levels are shown, you can reduce them with the buttons at the top of the frame.

OPTIONS

-h, --help

Show this help text and exit.

-r ROOT, --root=ROOT

Set the document root directory (default: current directory). For example, if --root=/my/greatproject is specified, the URL path / will correspond to the directory /my/greatproject. Directories or files "above" the root directory aren't accessible (probably, see section BUGS).

-t PROJECT_TITLE, --project-title=PROJECT_TITLE

Set the project title to display as the title of the frameset (default: capitalized base name of the root directory, so the above root option sets a project title "Greatproject").

-i PATTERN, --ignore-pattern=PATTERN

Ignore directories and files matching this pattern (default: nothing is ignored). To specify more than one pattern, repeat this option.

For each pattern, the corresponding pattern plus "/*" is also used, so you don't have to specify two patterns to ignore a directory and everything under it.

Example: To ignore all Mercurial and Subversion bookkeeping files, use --ignore-pattern="/*.svn" --ignore-pattern="/*.hg".

-l, --line-numbers

Prepend lines of text files with line numbers (default: no line numbers).

This works only if Pygments is installed, otherwise this option is ignored.

--http-host=HTTP_HOST

Use the specified host name or IP for the local interface to listen on (default: localhost).

With the defaults for --http-host and --http-port, the address line in the browser is http://localhost:8000/ .

--http-port=HTTP_PORT

Listen on this HTTP port (default: 8000).

With the defaults for --http-host and --http-port, the address line in the browser is http://localhost:8000/ .

-c CLIENT, --allowed-client=CLIENT

Allow remote access from this host name or IP address (default: allow only access from localhost). The localhost address is always included. For multiple host names or IP addresses use the option several times. For example:

wsbrowser -c my.host.com -c 199.243.19.27

As a special case, specifying ALL as the options value accepts requests from all addresses and so effectively makes Websourcebrowser a web server on the public internet, unless prevented by a router or firewall.

--logging

Activate logging of HTTP accesses to standard output (default: no logging).

ENVIRONMENT

WSB_IGNORE

Set wildcard patterns to ignore. If multiple patterns are given, they must be separated by whitespace.

A typical example for WSB_IGNORE might be *.pyc *.pyo */.svn *.svn/* */.hg */.hg/* *.swp

If both this environment variable and one or more --ignore-pattern options are used, the patterns from the command line are added to those from the environment variable.

BUGS

Probably there are some bugs as Websourcebrowser is still alpha software. Currently, I don't recommend to use Websourcebrowser for use on the public internet because it may contain significant vulnerabilities. (I indeed paid attention to security though I would welcome an experienced fellow to spot security problems.)

Since the software is still in the alpha stage, it may still change significantly. This may include incompatible variations like removing command line options or changing their semantics.

AUTHOR

The author of Websourcebrowser is Stefan Schwarzer <sschwarzer@…>.

SEE ALSO

The pydoc module in the Python distribution similarly acts as a webserver if it's invoked as a program with the option -p and a port number.