Nezd is a fork of dzen that aims to add polish and features.

Changes from dzen
-----------------

- Merge in existing patches adding:
  * Support for relative positioning
  * Manual page
  * Bug and documentation fixes

- Xft, Xinerama, and Xpm are now required
- Removed deprecated '-u' flag

Nezd is a general purpose messaging, notification and menuing program for X11.
It was designed to be fast, tiny and scriptable in any language.

Features
--------

    * Small, fast, very tiny set of dependencies (Xlib, XPM, and XFT only by default)
    * Scriptable in any language
    * Sophisticated formating language - including colours, icons, graphics
    * Versatile - display all sorts of information
    * Interactive - user defined mouse and keyboard actions
    * XFT support
    * XINERAMA support

Requirements
------------
In order to build nezd you need the Xlib, Xinerama, XPM and Xft header files.

Installation
------------
Edit config.mk to match your local setup (nezd is installed into
the /usr/local namespace by default).

Afterwards enter the following command to build and install nezd (if
necessary as root):

    make clean install

Optionally if you want to use nezd's gadgets:

    cd gadgets
    make clean install

Running nezd
------------
nezd accepts a couple of options:

    -fg     foreground color
    -bg     background color
    -fn     font
    -ta     alignment of title window content
            l(eft), c(center), r(ight)
    -tw     title window width (can be relative with %)
    -sa     alignment of slave window, see "-ta"
    -l      lines, see (1)
    -e      events and actions, see (2)
    -m      menu mode, see (3)
    -p      persist EOF (optional timeout in seconds)
    -x      x position (can be relative with %)
    -y      y position (can be relative with %)
    -h      line height (default: fontheight + 2 pixels) (can be relative with %)
    -w      width (can be relative with %)
    -xs     number of Xinerama screen
    -v      version information

    see (4) for the in-text formating language.

X resources
-----------

Nezd is able to read font and color setting from X resources.
As an example you can add following lines to ~/.Xresources

nezd.font:       -*-fixed-*-*-*-*-*-*-*-*-*-*-*-*
nezd.foreground: #22EE11
nezd.background: black


Window layout
-------------

Nezd's window layout is as follows:

     ------------------------------------------
    |        Title window, single line         |
    `------------------------------------------´
    |                                          |
    |               scrollable                 |
    |              Slave window                |
    |             multiple lines               |
    |     lines to display simultaneously      |
    |           controlled with the            |
    |              '-l' option                 |
    |                                          |
    |                                          |
    `------------------------------------------´

The first line you provide to nezd always goes to the title window,
all other consecutive lines will be drawn to the slave window unless
you explicitly override this with the (4) In-text formating language
command ^tw().


QA:
---

Q1:  I don't want a slave window, what to do?

A1:  Do not provide the '-l' option, all lines will be displayed
     in the title window, this is the default behaviour.


Q2:  I used the '-l' option but no slave window appears.

A2:  With the default event/action handling the slave window will
     only be displayed if you hoover with the mouse over the title
     window. See "(2) Events and actions" if you'd like to change
     this.


Q3:  If I echo some text or cat a file nezd closes itself immediately.

A3:  There are 2 different approaches nezd uses to terminate itself,
     see next section "Termination".


Q4:  Ok, the title and slave thing works, can I update the
     contents of both windows at the same time?

A4:  Use the in-text command "^tw()" to explicitly draw to the title window.
     See section (4) for further details


Q5:  Can I change color of my input at runtime?

A5:  Yes, you can change both background and foreground colors and
     much more See "(4) In-Text formating language"


Q6:  Can I use nezd as a menu?

A6:  Yes, both vertical and horizontal menus are supported.
     See "(3) Menu" for further details.

Termination:
------------
nezd uses two different approaches to terminate itself:

    * Timed termination: if EOF is received -> terminate
        - unless the '-p' option is set
            · '-p' without argument persist forever
            · '-p' with argument n  persist for n seconds

    * Interactive termination: if mouse button3 is clicked -> terminate
        - this is the default behaviour, see (2)
        - in some modes the Escape key terminates too, see (2)

