TIPS for
SAM Kernel and Application
Updated 2018-04-01

Copyright (C) 2018 Joseph Rosevear



This is the SAM TIPS file.  It, together with this directory are a
small, but important part of the SAM distribution, the balance of which
you will find at opt/SAM.  This file introduces this directory (which I
sometimes call the "b-files directory"), and it offers some helpful
tips regarding this directory and SAM.

This directory contains files that you can change/copy to add/modify
ways to start and run SAM.  *Please* when making the changes suggested
here, keep your old files, so you can revert to your previous setup if
desired.


1.  SAM now uses files $sam_root/bprofile and $sam_root/brc instead of
files ~/.bash_profile and ~/.bashrc.  Whereas the previous files both
ran at login, the new files run when you run $sam_root/begin.  Starter
files bash_profile and bashrc are provided here.

As with all the files in $sam_root you are the master; configure them
as needed.  However, you may want to preserve the orinal versions for
reference.  Also, please respect my copyright.


1.1 $sam_root/bprofile

The first of these, $sam_root/bashprofile, sets (or unsets) six
variables that are important to SAM.  These are

   sam_root
   sam_set_version
   sam_temp_base
   glos
   sam_env
   sam_distro

All but sam_env are essential to SAM, not to belittle sam_env. 
$sam_root/bprofile also contains other variables you may want to tailor
to your needs.


1.1.1 sam_root

sam_root is set automatically to `dirname $0`.  This is very
convenient, but not altogether necessary.  Setting sam_root in this way
allows SAM to be relocatable.


1.1.2 sam_set_version

Unless you are using a really old version of Slackware (before 10.0)
configure $sam_root/bprofile to export sam_set_version as "2".  This
variable is needed, because of a change that occurred in the way that
the "set" command formats its output.  SAM uses the output of the set
command to read the current variables and functions, but to do this
correctly it needs to know how the set command behaves.  The issue
regards the way that the set command formats its output when listing
functions.

Currently, there are two possible values for sam_set_version, as this
table shows:

sam_set_version  works in Slackware  GNU bash           behavior of set
---------------  ------------------  --------           ---------------

      1                7.1           bash-2.04           <function>=()

      2               10.0           bash-2.05b-i486-3   <function> ()

So, you must give sam_set_version a value of 1 or 2 and export it.  Note
that I do not know whether you should use 1 or 2 for the versions that went
between 7.1 and 10.0.  Also I cannot say what will happen if you use
versions before 7.1.  If you try any of these, would you please let me
know what happens?

To use a value of "2" for sam_set_version, put this in your
$sam_root/bprofile:

   export sam_set_version=2


1.1.3 sam_temp_base

Variable sam_temp_base identifies the directory in which SAM's temp
directories will be made.  SAM expects $sam_temp_base to exist and be
writable.  The file rc.SAM in this directory has code in it that makes
the directory (for each user of SAM) suitable for use as a
sam_temp_base directory, so you will probably want to use the one that
it makes.  $sam_root/bprofile sets sam_temp_base to /tmp/`whoami`, but
you can use any directory you want if it exists and you can write to
it.


1.1.4 glos

Variable glos is used by SAM to keep track of the portion of the string
in the PATH variable which contains the location of the operating
system.  The name "glos" comes from "GNU Linux Operating System".  The
variable glos is set by SAM in $sam_distro/go/sam to the current value
of PATH.  It is only set if it is found to be "".  This allows nested
invocations of SAM to work correctly.  (It is also exported.)

This requires, therefore that, glos be undefined before starting SAM. 
So that is why .bash_profile contains this code:

   unset glos


1.1.5 sam_env

The examples in /opt/SAM/example need the variables defined by
$sam_env/sam_env.  (This includes a variable called "env_scratch" which
some of the tools in this distribution use as a scratch directory.  You
may use it too.) A file sam_env is provided for you in $sam_root.


1.1.6 sam_distro

$sam_root/bprofile sets (and exports) sam_distro to $sam_root/opt/SAM.


1.2 $sam_root/brc

The second of these, $sam_root/brc, does one thing.

It makes the directories $sam_temp_base and $sam_temp_base/scratch
using this invocation

   mkdir --parents $sam_temp_base/scratch.

It does not replace script .bashrc despite the similarity of the names. 
(The name was actually chosen, because this script derives from
$sam_distro/tips/rc.SAM which is no longer favored.) In fact, there is
a suggested .bashrc file ($sam_root/bashrc) included in this distro. 

File $sam_root/bashrc contains some useful code that I found somewhere,
and it also contains an important bit of code regarding backspace.

I found that backspace didn't work from inside a running script in Slackware
12.0.  (I don't know if it is needed in subsequent releases of Slackware.) I
went looking for a solution and found it with help from my friends on
alt.os.linux.slackware.  So you may want to use it too.

If you want to use the included bashrc, you will need to copy it to
~/.bashrc.  Be careful not to clobber any existing .bashrc.


2.  I recommend that you start any gui that you wish to use before you start
SAM.  (There doesn't seem to be any good reason for doing it the other way
around.)

Once your gui is started you may want to run SAM from buttons or menus that
you have configured in your gui.

I use Fvwm2.  I run SAM, tin, and a SAM tool called "moan" (in audio in
the sam-example package) from Fvwm2 MiniButtons.  Here are the
invocations that I use:

vvv

*MiniButtons -   mini-happy.xpm       Exec    export sh_flag=sh; $HOME/begin

*MiniButtons -   mini-happy.xpm       Exec    export sh_flag=sh;
$HOME/breekit

*MiniButtons -   /mnt/sda6/usr/X11R6/include/X11/pixmaps/mini-news.xpm
Exec export sam_batch=batch; export sh_flag=sh; $HOME/begin "tin -nq -g
news.sunsite.dk"

*MiniButtons -   mini-cdlabel.xpm     Exec    export sam_batch=batch;
export sh_flag=sh; $HOME/begin "audio; k_moan"

^^^

These are from my .fvwm2rc file.  Note that in this file each invocation is
on a single line, as I don't know how to continue a line in Fvwm2.

The first of these sets sh_flag, to avoid the display of menus, and
then starts SAM in the usual way.  You will want to ensure that the
file $HOME/begin (normally the same as ~/begin) has in it what you
need.  See help below in this file.

The next one above does the same as above, except it uses breekit to
open a root shell in SAM.  Again pay attention to file breekit and see
the notes below.

The third runs tin (a news reader) from a SAM session.  This is done
because I like to use exed (in SAM's example package) as the editor for
tin.  Running tin from inside SAM makes exed available to tin.  There
are some other steps needed to use exed in tin.  I'll explain this
below.

The last of these runs moan, a simple audio CD player, by invoking
k_moan.  It also exects you to export a value for cd_dev.  You will
need to run "cdrecord -scanbus" to find the device name for your
CD-ROM.  File /opt/SAM/tips/bash_profile has code in it for defining
cd_dev, so you may want to use it.


2.1 How to use exed as the editor in tin

You need three things to do this.  See below.


2.1.1 You need to run tin from inside SAM

The code I gave above does this.


2.1.2 You need to "export EDITOR=exed"

This is easy to do from ~/.bash_profile. The file
/opt/SAM/tips/bash_profile already has this.


2.1.3 You need to change tin's tinrc file.

There is a file that you will likely find at ~/.tin/tinrc.  You can
edit it when tin is not running.  Find the line in it that says

   default_editor_format=%E +%N %F

and change it to

   default_editor_format=%E %F


3.  A customized mailcap file is included.  If you want to use it, copy
it to "~/.mailcap".
