Documentation for NetShell


  1. Installation guide
  2. Overview
  3. User manual
  4. List of tools
  5. NetShell library
  6. Known bugs
  7. Troubleshooting and maintenance
  8. Copyright Notice

Installation Guide

  1. Download the source
  2. Make sure you have Tk 4.0 and Perl installed.
  3. Untar the source:
    	% tar xf NetShell.tar
    
    This will create a new directory called NetShell.
  4. cd NetShell
  5. run the nshconfig program to configure your copy:
    	% nshconfig
    
  6. You are all set now. Start NetShell:
    	% netshell
    
    The NetShell window should appear and you can start using it.

Comments

Overview

NetShell works by viewing the WWW as just another IO stream. In addition to accepting IO to/from files or to/from user windows, NetShell provides an easy way to direct the IO stream to/from the web. Each NetShell tool -- and one can very easily make up tools from existing programs -- can be set to get its input from Netscape's current page and sends its output to be shown on Netscape's window. Tools can also use files or a special tty window for their input/output. This allows one to manipulate WWW data in a very customizable and convenient way. For example, using the FOLD tool (enclosed with NetShell distribution), one can with one click collect all pages pointed to from the current page into one big page (e.g., for saving or printing).

User manual

Tools

The NetShell window shows the list of currently available tools. When a tool is selected (by clicking on it), NetShell shows the program the tool uses and its selection on input/output. To execute a tool after selecting it, click on the Execute button. This is the simplest way to use NetShell. Tools can be easily added or edited as described below. A list of tools distributed with NetShell appears here.

File Menu

  1. New Tool: a special window will pop out and will allow you to specify a new tool. Do not forget to name your new tool. You can try your tool before saving it by clicking on "Try it".
  2. New folder: a special window will pop out and will allow you to add a new folder of tools. NetShell supports a hierarchy of folders containing tools so you are not limited to just one linear list.
  3. Edit: a special window will pop out to allow you to edit the selected tool. (Same as hitting the "Edit" button.)
  4. Delete: the selected item will go to the trash can. You can reclaim it using the Reclaim operation.
  5. Reclaim: a box containing everything you deleted will pop out. You can reclaim the items or move any item to the current folder (which may be different from its original folder). Double clicking on the trash can has the same effect.
  6. Execute: execute the selected tool. (Same as hitting the Execute button.)
  7. History: a list of folders you have used. Select a folder and you will go there directly.
  8. Exit: exits NetShell. The new/modified tools will be saved.

Options Menu

  1. Hide/Show Toolbar: The Toolbar is the small area with the three buttons and one trash can.
  2. Change Browser: when NetShell starts it establishes communication with a currently running Netscape window. If there is more than one window, or if you want to change the window later you can use this option, which lists all opened windows.
  3. Show/Hide Folders: shows the list of available folders.
  4. Raise/NoRaise Browser: The netscape window will usually pop out when a remote request is received. If NoRaise Browser is chosen, the netscape window will not pop out when processing remote request.
  5. Fast/Cautious Mode. In the Cautious Mode, which is the default, all URLs are fetched from scratch. If you choose Fast Mode, the page will be acquired directly from the Netscape window. The problem with Fast Mode is that sometimes the page may not be complete or up-to-date (e.g., when a transmission is in the middle or was interrupted).

TTY window as input

You can specify the tty window as the source of input. Click button 1 on a segment of text in tty window, which is the result of former execution of some tool, to select it as the tty win input. You can also select multiple segments at the same time. Single click of button 3 will cancel the selection of the segment. This function is useful, for example, for editing results and putting them back to the Netscape window.

Remote execute mode

NetShell can be executed from the regular shell (or from any program) without using the GUI.
	netshell -e TOOLNAME
has the same effect as executing the given TOOLNAME from the NetShell window. The only limitation on remote execution is that the tty window cannot be used as input. Remote execution can be somewhat slower, because for each call NetShell has to get the window id, URL address, and so on.

NetShell predefined variables

Currently 3 variables (URL, NSID and TMPDIR) are predefined by NetShell. URL is the url that's showing in the netscape window. NSID is the X windows id for the Netscape window. TMPDIR is the predefined temporary file directory. Those variables follow the Tcl convention. For example, you can show the current URL by "echo $URL". The environment variables can be accessed in the same way.

Some other tricks

List of tools

The main strength of NetShell is the ability to add and customize tools very easily. We have constructed several examples of tools, which are included in the NetShell distribution, and described here. We hope that people will build and distribute more useful tools. We will keep a list of available tools that we receive citing the contributor. Please send them to netshell@cs.arizona.edu.

NetShell library

We included a small HTML file lexer as library in NetShell. The source files for the library are in NetShell/lib and the head files are in NetShell/include. The library is built based on the simple SGML lexer by Dan Connolly

The lexer works in this way: each time a grammer unit is returned from the lexer, the type of this unit is out of the HTML_DATA, HTML_TAG or HTML_COMMENT. With a tag (i.e. unit of type HTML_TAG), there is a global variable theTag in which we saved all the information about this tag. Following are the functions to deal with the tag we just scanned in:

  • void AddNewAttrib(const char * attribName)
  • char * GetAttrib(const char * attribName)
  • int SetAttrib(const char * attribName, const char * newValue)
  • char * Tag2String(char * buf)
  • Following function is used to output the just scanned unit to a file:

  • int Output(FILE *, int unit_type)
  • In NetShell/hextract we also included the source code for some tools. This lexer is used in most of these tools.

    Known bugs

    1. Semicolon doesn't work: if you put a semicolon between 2 commands to execute them one by one, it won't work. I am working on it. The way to get around: write a shell script.
    2. Folder doesn't work in remote mode: you cannot invoke a tool that's not in the home folder. The problem is I haven't figure out a intuitive way to express the folder structure from the command line.

    Troubleshooting and maintenance

    1. NetShell fails to find the current URL correctly -- Check if you set the [netscape][option][show location].
    2. Netscape always says it can't open some temporary files -- Check if the netshell and the netscape associated with the netshell are running on the same machine.
    3. NetShell shows that the Netscape complains about version number mismatch. Usually it caused by the same reason of above item. Netscape 2.01 is much more strict with the version number.
    4. Netscape shows alert for some errors of JavaScript like:
      Register not a function.
      If you are using Netscape 2.01, you can just simply disable the JavaScript to get around.


    NetShell was developed by dachuan Zhang and Udi Manber at University of Arizona, Dept. of Computer Science.