[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:

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/NST use the environment variable $NSTPATH to locate circuit and data files. Make sure that this variable exists and contains at least the name of the tutorial directory, e.g.

export NSTPATH=/vol/nst/man/tutorial

The variable $NST_LD_LIBRARY_PATH tells Neo/NST where to find NST-specific shared libraries. If this path variable is not defined, $LD_LIBRARY_PATH will be used as a default.

To properly go on, you should configure your browser to handle *.HNST sample circuit files. For Ubuntu, first register a mime type and an application for it as follows (if not yet done system-wide):

  1. Create or download the following neo.desktop file for Neo/NST in the folder ~/.local/share/applications:
    [Desktop Entry]
    Name=Neo/NST
    GenericName=Neo Graphical Programming Environment
    TryExec=/vol/nst/bin/neo-wrapper
    Exec=/vol/nst/bin/neo-wrapper
    Terminal=true
    Type=Application
    StartupNotify=false
    MimeType=text/x-nst
    
  2. Create or download the file agni-nst.xml describing the mime type:
    <mime-info xmlns='http://www.freedesktop.org/standards/shared-mime-info'>
      <mime-type type="text/x-nst">
        <comment>Neo/NST circuit</comment>
        <glob pattern="*.HNST"/>
        <glob pattern="*.NST"/>
        <glob pattern="*.NST.gz"/>
      </mime-type>
    </mime-info>
    
  3. Register this mime type:
    xdg-mime install agni-nst.xml
  4. Define the default application for the new mime type:
    xdg-mime default neo.desktop text/x-nst
  5. If necessary, configure your favorite browser to consider the new mime type.

Remark: The non-standard suffix .HNST for the example circuits avoids conflicts with the nstplugin, which will consume files with suffix *.NST by default.

How to explore the examples

The neo-wrapper script installed as the mime-type handler will open an example circuit as you click its hyperlink. By default, a new Neo/NST session will be started every time.
To avoid this, start Neo/NST from the menu or with the following command first:

neo-wrapper

This starts Neo/NST in fifo mode, i.e. actually issuing the command:

neo -i :netscape

which creates the fifo file ~/.nstplugin/:netscape, which Neo/NST watches for new circuits to load.

If the current circuit window is non-empty, Neo will first ask for permission to overwrite it. If you refuse, the new 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 Neo/NST blocks, the fifo might have become corrupted. In this case, remove that file and start over.

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