Return values:
--------------
0               -   nezd received EOF
1               -   some error occurred, inspect the error message
user defined    -   set with 'exit:retval' action, see (2)


(1) Option "-l": Slave window
--------------------------------

Enables support for displaying multiple lines. The parameter to "-l"
specifies the number of lines to be displayed.

These lines of input are held in the slave window which becomes active as soon
as the pointer enters the title (default action) window.

If the mouse leaves the slave window it will be hidden unless it is set
sticky by clicking with Button2 into it (default action).

Button4 and Button5 (mouse wheel) will scroll the slave window up
and down if the content exceeds the window height (default action).


(2) Option '-e': Events and actions
-----------------------------------

nezd allows the user to associate actions to events.

The command line syntax is as follows:
-e 'event1=action1:option1:...option<n>,...,action<m>;...;event<l>'

Every event can take any number of actions and every action can take any number
of options. (By default limited to 64 each, easily changeable in action.h)

An example:
    -e 'button1=exec:xterm:firefox;entertitle=uncollapse,unhide;button3=exit'

    Meaning:

    button1=exec:xterm:firefox;
    on Button1 event (Button1 press on the mouse) execute xterm and
    firefox.
    Note: xterm and firefox are options to the exec action

    entertitle=uncollapse,unhide;
    on entertitle (mouse pointer enters the title window) uncollapse
    slave window and unhide the title window

    button3=exit
    on button3 event exit nezd


Supported events:
-----------------

    onstart             Perform actions right after startup
    onexit              Perform actions just before exiting
    onnewinput          Perform actions if there is new input for the slave window
    button1             Mouse button1 released
    button2             Mouse button2 released
    button3             Mouse button3 released
    button4             Mouse button4 released (usually scrollwheel)
    button5             Mouse button5 released (usually scrollwheel)
    button6             Mouse button6 released
    button7             Mouse button7 released
    entertitle          Mouse enters the title window
    leavetitle          Mouse leaves the title window
    enterslave          Mouse enters the slave window
    leaveslave          Mouse leaves the slave window
    sigusr1             SIGUSR1 received
    sigusr2             SIGUSR2 received
    key_KEYNAME         Keyboard events (*)


    (*) Keyboard events:
    --------------------

    Every key can be bound to an action (see below). The format is:
    key_KEYNAME where KEYNAME is the name of the key as defined in
    keysymdef.h (usually: /usr/include/X11/keysymdef.h).  The part
    after 'XK_' in keysymdef.h must be used for KEYNAME.

Supported actions:
------------------

    exec:command1:..:n  execute all given options
    menuexec            executes selected menu entry
    exit:retval         exit nezd and return 'retval'
    print:str1:...:n    write all given options to STDOUT
    menuprint           write selected menu entry to STDOUT
    collapse            collapse (roll-up) slave window
    uncollapse          uncollapse (roll-down) slave window
    togglecollapse      toggle collapsed state
    stick               stick slave window
    unstick             unstick slave window
    togglestick         toggle sticky state
    hide                hide title window
    unhide              unhide title window
    togglehide          toggle hide state
    raise               raise window to view (above all others)
    lower               lower window (behind all others)
    scrollhome          show head of input
    scrollend           show tail of input
    scrollup:n          scroll slave window n lines up   (default n=1)
    scrolldown:n        scroll slave window n lines down (default n=1)
    grabkeys            enable keyboard support
    ungrabkeys          disable keyboard support
    grabmouse           enable mouse support
                        only needed with specific windowmanagers, such as fluxbox
    ungrabmouse         release mouse
                        only needed with specific windowmanagers, such as fluxbox

