README

     _  __     
 ___(_)/ _|___ 
/ __| | |_/ __|
\__ \ |  _\__ \
|___/_|_| |___/
               
GENERAL HELP FILE FOR SIFS


WHAT IS SIFS?

SIFS stands for:  shell "include file" system
An "include file" is a file you source into your current interactive shell
like so:
   % . some_file
You could also include it into a non-interactive shell, but be aware that some
commands defined within that file may be designed to expect user interactivity.
The SIFS system does the following:
1) facilitates the process of including files especially in interactive
   shells.  
2) is a set of conventions about how these included files should be structured
   and managed.
   We call the include files "sif files" and we store them in one or more
   sif repositories (a directory which is referred to by the shell 
   variable SIFS_DIR).
   You store your SIFS_DIR's in SIFS_CONF, a conf file.  Often, you'll
   only need one SIFS_DIR.
   A simple file sifs.sh in conjunction with sifs.conf acts as the glue
   allowing you to switch between sif repositories and between sif files
   in those repositories.
3) currently assumes you're running bash.

---------------------------------------------------------------------------
See the QUICKSTART file for setting SIFS up and basic commands.
---------------------------------------------------------------------------

SIFS is so simple you could easily implement it yourself.  To this extent,
this software is just expressing a simple idea but it is one that has helped
me to organize and handle more complexity in my daily jobs.

WHY SIFS? GENERAL PHILOSOPHY

The command-line is a powerful tool.
SIFS is meant for people who do a lot of things from the command-line usually
on linux or unix systems.
If you're a power user there are various things you can do to make your shell
more user friendly:
  - using ctrl+r to search on previous history commands
  - using vi or emacs mode to edit the current command and use the shell
  - using screen to handle multiple bash sessions, giving them titles
  - familiarity with an array of shell commands, builtin or gnu, posix stuff
SIFS assumes you're probably doing some, all or maybe a whole lot more of
that sort of thing.

The sifs system serves to
1) group related (often administrative) shell functions together which are run
   from the shell or command-line.  If you login and administer lots of machines
   each running their own sets of complex systems, this can be a boon.
2) make it easier and faster to run and remember commands and complex sequences of
   commands from the command-line; also to move around the file system from one 
   central location to another relatively easily
   (For instance you might implement a 'go' shell function in a sif file and have it
   take several options: go logs; go db; go; etc
3) document systems and procedures and locations (often administrative / sysadmin)
   or (more accurately) act as a central reference point where one can find 
   documentation, procedures, locations;
   and facilitate proper execution of processes by staff or yourself (in
   the case of a personal setup)
   You could embed checksheets or explanatory notes.  The existing functions and
   shell variables already document what you are doing to some degree and this
   is all tied together in a self-documenting help function that is accessed using
   the 'h' key.
4) Rapid editing/feedback; one of the sifs commands ('e') allows you to edit
   the currently loaded sif file.  I'll often suspend it in bash (ctrl-z) and
   then bring it up (fg) as I feel the need to update it.
   Type 'i' to re-include it into your shell.
5) SIFS implementation tries to keep it simple; apart from sourcing files,
   using several unix/linux command line functions and doing the occasional
   bash 'select' we aren't doing anything too clever (with the exception 
   of the "dot commands", that is ;) ).


NOTES / CONVENTIONS / GUIDING PRINCIPLES

0) The sifs system is a set of convenience functions and conventions.
   A sif file is a bash script file; by using .sif you are saying it is
   a particular type of shell file following some basic conventions.
   A sif file should be perfectly usable by simply sourcing it directly.
   % . /path/to/some_file.sif
   You should be able to source your sif file into a cron script without
   worrying about the sifs system
   In other words, it is no different to a bash script that you might
   have designed to be sourced.
1) Apart from variable setting and maybe some error checking code, sifs files
   shouldn't really execute anything when you source or run them
      % . some_file.sif     # No action
      % bash some_file.sif  # No action
   All the action is stored in function definitions and variables which are 
   loaded into your current shell (using the first form above).
   It generally only makes sense to source a sif either into a script or
   into your current shell.
   Notes:
   a) The 'c' command can take an argument (when being used non-interactively)
      which is an absolute path to the sif file
      % c /path/to/some_file.sif
      This command makes no assumptions about sifs system but will set
      SIFS_DIR. (This is useful if you use a scripted 'screen' setup
      where you want screen's windows to already be set to a SIFS_DIR).
      (When run without an argument, 'c' requires SIFS_DIR.)
2) I've sometimes been tempted to store data alongside a sif file.
   For instance, I might be logging changes I make to a system or a project
   and store these either in the sif file or as a .log file next to it.
   However, whilst it is possible to store non-sif files alongside your sif
   files, it is probably better to store all project data including slightly 
   meta-stuff like your progress with the project itself.  Use your sif file
   to point to it.
   This raises the question: shouldn't I also store my sif file with the
   project rather than in a centralised SIFS_DIR.
   The answer is: you can.  Just put a symbolic link of your sifs file in
   SIFS_DIR.


