TIPS for
SAM Kernel and Application
Updated 2023-09-19

Copyright (C) 2018, 2019, 2020, 2023 Joseph Rosevear

********************************************************************

230919 Joseph Rosevear This file is seriously out of date.  Much has
changed that has not yet been reflected in this file.  I will work on
it.

I removed the references to sam_env and patched the text to account for
the removed references.

I also have begun making corrections to this file, but I'm not done
yet.
********************************************************************

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.  This file introduces $sam_root, and it offers
some helpful tips regarding it and SAM.

$sam_root contains files that add/modify ways to start and run SAM. 
Although you could change, them for this purpose, please don't.  It is
better to create a Dual directory which contains copies or symlinks to
the executables and configuration files of $sam_root.

The idea is that you will make copies of the executables and
configuration files, rather that symlinks, in Dual for the things that
you wish to modify.  I will describe Dual directories better in another
place in the documentation.


1.  File $sam_root/begin contains some variable assignments that affect
the way SAM runs.  In particular:

   export sam_mark_num=1
   export sam_temp_base=/tmp/`whoami`
   export env_scratch=$sam_temp_base/scratch
   export sam_set_version=2

You can override these settings by making and editing a copy of
$sam_root/begin in a Dual directory, and you should use a Dual
directory.  However you should know that there is an alternative to
making a dual copy of begin.  That alternative is the use of a dual
copy of file bprofile.  Or, alternatively, you can prefix a definition
of variable bprofile when invoking begin.


Use 


if [ "$init" = "" ]; then

   export init=$sam_root/init
fi

if [ "$lib" = "" ]; then

   export lib=$sam_root/lib
fi

if [ "$bprofile" = "" ]; then

   export bprofile=$sam_root/bprofile
fi

export sam_mark_num=1
export sam_temp_base=/tmp/`whoami`
export env_scratch=$sam_temp_base/scratch
export sam_set_version=2

if [ "$bprofile" != "" ]; then

   . $bprofile
fi


1.1 $sam_root/bprofile

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

   sam_root
   sam_set_version
   sam_temp_base
   glos
   sam_distro

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


1.1.1 sam_root

Script begin sets sam_root to `dirname $0`.  This started has a
convenience, but may have evolved into a requirement.  Although you
could change this in a dual copy of begin, or override it in bprofile,
I don't recommend it.


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


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.

   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.)