Note:   If no events/actions are specified nezd defaults to:

        Title only mode:
        ----------------

        -e 'button3=exit:13'

        Multiple lines and vertical menu mode:
        --------------------------------------

        -e 'entertitle=uncollapse,grabkeys;
            enterslave=grabkeys;leaveslave=collapse,ungrabkeys;
            button1=menuexec;button2=togglestick;button3=exit:13;
            button4=scrollup;button5=scrolldown;
            key_Escape=ungrabkeys,exit'

        Horizontal menu mode:
        ---------------------

        -e 'enterslave=grabkeys;leaveslave=ungrabkeys;
            button4=scrollup;button5=scrolldown;
            key_Left=scrollup;key_Right=scrolldown;
            button1=menuexec;button3=exit:13
            key_Escape=ungrabkeys,exit'

        If you define any events/actions, there is no default behaviour,
        i.e. you will have to specify _all_ events/actions you want to
        use.

(3) Option '-m', Menu
---------------------

Nezd provides two menu modes, vertical and horizontal menus. You can
access these modes by adding 'v'(ertical) or 'h'(horizontal) to the
'-m' option. If nothing is specified nezd defaults to vertical menus.

Vertical menu, both invocations are equivalent:
    nezd -p -l 4 -m < file
    nezd -p -l 4 -m v < file

Horizontal menu:
    nezd -p -l 4 -m h < file


All actions beginning with "menu" work on the selected menu entry.

Note:   Menu mode only makes sense if '-l <n>' is specified!

        Horizontal menus have no title window, so all actions
        affecting the title window will be silently discarded
        in this mode.

(4) In-text formating & control language:
-----------------------------------------

This feature allows to dynamically (at runtime) format the text nezd
displays and control its behaviour.

Currently the following commands are supported:


Note:  Doubling the '^' character ('^^') will remove the special meaning from it.

Colors:
-------

    ^fg(color)         set foreground color
    ^fg()              without arguments, sets default fg color
    ^bg(color)         set background color
    ^bg()              without arguments, sets default bg color

Graphics:
---------

    ^i(path)           draw icon specified by path
                       Supported formats: XBM and XPM

    ^r(WIDTHxHEIGHT)   draw a rectangle with the dimensions
                       WIDTH and HEIGHT
    ^ro(WIDTHxHEIGHT)  rectangle outline

    ^c(RADIUS)         draw a circle with size RADIUS pixels
    ^co(RADIUS)        circle outline

Positioning:
------------

    ^p(ARGUMENT)       position next input amount of PIXELs to the right
                       or left of the current position
                       a.k.a. relative positioning

    ^pa(ARGUMENT)      position next input at PIXEL
                       a.k.a. absolute positioning

     ARGUMENT:

     ^p(+-X)          move X pixels to the right or left of the current position (on the X axis)

     ^p(+-X;+-Y)      move X pixels to the right or left and Y pixels up or down of the current
                      position (on the X and Y axis)

     ^p(;+-Y)         move Y pixels up or down of the current position (on the Y axis)

     ^p()             without parameters resets the Y position to its default

     ^pa()            takes the same parameters as described above but positions at
                      the absolute X and Y coordinates

     Further ^p() also takes some symbolic names as argument:

     _LOCK_X          Lock the current X position, useful if you want to
                      align things vertically
     _UNLOCK_X        Unlock the X position
     _LEFT            Move current x-position to the left edge
     _RIGHT           Move current x-position to the right edge
     _TOP             Move current y-position to the top edge
     _CENTER          Move current x-position to center of the window
     _BOTTOM          Move current y-position to the bottom edge

Interaction:
------------

    ^ca(BTN, CMD) ... ^ca()

                       Used to define 'clickable areas' anywhere inside the
                       title window or slave window.
                       - 'BTN' denotes the mouse button (1=left, 2=right, 3=middle, etc.)
                       - 'CMD' denotes the command that should be spawned when the specific
                         area has been clicked with the defined button
                       - '...' denotes any text or formating commands nezd accepts
                       - '^ca()' without arguments denotes the end of this clickable area

                       Example:
                         foo ^ca(1, echo one)^fg(red)click me and i'll echo one^fg()^ca() bar

Actions as commands:
--------------------

    ^togglecollapse()
    ^collapse()
    ^uncollapse()
    ^togglestick()
    ^stick()            See section (2) 'Events and actions' for a detailed description
    ^unstick()          of each command.
    ^togglehide()
    ^hide()
    ^unhide()
    ^raise()
    ^lower()
    ^scrollhome()
    ^scrollend()
    ^exit()

