[NEXT ] [UP ]

How to use this Tutorial

The following provides an interactive tutorial how to use Neo. Each lesson will acquaint you with a set of topically related commands and techniques. They will first be explained with demo circuits that are as simple as possible. Then, their full power will be shown with more advanced examples. On a first tour, you can skip these (or just try them out, without really looking inside). On a second tour through the tutorial, these advanced examples will help to illustrate additional features and more subtle points. Before we start, here are some general hints how to navigate through the tutorial:

Prerequisites

To use this tutorial, you will need Neo with version 7.1 or higher, NST with version 7.1 or higher (you get the version numbers by typing "neo -V") and the KDE Konqueror or Netscape viewer with version 4.0 or higher.

How to set up your environment

Your home directory should contain the following files or directories:

.neofolders  a file with a listing of folders to load (a sample file is here )
.neo        a file with initial parameter settings (a sample file is here )
.nstplugin    a directory which may initially be empty

Neo and NST  use the directory search path held in environment variable $NSTPATH to locate circuit or data files. Make sure that this variable exists and contains at least the name of the tutorial directory in which the *.HNST example circuits are located. E.g., if .bashrc is your shell startup file, $NSTPATH might be defined as

    export NSTPATH=~/nst5/doc/tutorial

(you can specify any colon-separated list of directory names). There is a second path variable $NST_LD_LIBRARY_PATH that tells Neo/NST where to look for NST-specific shared libraries. If this path variable is not defined, $LD_LIBRARY_PATH will be used as the default.

To properly go on, you must first configure netscape to send *.HNST files (they contain the examples) to Neo. For Netscape, follow these steps:

  • 1. Select Preferences in the Edit menu
  • 2. Select the arrow before the category "Navigator" to open the navigator preferences and select "Applications"
  • 3. Select "New" to define a new helper application
  • 4. Fill the Description entry with "neo circuit", the MIME Type field with "application/neo", and the Suffixes field with "HNST,hnst".
  • 5. Select the Application radio button and enter in the Application entry "/vol/nst/bin/neohelper %s". Note, that for Netscape 6 and above as well as for Mozilla you need to omit the %s.

    • For the Konqueror browser, you need to copy the auxiliary shell script neohelper  (it wraps the ""cat %s >  ..." command) into your bin directory (or any other directory in your search path for shell scripts). Then the analogous steps are:

    Remark: The non-standard suffix *.HNST for the example circuits is used to avoid that the nstplugin - when loaded - consumes the circuit file when an example link is selected (in the usual configuration, the nstplugin will be invoked for all files with suffix *.NST).

    How to navigate through the tutorial

    Note, that for "safety reasons" (according to P. Koch), the TechFak web server does not send the correct mime type with the *.HNST circuit files. Therefore, in order to use the automatic loading of Neo circuits you need to use the local version of the tutorial.

    Start Neo with the command

    neo -i :netscape &

    The "-i :netscape" configures Neo in such a way that a browser (such as Netscape or Konqueror) can directly pipe the *.HNST example file behind a selected example link into Neo. This communication proceeds via a named pipe (FIFO) in the .nstplugin directory (the tutorial neither needs nor uses the nstplugin , but it accesses in the so-named directory the same FIFO that is also used by the plugin). If the FIFO does not yet exist, Neo will offer to create it (answer "OK").

    The tutorial consists of a set of HTML documents, together with a set of Neo example circuits. Usually you should navigate by following hyperlinks in the netscape browser, however, some Neo examples also offer hyperlinks that are embedded in the Neo circuit. If you follow these, Neo will send a command to netscape to change to an appropriate page. Thus, you can navigate at two different levels.

    How to explore the examples

    To explore an example, click at its hyperlink. When you then move with the mouse pointer into one of Neo's windows, Neo will start to load the example (if there is already an example loaded, Neo will first ask for permission to overwrite it; if you refuse, the load attempt will be ignored). When the example is loaded, you can start it with the "Step" command in the leftmost menue of command buttons (usually, the text explains carefully what to do). If something goes wrong, just restart Neo with the above command. If Neo seems to block, the named fifo ~/.nstplugin/:netscape may have become corrupted. In this case, remove that file and start again.

    Useful accelerator keys

    Many Neo commands can be invoked directly from the keyboard by typing ALT-c, where c is the character that appears underlined on a Neo command button. Additionaly, there are the following general Neo accelerator keys:

    Ctrl-Return, ESC   leave current dialog with Cancel
    Alt-Return accept current dialog with OK
    Ctrl-Return leave current dialog with Cancel
    Alt-Tab select next icon
    Alt-Backspace select previous icon
    Alt-x execute selected icon once
    Alt-m modify selected icon
    Alt-# open parameter dialog for selected icon
    Alt-- wrap selected icons in container
    Alt-< optimize wire layout
    Alt-o open selected icon
    Alt-u goto next outer circuit, or enter variable dialog, if already at topmost level
    Alt-0..4 select one of circuits #0 .. #4

    For ALT, the left or right ALT key can be used.

    How to enter or edit text in NST dialog windows

    Entering or editing text in NST dialog windows become much more convenient when you know the following editing commands:

    Ctrl-A,E  goto begin/end of line
    Ctrl-B,F  one letter backward/forward
    Ctrl-C    copy selection into paste buffer
    Ctrl-D,U  one letter downward/upward
    Ctrl-G    goto token or find a token
    Ctrl-J    invoke external editor $MYEDITOR
    Ctrl-K    kill line (into paste buffer)
    Ctrl-L    cut all
    Ctrl-N    find next occurrence of selected text
    Ctrl-H    backspace erase
    Ctrl-P    find previous occurrence of selected text
    Ctrl-Q    query man page of edited icon
    Ctrl-R    delete current char
    Ctrl-S    substitute selected text by contents of buffer and progress to next/previous occurrence
    Ctrl-T,Z  goto top/bottom of text
    Ctrl-V    insert (and empty) paste buffer at cursor
    Ctrl-W    if cursor is on bracket: goto matching bracket (including comment delimiters)
    Ctrl-X    kill selection (into paste buffer)
    Ctrl-Y    yank paste buffer

    You'll most probably need Ctrl-C, Ctrl-K, Ctlr-L (for cutting various amounts of text), Ctrl-V, Ctrl-Y (for re-pasting the text) and Ctrl-J  (for using your favorite editor) most frequently.

    How to find additional information

    You can find additional information in the following postscript files:
     
  • Neo in 20+ Pages :  short documentation of Neo
  • NST in 8+ Pages :  short documentation of the underlying NST system
  • The NST Programming guide :  detailed description of NST programming
  • Neo/NST Technical Synopsis :  an overview of the Neo/NST system architecture
  • The tools Mku+ and Mku++ : a description how to wrap C/C++ classes to make them available as NST units
  • The Nst loader library libnstld.a :  a description of a library to instantiate Neo circuits in C/C++ programs from Neo their circuit files