TIPS for
SAM Kernel and Application
Updated 2020-03-22

Copyright (C) 2018, 2019, 2020 Joseph Rosevear



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

$sam_root 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 bprofile and brc are provided here.

Files bprofile and brc do not replace ~/bash_profile or~/.bashrc, so
you should still use them as would would normally*.  The similarity in
names shows the evolution of the the files, but is meaningless
otherwise.  Currently brc does onely one thing, but for now I'm keeping
it.  bprofile does a number of things.  There is more information about
files brc and bprofile below.

As with all the files in $sam_root you are the master; configure them
as needed.

   * I recommend that you put this in your .bashrc:

      echo "in $BASH_SOURCE"

      stty erase `tput kbs`

   and nothing else.  This is, actually where you would traditionally
   put your aliases, but I had a bit of trouble with them so I quit
   using aliases.  I'm not sure what the trouble was.  My notes say it
   was because an alias is not inherited by a new shell.  Hmmm.

   When using SAM you don't need aliases, because you can write new
   commands instead.  See my command "_ls" in the menu for
   $sam_root/example/handy.

   The "stty erase" line fixes a problem that would occur otherwise
   (nothing to do with aliases): Backspace would not work correctly
   when typing a response to read command invoked by a script.  Again
   Hmmmm.


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.  (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.aioe.org"

*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.  There are other files in $sam_root not mentioned above.  Here I'll
list all the files of $sam_root.

   COPYING:

      A statement of the license for this distribution.

   ENV-NOTE:

      A file in this dir which descdribes the configuring of SAM
      through the use of environment variables.

   GUIDE:

      A guide for the use (or application) of SAM.

   README:

      Release notes.

   TIPS:

      This file.

   bclean:

      A b-file in this dir.  It supports bree.

   begin:

      A b-file in this dir.  See above and GUIDE.

   bprofile:

      A cnfiguration b-file used by the b-files (not bree).  See above
      and GUIDE.

   brc:

      A configuration b-file usede by the b-files (not bree).  See above
      and GUIDE.

   bree:

      A b-file in this dir.  See GUIDE.

   breekit:

      A b-file in this dir.  See above and GUIDE.

   bstart

      A special b-files.  See GUIDE.

   buser:

      This b-file is an alternative to begin.  Use it from inside an
      xterm.  Supply a username or "root" for $1, then login.  Next, in
      the xterm that opens, start SAM using "begin" or similar.  This
      allows you to run SAM as a different user when in X.

      Note that this is not the same as what you get by using bxauth
      and bxadd.  buser is faster and can do at least one thing that
      bxauth and bxadd cannot do.  Namely, it partners with the command
      "dog" of menu $env_handy to run a web browser in a special way. 
      Otherwise it is noticeably lacking, as you cannot use it to run X
      applications.

   bxadd:

      Goes with bxauth.

   bxauth:

      This b-file is handy for giving permission to a different user to
      use you X authority.

   changlog.txt:

      This is the change log for $sam_root.

   config:

      This is a handy starter file (which I actually use).

   mailcap

      This is a customized mailcap file.  If you want to use it, copy
      it to "~/.mailcap".  (Note that I haven't use this file for many
      years.)

   opt

      This dir contains the following sub-dirs:

      SAM:

         A symbolic link to SAM_modules/main.

      SAM_modules:

         This is the SAM distribution.

      f_lib:

         This dir contains file script_tools which is used by some SAM
         commands.

   sam-start

      (See above.)

   sam_env

      (See above.)