Other:
------

    ^tw()              draw to title window
                       This command has some annoyances, as only
                       the input after the command will be drawn
                       to the title window, so it is best used
                       only once and as first command per line.

    ^cs()              clear slave window
                       This command must be the first and only command
                       per line.

    ^ib(VALUE)         ignore background setting, VALUE can be either
                       1 to ignore or 0 to not ignore the bg color set
                       with ^bg(color).
                       This command is useful in combination with ^p()
                       and ^pa() in order to position the input inside
                       other already drawn input.

                       Example:
                         ^ib(1)^fg(red)^ro(100x15)^p(-98)^fg(blue)^r(20x10)^fg(orange)^p(3)^r(40x10)^p(4)^fg(darkgreen)^co(12)^p(2)^c(10)


These commands can appear anywhere and in any combination in nezd's
input.

The color can be specified either as symbolic name (e.g. red,
darkgreen, etc.) or as #rrggbb hex-value (e.g. #ffffaa).

Icons must be in the XBM or XPM format, see the "bitmaps"
directory for some sample icons. With the standard "bitmap" application
you can easily draw your own icons.

Some examples:

   Input:
          ^fg(red)I'm red text ^fg(blue)I am blue

   Input:
          ^bg(#ffaaaa)The ^fg(yellow)text to ^bg(blue)^fg(orange)colorize

   Input:
          ^fg(grey70)Some text containing ^^ characters

   Input for icons:
          ^i(bitmaps/envelope.xbm) I am an envelope ^fg(yellow)and ^i(bitmaps/battery.xbm) I'm a battery.

   Input for rectangles:
          6x4 rectangle ^r(6x4) ^fg(red)12x8 ^r(12x8) ^fg(yellow)and finally 100x15 ^r(100x15)

   Input for relative positioning:
          Some text^p(100)^fg(yellow)100 pixels to the right^p(50)^fg(red)50 more pixels to the right

Examples:
---------

* Display message and timeout after 10 seconds:
    (echo "This is a message"; sleep 10) | nezd -bg darkred -fg grey80 -fn fixed

* Display message and never timeout:
    echo "This is a message"| nezd -p

* Display updating single line message:
    for i in $(seq 1 20); do A=${A}'='; print $A; sleep 1; done | nezd

* Display header and a message with multiple lines:
    (echo Header; cal; sleep 20) | nezd -l 8

    Displays "Header" in the title window and the output of cal in the 8
    lines high slave window.

* Display updating messages:
    (echo Header; while true; do echo test$((i++)); sleep 1; done) | nezd -l 12

    The slave window will update contents if new input has arrived.

* Display log files:
    (su -c "echo LOGFILENAME; tail -f /var/log/messages") | nezd -l 20 -x 100 -y 300 -w 500

* Monthly schedule with remind:
    (echo Monthly Schedule; remind -c1 -m) | nezd -l 52 -w 410 -p -fn lime -bg '#e0e8ea' -fg black -x 635

* Simple menu:
    echo "Applications" | nezd -l 4 -p -m < menufile

* Horizontal menu without any files:
    {echo Menu; echo -e "xterm\nxclock\nxeyes\nxfontsel"} | nezd -l 4 -m h -p

* Extract PIDs from the process table:

    {echo Procs; ps -a} | nezd -m -l 12 -p \
    -e 'button1=menuprint;button3=exit;button4=scrollup:3;button5=scrolldown:3;entertitle=uncollapse;leaveslave=collapse' \
            | awk '{print $1}'

* Nezd as xmonad (see http://xmonad.org) statusbar:

    status.sh | nezd -ta r -fn '-*-profont-*-*-*-*-11-*-*-*-*-*-iso8859' -bg '#aecf96' -fg black \
        -p -e 'sigusr1=raise;sigusr2=lower;onquit=exec:rm /tmp/nezd-pid;button3=exit' & echo $! > /tmp/nezd-pid

Have fun.