= Ginsu Manual =

Ginsu is a client for the gale chat system. It is designed to be powerful and
above all stable, as well as having a quick learning curve.


== Using Ginsu ==


=== Keys ===

These are the default keybindings. You may use the action name to rebind a key. See below for details.

<include `perl ../gen_keyhelp.prl -c ../ginsu.config.sample ../actions.def`>

=== Options ===

<pre>
ginsu [OPTIONS]...  [categories]...
</pre>

<include `../ginsu --showOptions`>

=== Filters ===

Filters are used throughout ginsu. A filter is an expression which selects
puffs which match it.

Filters are built up from primitives via conjunctions, disjunctions and
grouping, allowing complex filters to be created.

<pre>
a ; b - semicolons are used to mean OR. this matches if a OR b matches
a b - a space means AND. this matches if a AND b both match
(a b) ; c - filters may be grouped with parenthesis
!a - NOT. this matches if a does not match
</pre>

primitive filters are regular expressions which are matched against the body
of the puff, or a variety of special forms beginning with a ~ then a single
character, then a colon, then the rest of the special form. If the text
following the colon begins with a letter, the colon may be omitted. Arbitrary
text may be used in filters by quoting it with single quotes.


||||  Special Forms  ||
|| ~a:<gale-id>||author of puff ||
|| ~c:<category>||category puff was sent too ||
|| ~k:<regex>||regex match against keywords ||
|| ~s:<regex>||regex match against senders real name ||
|| ~b:<regex>||regex match against message body ||
|| /<regex>|| search everything visible for regex ||
|| ?true || always succeed ||
|| ?false || always fail ||
|| ?signed || puff is signed ||
|| ?encrypted || puff is encrypted ||

Examples of Filters:

<pre>
 (~a:john@ugcs.caltech.edu) - all puffs by me
 (~c:pub.tv.buffy ~a:jtr@ofb.net) - puffs from jtr and to pub.tv.buffy
 ( /[gG]insu ; ~c:pub.gale.ginsu) - puffs containing the word ginsu or directed to pub.comp.ginsu
 ( /'(?i)john +meacham' ) - puffs with my name in them
 (!~k:^spoil) - no spoilers
 (~c:pub.tv.buffy !~c:pub.meow) - puffs to buffy which are not about cats
</pre>


=== The Filter Stack ===

There is always a current filter stack, which is a set of filters that
determines which puffs are currently visible. there are a variety of
keystrokes to modify the filter stack. If non-empty, the current filter stack
is displayed on the bottom line of the main screen.


== Environment Variables ==

; BROWSER : which web browser to use in the default application hooks.
; EDITOR : used if $VISUAL is not set.
; GALE_CONF : name of alternate Gale configuration file to read. This does not change the name of the ginsu specific configuration file.
; GALE_DIR  : alternate location for user's gale directory. ~/.gale/ by default.
; VISUAL : editor to use for composing puffs.

If any of these exist in the environment prefixed with GINSU_, they are
preferred over the bare versions.


== Configuration Options ==


=== Standard Gale Options Honored by Ginsu ===

; GALE_DOMAIN : The current gale domain.
; GALE_ID : Your gale id. default is $LOGNAME@$GALE_DOMAIN
; GALE_NAME : Your real name used in puffs sent.
; GALE_PRESENCE : default presence string to send out.
; GALE_PROXY : This can be used to override which gale server to connect to.
; GALE_SUBSCRIBE : List of categories to subscribe to. The default is some common public categories and your private address.

see also:  http://gale.org/users/vars

=== Ginsu Specific Options ===

