                               hsh Introduction

Copyright (C) 2010 Alexander Taler (dissent@0--0.org)

This file is part of hsh.

hsh is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

hsh is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with hsh.  If not, see 
http://www.gnu.org/licenses/

    Overview
    --------

hsh is the {Happy|Human|History} shell.  It's a replacement for your
traditional shell (Bourne shell, C shell, etc.) intended to be more usable for
humans.  It is a curses apps, which means full screen interaction and a small
ugly palette of colours.  Currently it's at alpha level, and there are hundreds
more features that could be added.

The main purpose of hsh compared to a traditional shell is to make job output
easier to work with.  Each job's output is viewed and manipulated
independeantly.  This means, among other things, that you can incrementally
create pipelines, and that a rampant process can't trash all the output of your
session.  Other purposes for hsh are:

  Syntax designed for human use, not a programming language.
  Dynamic configurable interface making useful information accessible.
  Better job control and backgrounding features.
  Protection from terminal-trashing processes.
  Extensibility for new features.

This document is purely introductory, there is much more documentation in the
user manual and developer manual.

    hsh Usage Basics
    ----------------

The hsh interface is split into two main areas, the bottom few lines are for
input, and the rest of the screen is the main view, which can be switched
between multiple views.  Both areas can accept input, and the focus can be
moved from one to the other.  (Alt-o and Alt-Tab switch focus.)

Commands are typed into the input area and submitted for execution using the
enter key, as for a traditional shell.  The input area also displays
information about the command as it is being typed, to assist in preventing
errors.  When a command is submitted a job is created and displayed in the main
view.  The command-line syntax is inspired by that of the Bourne shell, but
shares only its most basic features.

On start-up the main view shows a welcome message with brief explanation of
keystrokes.  When a job is created, it will occupy the main view instead with a
job output view.  Additionally there are several job list views that can be
shown here.  (F1-F10 switch views.)

The job output view has a header area at the top with a blue background giving
information about the job, and the rest of the area below is for the job's
output.  When the job view has focus you can move it around using the arrow
keys as well as PageUp and PageDown keys.  hsh runs jobs in the background, and
does not wait for them to complete before showing output.  A job which isn't
terminated does not negatively affect the hsh interface.  Colours are used to
distinguish the job's stdout, stderr, and any interactive input.

Several job list views are also available: the session list has a history of
executed jobs and their output, from this session and previous ones; the
command history is a list of just command lines used, including those which
haven't been executed; and the running job list shows only jobs which are
actively running.  Jobs may be removed from the job list views in order to
reduce clutter.

    Feature Status
    --------------

hsh is still very new software, so there is a long list of to-be-implemented
features.  However, it is already usable and fairly stable in the features it
already provides.  The main important features of hsh are:

  Basic command-line features: globbing, env variables, tilde expansion.
  Ability to do manual interactive input.
  Switch to fullscreen mode for tolerant curses apps, notably vi.
  Use output from previous jobs as input for new jobs.
  Job backgrounding.
  Traditional shell fallback, either interactive or a single command.

A handful of the more important features to come are:

  No echo mode for entering passwords.
  Handling wider variety of terminal-interacting programs.  (/bin/sh doesn't
    show a prompt, gpg breaks the terminal, aptitude misbehaves, python refuses
    to go interactive, top refuses to run.)
  Handling of multi-line input commands.
  Environment modification with a dedicated view.
  Output search
  Dedicated view for contents of the current directory.
  Better configuration mechanisms.
  More movement commands.
  Execution context list and switching, like the directory stack.
  Directory naming feature like zsh.
  Directory list view, made visible via an ls builtin.
  "Remote" execution using ssh and sudo.
  Annotations on stored output: time, line num and ways to show the info.
  Support for non-ASCII character sets.