HOPPING BETWEEN LOCATIONS AND DOT COMMANDS

You can store (mark) your current location (pwd) by typing 
  m <char>
You can use one or more letters and numbers and underscores for <char>.
To cd back to this location, type
  g <char>
To view your marked locations type
  g
To jump back and forth between last location and current location
(where current location was accessed using 'g <char>)
  gg
.<char> and ,<char> can be used as shortcuts for the g and m keys
respectively (uses a feature that comes with debian/ubuntu bash
so it may not work on other bashes).

SIF FILE FORMAT

Every .sif file you create should follow a standard format.
I have my own rules, but you can of course just do your own if you like.

See SIFS_HOME/QUICKSTART
    % sifs.quickstart
See SIFS_HOME/docs/editing.txt
    % sifs.help
Run:
  % sifs.template 
and look at the output.

These are the conventions I use for my sifs files:
0) At the top of a sif file, set up your variables
   Set up a 'home' variable. eg
     MY_HOME=/usr/local/project1
   Set up other variables as needed. This depends on what you're doing.  It 
   should be fairly obvious what is worth stashing as a variable and what isn't eg
     LOGAREA=/usr/local/project1/var/log
     HTTP=localhost.project1:3003
     ...
   For the home or central directory of your project, you can either use HOME
   but beware that settings and dot files for your programs may be stored in
   the new HOME directory.
   Or, you can create your own home variable.  The sifs.template function
   assumes the latter and uses MY_HOME with a 'go' function.
     go() {
       case "$1" in
       *) cd $MY_HOME;;
       esac
     }
   NOTE: If you do use HOME, SIFS records the previous HOME as OLD_HOME which
   is reverted to when you type 'r'.
1) Next create an h()
   h() {
     less <<-EOF
     Project 1

     Functions:
     foo()
       - Runs foo
   EOF
   }
   I usually put the title of the project, and broad meta information in here
   as well as explanations for any key functions.
3) The rest of the sif file is pretty left for you to define your functions.
   For instance, see the go() function above.
4) Example sif file format.
   Run this:
   % sifs.template


RUNNING AUTOMATED SIFS SCRIPTS

Locate individual .sif files and just source them directly into your shell script.
   ...
   . /x/y/z/sifs/some_file.sif
   ...
   ...
Note: the job of SIFS_HOME/sifs.sh is to provide interactive assistance in
switching between sif files, something that is not needed for automated
processes.

SIFS AND SCREEN

If you want to load the sifs system up into screen, here is one way (note it
is the only way I've found so far, but it works well enough).

In your screen.conf have something like:

  ...
  setenv SCREEN_HOME /home/user

  chdir $SCREEN_HOME
  setenv SCREEN_SIFS /home/user/sifs/blogger.sif
  screen -t blogger  0 bash --init-file /home/user/screen.boot.sifs

  chdir /home/user
  screen -t title2  1
  ...

In  /home/user/screen.boot.sifs, have something like:

  . /home/danb/.bashrc
  c $SCREEN_SIFS
  cd

Then invoke screen:
  % screen -c screen.test

The first screen window should have a title 'blogger' and it
should have i) loaded the sifs system; ii) selected the blogger.sif
file.  The second window ('title2') will just be a normal shell.

Note, we ran bash with an init file; the init file source .bashrc
which makes it more like a login shell; this included the sifs 
system setup.  We then ran the 'c' function with an argument.


EXTENDING SIFS

1) Switching to another SIFS system
   Not implemented.  But to do it, you just need to change SIFS_HOME and then
   include SIFS_HOME/sifs.sh.  Run 'r' before you do this to reset your HOME to
   OLD_HOME.
   Really, sifs is very simple; you only need one system; to access new files,
   just update your sifs.conf.
   Several people could have different sifs systems with different sifs.conf's 
   both using public .sif repositories and private ones.

2) sif groups
   Instead of a large_project.sif file, you create 
   large_project.sif/
   and put several smaller .sif files within it.
   When you type 'c' to change to large_project you get to choose which
   of the several smaller files to include.
   large_project.sif/_* files might get included automatically when you
   change in.
   Not implemented.  Not sure this extra complexity is warranted.


-- DB, Sat Aug 22 20:19:17 EST 2009