; BEEP : beep on incoming puffs which match this filter.
; BROWSER : set the web browser. This overrides the environment. This is only used by the default 'apphook' declarations. see below.
; CHARSET : character set to assume files are in. This will become obsolete at some point.
; DISABLE_SIGWINCH : do not install sigwinch handler. ignore if you don't know what this means.
; EDITOR_NEWPUFF_OPTION : options passed to editor when beginning a new puff.
; EDITOR_OPTION : options passed to editor when replying to a puff.
; MARK_[1-9] : these should be set to filters which are activated by the corresponding number key.
; NO_PRESENCE_NOTIFY : disable presence notifications.
; ON_INCOMING_PUFF : macro to run when new puff is received.
; ON_STARTUP : on startup, run this macro.
; PRESERVED_KEYWORDS : when replying to a puff, keep these keywords intact.
; PUFFLOG_SIZE : number of puffs to store in the pufflog.
; SCROLLBACK_SIZE : maximum number of puffs to keep in memory (or 0 for no limit).
; TRIM_BLANKLINES : before sending a puff, get rid of leading and trailing blank lines.
; VISUAL : set the editor. This overrides the environment.
; USE_DEFAULT_COLORS : use the default colors of your terminal if possible.
; PUFF_DATE_FORMAT : format string to use in puff display



=== Changing Keybindings ===

keys may be rebound with the 'bind' keyword in the configuration file. the syntax is
<pre>
bind <key> <command>
</pre>

here are some examples:
<pre>
bind <C-r> reconnect_to_servers
bind c prompt_new_filter
bind v goto_match
</pre>


=== Changing Application Hooks ===

When puff bodies match regular expressions, the user may choose to run
arbitrary commands based on them. This can be used to follow web links in
puffs for instance. The 'apphook' mechanism is fully configurable via using
'apphook' lines in your <tt>ginsu.config</tt> file.

The general form is:
<pre>
apphook <name>
        <regular expression>
        <command to run>
        [string user sees in menu ("$0" by default)]
</pre>
in the command and menu string, <tt>$0</tt> is replaced by the whole regex match and
<tt>$1, $2, .. $9</tt> are replaced by the substrings captured by parenthesis
in the regular expression.



<pre>
apphook WikiWord
        '([[:space:]]|^)(([[:upper:]][[:lower:]]+){2,})([[:space:]]|$)'
        '$BROWSER ''http://wiki.ofb.net/?$2'''
        '$2'

apphook URL
        '(http|ftp)s?://(%[[:digit:]A-Fa-f][[:digit:]A-Fa-f]|[-_.!~*'';/?:@&=+$,[:alnum:]])+'
        '$BROWSER ''$0'''
</pre>

=== Category Aliases ===

Ginsu uses the same alias mechanism as 'gsend'. Aliases take the form of
symbolic links in the aliases directory in the gale directory.

Here is an example of how to create new aliases.

<pre>
mkdir ~/.gale/aliases  # only if it does not already exist
cd ~/.gale/aliases
ln -s pub pub@ofb.net
ln -s ugcs ugcs@ugcs.caltech.edu
</pre>

== Files ginsu uses ==

$GALE_DIR is ~/.gale/ by default.

; <tt>$GALE_DIR/ginsu.config</tt> : main configuration file.
; <tt>$GALE_DIR/ginsu.<i>n</i>.pufflog</tt> : pufflog version <i>n</i>
; <tt>$GALE_DIR/ginsu.errorlog</tt> : main configuration file.
; <tt>$GALE_DIR/auth/private/*</tt> : This is where ginsu looks for private keys for decoding incoming encrypted puffs.
; <tt>$GALE_DIR/auth/cache/*</tt> : This is where ginsu looks for and stores public keys.

== Other ginsu resources ==

* http://repetae.net/john/computer/ginsu/ - the project homepage
* http://wiki.ofb.net/?GinsuFaq - the ginsu FAQ and wiki
* http://gale.org/ - gale homepage
* http://bugs.ofb.net/cgi-bin/bugzilla/enter_bug.cgi?product=Ginsu - report bugs here.
* http://repetae.net/john/ - author's homepage.

There is also a public arch repository for ginsu at http://repetae.net/john/arch/2004/

<html>
</html>