                               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 areas, the bottom few lines are for input,
and the rest of the screen is the main area, which shows one of a number of
different 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, just like 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
area.  The command-line syntax is inspired by that of the Bourne shell, but
shares only its most basic features.

On start-up the main area shows a welcome message with brief explanation of
keystrokes.  When a job is created, the main area will switch to show the job's
output.  The Fn keys can be used to switch the view shown in the main area,
between the job output view and several available job list views.

The job 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.  While a job is running the user may
interact with hsh as usual, starting new jobs or examining output.  The running
job's output will be shown in its output view as it arrives.  Colours are used
in the job output view to distinguish the job's stdout, stderr, and any
interactive input.

Several job list views are also available: the session list includes all jobs
running in this session; the command history is a list of just command lines
used, including those which haven't been executed; the running job list shows
only jobs which are actively running; and the job history view includes all
jobs from this and other session.  The user can remove jobs from list views.

    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.
  Support for fullscreen terminal apps including curses apps.
  Use output from previous jobs as input for new jobs.
  Job backgrounding.
  Ability to modify the environment.
  Command aliases.
  Traditional shell fallback, either interactive or a single command.

Features slated for the next release are:

  Session list which includes job output, to become the default view, in order
  to provide a more familiar experience for users coming from other shells.
  More obvious cues that a job is running or not.
  More movement keys - including word movement.
  Output search
  Execution context list and switching, like the directory stack.
  Deleting jobs won't delete command history.  Jobs from other instances won't
  be (easily?) deletable (unless they are old?)  True session list vs. full job
  history list.

A handful of the more important features for future releases:

  Workspaces - a way to group related command history items, jobs, and
  execution contexts which are used together.
  No echo mode for entering passwords.
  Handling of multi-line input commands.
  Better configuration mechanisms.
  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.

