ginsu-0.8.0: docs/ginsu-manual.html
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><head><title>Ginsu Manual</title><link type="text/css" rel="stylesheet" href="wiki.css"><meta http-equiv="Content-Type" content="text/html; charset=utf-8"></head><body class="http://localhost/home/john/bin/share/mup.prl"><h1>Ginsu Manual</h1><p>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.<p><h2>Using Ginsu</h2><h3>Keys</h3><p>These are the default keybindings. You may use the action name to rebind a key. See below for details.<p><table class="user"><tr><td><b>Action Name</b></td><td><b>Default Key</b></td><td><b>Description</b></td></tr><tr><td colspan="3"><b><i>Main Screens</i></b></td></tr><tr><td>show_help_screen</td><td><F1>, ?</td><td>Show help screen</td></tr><tr><td>show_presence_status</td><td><F3></td><td>show presence status</td></tr><tr><td>show_puff_details</td><td>d</td><td>show puff details</td></tr><tr><td>show_status_screen</td><td>S</td><td>show status screen</td></tr><tr><td colspan="3"><b><i>Puff Movement</i></b></td></tr><tr><td>next_puff</td><td>j, <Down></td><td>Goto the next puff</td></tr><tr><td>previous_puff</td><td>k, <Up></td><td>Goto the previous puff</td></tr><tr><td>first_puff</td><td><Home></td><td>Goto the first puff</td></tr><tr><td>last_puff</td><td><End>, G</td><td>Goto the last puff</td></tr><tr><td>next_line</td><td><Enter>, <C-E></td><td>Scroll one line down</td></tr><tr><td>previous_line</td><td><BackSpace>, <C-Y></td><td>Scroll one line up</td></tr><tr><td>next_page</td><td><C-F>, <PageDown></td><td>Scroll one page down</td></tr><tr><td>previous_page</td><td><C-B>, <PageUp></td><td>Scroll one page up</td></tr><tr><td>forward_half_page</td><td><C-D></td><td>Scroll a half page down</td></tr><tr><td>backward_half_page</td><td><C-U></td><td>Scroll a half page up</td></tr><tr><td colspan="3"><b><i>Filter Manipulation</i></b></td></tr><tr><td>prompt_new_filter</td><td>c</td><td>prompt new filter</td></tr><tr><td>prompt_new_filter_slash</td><td>/</td><td>prompt new filter slash</td></tr><tr><td>prompt_new_filter_twiddle</td><td>~</td><td>prompt new filter twiddle</td></tr><tr><td>pop_one_filter</td><td>u</td><td>pop one filter</td></tr><tr><td>pop_all_filters</td><td>U</td><td>pop all filters</td></tr><tr><td>invert_filter</td><td>!</td><td>invert filter</td></tr><tr><td>filter_current_thread</td><td>t, T</td><td>filter current thread</td></tr><tr><td>swap_filters</td><td>x</td><td>swap filters</td></tr><tr><td>filter_current_author</td><td>a</td><td>filter current author</td></tr><tr><td colspan="3"><b><i>Puff Body Filtering</i></b></td></tr><tr><td>toggle_rot13</td><td><C-o></td><td>toggle Rot13 filter</td></tr><tr><td colspan="3"><b><i>Mark/Workspace Manipulation</i></b></td></tr><tr><td>set_mark</td><td>m</td><td>save current position at a given mark.</td></tr><tr><td>recall_mark</td><td><SingleQuote></td><td>goto position saved at mark</td></tr><tr><td>set_filter_mark</td><td>M</td><td>save current filter stack at given mark.</td></tr><tr><td>recall_filter_mark</td><td><DoubleQuote></td><td>Recall filter stack at mark</td></tr><tr><td>recall_combine_mark</td><td>C</td><td>Recall filter stack at mark and combine it with the current filter stack.</td></tr><tr><td>recall_workspace</td><td>[1-9]</td><td>Recall given numbered workspace and set it as current workspace, these follow marks [1-9]</td></tr><tr><td colspan="3"><b><i>Composing Puffs</i></b></td></tr><tr><td>new_puff</td><td>p</td><td>compose a new puff</td></tr><tr><td>follow_up</td><td>f</td><td>follow up to the same category as the current puff</td></tr><tr><td>reply_to_author</td><td>r</td><td>reply to the author of the current puff privatly</td></tr><tr><td>group_reply</td><td>g</td><td>reply to the union of the sender and categories of the current puff</td></tr><tr><td>resend_puff</td><td>R</td><td>resend puff</td></tr><tr><td colspan="3"><b><i>Miscellaneous</i></b></td></tr><tr><td>goto_match</td><td>v</td><td>visit link in current puff</td></tr><tr><td>modify_presence_string</td><td>N</td><td>modify presence string</td></tr><tr><td>reconnect_to_servers</td><td><C-r></td><td>reconnect to servers</td></tr><tr><td>edit_config_file</td><td>E</td><td>Edit the configuration file and reload its settings</td></tr><tr><td>ask_quit</td><td>q</td><td>quit ginsu</td></tr><tr><td>fast_quit</td><td>Q</td><td>quit ginsu without asking first</td></tr><tr><td>redraw_screen</td><td><C-l></td><td>redraw screen</td></tr></table> <h3>Options</h3><p><pre class="real">ginsu [OPTIONS]... [categories]...
</pre><p><table class="user"><tr><td colspan="2">Available Options</td></tr><tr><td>-v, --verbose</td><td>increase verbosity output to errorlog.</td></tr><tr><td>-V, --version</td><td>print version information</td></tr><tr><td>-s, --sample-config</td><td>print sample configuration file to stdout</td></tr><tr><td>-m, --man</td><td>print all internal help screens to stdout</td></tr><tr><td>-e, --justargs</td><td>only subscribe to command line arguments</td></tr><tr><td>-P</td><td>do not write to pufflog</td></tr><tr><td>--help</td><td>show this help screen</td></tr><tr><td>--nopufflog</td><td>do not read or write pufflog</td></tr><tr><td>--errorlog <i><FILE></i></td><td>log errors to file</td></tr><tr><td>--dumpkey <i><KEYFILE></i></td><td>print info for keyfile</td></tr><tr><td>--checkconfig</td><td>check and print out configuration</td></tr></table> <h3>Filters</h3><p>Filters are used throughout ginsu. A filter is an expression which selects puffs which match it.<p>Filters are built up from primitives via conjunctions, disjunctions and grouping, allowing complex filters to be created.<p><pre class="real">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><p>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.<p><table class="user"><tr><td colspan="2">Special Forms</td></tr><tr><td>~a:<gale-id></td><td>author of puff</td></tr><tr><td>~c:<category></td><td>category puff was sent too</td></tr><tr><td>~k:<regex></td><td>regex match against keywords</td></tr><tr><td>~s:<regex></td><td>regex match against senders real name</td></tr><tr><td>~b:<regex></td><td>regex match against message body</td></tr><tr><td>/<regex></td><td>search everything visible for regex</td></tr><tr><td>?true</td><td>always succeed</td></tr><tr><td>?false</td><td>always fail</td></tr><tr><td>?signed</td><td>puff is signed</td></tr><tr><td>?encrypted</td><td>puff is encrypted</td></tr></table><p>Examples of Filters:<p><pre class="real"> (~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><h3>The Filter Stack</h3><p>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.<p><h2>Environment Variables</h2><dl><dt>BROWSER </dt><dd> which web browser to use in the default application hooks. </dd><dt>EDITOR </dt><dd> used if $VISUAL is not set. </dd><dt>GALE_CONF </dt><dd> name of alternate Gale configuration file to read. This does not change the name of the ginsu specific configuration file. </dd><dt>GALE_DIR </dt><dd> alternate location for user's gale directory. ~/.gale/ by default. </dd><dt>VISUAL </dt><dd> editor to use for composing puffs.</dd></dl><p>If any of these exist in the environment prefixed with GINSU_, they are preferred over the bare versions.<p><h2>Configuration Options</h2><h3>Standard Gale Options Honored by Ginsu</h3><dl><dt>GALE_DOMAIN </dt><dd> The current gale domain. </dd><dt>GALE_ID </dt><dd> Your gale id. default is $LOGNAME@$GALE_DOMAIN </dd><dt>GALE_NAME </dt><dd> Your real name used in puffs sent. </dd><dt>GALE_PRESENCE </dt><dd> default presence string to send out. </dd><dt>GALE_PROXY </dt><dd> This can be used to override which gale server to connect to. </dd><dt>GALE_SUBSCRIBE </dt><dd> List of categories to subscribe to. The default is some common public categories and your private address.</dd></dl><p>see also: <a href="http://gale.org/users/vars">http://gale.org/users/vars</a><p><h3>Ginsu Specific Options</h3><dl><dt>BEEP </dt><dd> beep on incoming puffs which match this filter. </dd><dt>BROWSER </dt><dd> set the web browser. This overrides the environment. This is only used by the default 'apphook' declarations. see below. </dd><dt>CHARSET </dt><dd> character set to assume files are in. This will become obsolete at some point. </dd><dt>DISABLE_SIGWINCH </dt><dd> do not install sigwinch handler. ignore if you don't know what this means. </dd><dt>EDITOR_NEWPUFF_OPTION </dt><dd> options passed to editor when beginning a new puff. </dd><dt>EDITOR_OPTION </dt><dd> options passed to editor when replying to a puff. </dd><dt>MARK_[1-9] </dt><dd> these should be set to filters which are activated by the corresponding number key. </dd><dt>NO_PRESENCE_NOTIFY </dt><dd> disable presence notifications. </dd><dt>ON_INCOMING_PUFF </dt><dd> macro to run when new puff is received. </dd><dt>ON_STARTUP </dt><dd> on startup, run this macro. </dd><dt>PRESERVED_KEYWORDS </dt><dd> when replying to a puff, keep these keywords intact. </dd><dt>PUFFLOG_SIZE </dt><dd> number of puffs to store in the pufflog. </dd><dt>SCROLLBACK_SIZE </dt><dd> maximum number of puffs to keep in memory (or 0 for no limit). </dd><dt>TRIM_BLANKLINES </dt><dd> before sending a puff, get rid of leading and trailing blank lines. </dd><dt>VISUAL </dt><dd> set the editor. This overrides the environment. </dd><dt>USE_DEFAULT_COLORS </dt><dd> use the default colors of your terminal if possible. </dd><dt>PUFF_DATE_FORMAT </dt><dd> format string to use in puff display</dd></dl><p><h3>Changing Keybindings</h3><p>keys may be rebound with the 'bind' keyword in the configuration file. the syntax is <pre class="real">bind <key> <command>
</pre><p>here are some examples: <pre class="real">bind <C-r> reconnect_to_servers
bind c prompt_new_filter
bind v goto_match
</pre><h3>Changing Application Hooks</h3><p>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.<p>The general form is: <pre class="real">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.<p><pre class="real">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><h3>Category Aliases</h3><p>Ginsu uses the same alias mechanism as 'gsend'. Aliases take the form of symbolic links in the aliases directory in the gale directory.<p>Here is an example of how to create new aliases.<p><pre class="real">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><h2>Files ginsu uses</h2><p>$GALE_DIR is ~/.gale/ by default.<p><dl><dt><tt>$GALE_DIR/ginsu.config</tt> </dt><dd> main configuration file. </dd><dt><tt>$GALE_DIR/ginsu.<i>n</i>.pufflog</tt> </dt><dd> pufflog version <i>n</i> </dd><dt><tt>$GALE_DIR/ginsu.errorlog</tt> </dt><dd> main configuration file. </dd><dt><tt>$GALE_DIR/auth/private/*</tt> </dt><dd> This is where ginsu looks for private keys for decoding incoming encrypted puffs. </dd><dt><tt>$GALE_DIR/auth/cache/*</tt> </dt><dd> This is where ginsu looks for and stores public keys.</dd></dl><p><h2>Other ginsu resources</h2><ul><li><a href="http://repetae.net/john/computer/ginsu/">http://repetae.net/john/computer/ginsu/</a> - the project homepage </li><li><a href="http://wiki.ofb.net/?GinsuFaq">http://wiki.ofb.net/?GinsuFaq</a> - the ginsu FAQ and wiki </li><li><a href="http://gale.org/">http://gale.org/</a> - gale homepage </li><li><a href="http://bugs.ofb.net/cgi-bin/bugzilla/enter_bug.cgi?product=Ginsu">http://bugs.ofb.net/cgi-bin/bugzilla/enter_bug.cgi?product=Ginsu</a> - report bugs here. </li><li><a href="http://repetae.net/john/">http://repetae.net/john/</a> - author's homepage.</li></ul><p>There is also a public arch repository for ginsu at <a href="http://repetae.net/john/arch/2004/">http://repetae.net/john/arch/2004/</a><p>
</body>
</html>