new copy of Indhist on INDOLOGY fileserver

[Dominik Wujastyk]

Anand Raman's program Indhist, which was lodged at the INDOLOGY fileserver
recently was somehow truncated.  Anand has kindly provided a new copy,
and it has now been installed at Liverpool.
 
The original was a listpunched shar file; since this probably sounds a bit
arcane to many Indologists, I have repacked it as a ZIP file, which
is XXencoded.  This should be easier to deal with for most members.
 
Indhist is a Unix program which, when invoked, prints a random paragraph or
more of historical text on India, from a large database of such quotes.
 
Thanks, Anand!
 
I append the readme.1st file below, for those who wish to know more.
 
Dominik


 
# readme.1st, Introduction and Preliminary notes on Indhist
# anand v raman, 30 Aug 1992
 
                          Welcome to Indhist
                          ~~~~~~~~~~~~~~~~~~
 
                              DEDICATION
                              ~~~~~~~~~~
   I would like to dedicate Indhist to the memory of my grandfather,
         Sri S.K. Srinivasan, who kept his word and never died.
				
 
  The purpose  of Indhist is not  to glorify Indian heritage beyond
  recognition.  Nor is it  to  encourage a certain kind of arrogant
  chauvinism.  On the contrary, it is to show that the great Indian
  civilization, like the Chinese  and Ethiopian  before it,  was no
  more  profound a civilization than  any  other, and certainly not
  any more than the mighty European, but on the other hand, no less
			       either.
 
 
UNPACKING INDHIST
-----------------
 
When you unpack the shell archive, you should find the following
files in it:
 
0. Indhist1.0/readme.1st    : This file
1. Indhist1.0/readme.2nd    : Essay 1
2. Indhist1.0/readme.3rd    : Essay 2
 
3. Indhist1.0/INSTALL       : Makes the binaries, installs, etc.
4. Indhist1.0/Indhist       : Executable + Database
5. Indhist1.0/fifo          : Shell script for a named pipe
6. Indhist1.0/Indhist.8     : Indhist manual page
 
7. Indhist1.0/random.c      : C program to generate a random number
8. Indhist1.0/getopt.c      : C program to parse options to shell script
 
INSTALLATION NOTES:
-------------------
 
After  unpacking Indhist and  verifying its contents,   you are almost
ready to go.   If everything went well,  you should find  a  directory
called Indhist1.0   in  your current  directory.   Change    into that
directory and type  INSTALL   (all   upper case)  and answer  the  few
questions it asks you.  INSTALL will place  all the requisite binaries
in the right  places for you.  The manual page will  not be installed.
You must do that yourself.  (If you can handle shell scripts, it might
help to  look into INSTALL to  see if you  need to tailor  it a little
before you run it.  Strictly speaking this shouldn't be necessary.)
 
When INSTALL completes, you are ready to use Indhist or fifo.  You may
want to read the Manual page on them before you start.   If your pager
cannot detect nroff documents and automatically  invoke nroff for you,
you may have to type
 
nroff -man Indhist.8 | more
 
Also read the section in this document on troubleshooting  Indhist for
most of the common problems you could encounter.
 
HOW TO USE INDHIST AND FIFO
---------------------------
 
When Indhist is run, it prints a random record from  its database (See
the manual page on Indhist for  more details on  this).  In that sense
it functions somewhat  similar to the program  fortune (ucb).  You can
include  a call to  Indhist from  within  your  .login  script, so one
random record is printed out every  time you login or alternatively in
your .logout  so you can  read  it while  logging  out.  You  can even
include a call to Indhist in both .login and .logout if you love India
so much, but be careful not to be mistaken for a chauvinist.
 
Using fifo, you  can create named pipes on  the filesystem.  Then each
time the named  pipe is opened, it  delivers a new record.  Your named
pipe could be called .plan and placed in your home directory,  so each
time someone fingers you it prints a new record (Note that some finger
daemons are clever enough to  not look at  .plans that are fifos),  or
you could call  your  fifo .signature.   This is strongly discouraged.
Most mailers and  news posters  implicitly append this  file to  *any*
posting you make  so you could   end  up posting a note  about  Indian
history  to  soc.culture.brazil,   or     what's  even    worse,    to
comp.unix.wizards.
 
To save you flames, I'd suggest  you stay away  from calling your fifo
signature.   The default   name  for  the fifo is .signature.indhist.
This works just as  well and most editors  allow  you to include files
within  other files.  Since you  have  to  edit Mail and News articles
before posting them, it is just one small step to  append this file to
the end of your article before you send it off.  This way you even get
to  know which record you're tagging  on to your   signature.  Beware!
some records in Indhist are over  20 lines in  length, so if you let a
program handle the record insertion independently, you could be flamed
for posting a signature that is many times bigger than what you had to
say in  your article.   If this  doesn't suit you because  you usually
mail or post off the fly using cat |, then you probably don't care too
much for fellow net users anyway, so a few flames won't bother you.
 
I've  noticed that emacs seems  to   include 0  bytes   when  you  try
inserting a fifo into  your document.  This can  be bypassed, however.
You can run the Indhist or fifo command within  an inferior  shell and
include  its   contents into  the   emacs  buffer.  To do   this, type
M-x shell-command.  Then type in either one of:
 
Indhist
fifo
cat .signature.indhist    (if the fifo already exists)
 
Then you can  yank the contents  of the buffer  *Shell Command Output*
into  your current buffer.  The  emacs manual will tell  you how to do
that.
 
TROUBLESHOOTING:
----------------
 
1. Indhist
 
I'm assuming that you have sh(1) sed(1) and expr(1) which are all part
of a basic  UNIX  distribution  on  your system.   If  you don't, then
there's  no use  going any further,  Indhist simply won't run.  If you
do, there's no reason why  Indhist won't work.  However,  to be on the
safe side, maybe  you can check  the permissions on the script Indhist
and  whether Indhist  is in a   directory that is  part  of  your PATH
environment variable.
 
-   1.a) Indhist prints less than random records:
 
If you find that that the records that Indhist prints are more or less
sequentially selected from the  database, (In practice there's  no way
of finding  this  out  unless  you  keep  running  Indhist    in rapid
succession continuously, which is strongly  discouraged) then probably
the random command  must  be  failing for some  reason; the script has
been   using    expr(1) which yields less   than   random numbers.  It
shouldn't really matter as long as you abide by my suggestions and use
Indhist sparingly.  But  if you  want  really random  records and want
them soon after each  other, then you  must look  at  fixing the small
random binary, the details of which I won't go into here.
 
-   1.b) Indhist doesn't work unless the full path name is given:
 
Under UNIX System V, if you let the shell select Indhist from the PATH
and  run it from any  directory other than the  current one, it prints
the following two lines and exits:
 
Can't open Indhist
Can't open Indhist
 
This happens because /bin/sh under Sys V substitues $0  by the name of
the program being  run  without tacking on  the  path  to it.   So sed
complains about  not being able to open  Indhist which, of  course, is
not where $0  says   it is.  To fix  this,  you must edit  Indhist and
change `$0' in  the statement  db=$0  to be  the  actual pathname  for
Indhist.   For   example,  you  might    need  to  change    it  to be
db=$HOME/bin/Indhist.
 
2. fifo
 
Fifo is a slightly larger script  than  Indhist.  So  it is likely you
may encounter some   more problems  with  it.  For  a start, you  must
ensure  that you have the following  programs  if fifo  is to function
properly:
 
1. getopt       (also supplied with this package)
2. test
3. cat
4. mknod
5. true
6. echo
 
Now, if you don't have getopt on your system, you could compile up the
Public domain one which I picked up from  an anonymous ftp site and am
distributing with this package.  It is  by Rich Salz of Mirror Systems
(rs at mirror.tmc.com).  If you like, you may even write your own or pick
up one from your  favorite ftp site.   It should be compiled and  made
available  from  a directory in  your PATH.   If  you  used INSTALL to
install Indhist,  you shouldn't need  to worry  about this as  it will
ensure you have a working copy of getopt.
 
-   2.a) Catting fifo sometimes prints more than one record:
 
If  this happens,  then  edit the  file   fifo and uncomment the  line
containing the sleep near the very  end  of the script.  That will fix
it.
 
-   2.b) I've got my fifo set up, but catting it just seems to hang:
 
Remember that fifos  are almost the same as  pipes.  You cannot  write
into a fifo on one machine and try to read what  you  wrote on another
machine where the fifo is made available via NFS.  In order  to read a
fifo that had  just been written  into, you   must  have performed the
write on the same machine you are reading the fifo from.
 
If that's not why the cat hangs, then you must make sure  you have the
fifo process in  your background.  To  check this, type  ps -x.  On my
system the ps output looks like this:
 
  PID TT STAT   TIME COMMAND
 6717 p0 I      0:04 -tcsh (tcsh)
 6990 p0 S      0:00 sh fifo -df
 6995 p0 S      0:00 sh fifo -df
 7005 p0 R      0:00 ps -x
 
If you don't   see the two  lines  showing your  fifo processes,  then
they're probably dead, which explains why  your  named pipe is silent.
Maybe someone (a superuser) killed your daemon's when you were out, or
your .logout is setup  to automatically kill  all your  processes when
you log out. In any case you can get it going again by typing fifo -df
 
-   2.c) finger seems to ignore my .plan file set up to be a fifo
 
Finger(1) could ignore   the .plan file and  keep  printing "No plan."
under two  circumstances.  The first  is if your .plan is inaccessible
to the world.  Check  the permissions on the  .plan file and your home
directory.  "ls -ld . .plan" should print something like:
 
drwxr-x--x 26 ARaman       1536 Jun  2 18:09 .
prw-r--r--  1 ARaman          0 Jun  2 17:32 .plan
 
In most  cases, this can  be fixed by just setting  the  mode on these
files using chmod(1).  Try typing "chmod 751 ." and "chmod 644 .plan".
That  should fix  it.  If it  doesn't, then  it  is probable  that the
finger(1)  daemon on your system requires  .plan to be a regular file.
You can  check this out quickly by   creating a regular file  for your
plan with the same permissions as your  fifo and then running finger.
There's nothing much you can do if this is the case.
 
-   2.d) Inappropriate error messages are printed when fifo is run:
 
Sometimes, meaningless  error  messages have been   seen to occur when
running  fifo.    Most   commonly  these   are stty  complaints  about
unsupported  operations  etc.  Vijay Rangarajan  (vijay at ncsa.uiuc.edu)
has traced these  problems to  being  caused by /usr/ucb/which (called
near the very beginning of fifo) that sources your  ~/.cshrc file.  If
this happens, the fix he suggests is that  you move your stty settings
from your .cshrc file into your .login file.
 
-   2.e) fifo -d keeps printing `cat' error messages:
 
Remember that fifos don't get along too well with  NFS.  What's worse,
some cats don't return proper  exit statii to  their shells when their
writes  fail.  I know this  happens at least on  our  Pyramid.  So the
only way you can sometimes tell if fifo has gone bonkers is if you see
a recurrent message on your screen that goes
 
cat: output write error
 
 
 
 
when fifo is operating as a daemon.   This  only happens  if fifos are
not supported across your NFS and the directory you chose to keep your
fifo happens to  be NFS mounted from  some other hetergenous host.   I
haven't been able to fix this problem, but I managed to get  a  cat in
the pipeline so if something goes wrong, at least the cat will squeal.
The only  thing you can do  if this  happens is to get the  pid of the
fifo process and kill it.  You probably want to do this in a hurry, so
remember that ps(1) usually won't  show up daemon processes.  You must
specify the -x switch to  ps(1).  This means  you  can't run the fifo,
but you still have Indhist.  Alternatively, you could try  making your
fifo on a locally mounted disk.
 
Also,  I don't  detach the daemon from the  control tty.  I thought of
supplying another binary that  does  the ioctl call  to do  this,  but
realized it wasn't  worth the  trouble.  Most  of us   aren't  running
/bin/sh anyway, so keyboard   signals don't  get propagated  to  child
processes.
 
HOW TO GET THE MOST OUT OF INDHIST:
-----------------------------------
 
The following tips may be helpful in  prolonging the enjoyment you get
out of Indhist.
 
 * Please read the essays  distributed along with Indhist.   They reflect
   some  of the sentiments which have  directly gone into the  making  of
   Indhist.  However, remember that Indhist will still be useful  even if
   you don't agree with these essays.
 
 * Never print more than a few records a day.
 
 * Never open the data file and read its contents.
 
 * Don't use records from Indhist in your signatures for articles or mail
   not related to Indian culture.
 
 * Don't edit Indhist to doctor any of the records.
 
HOW TO CONTRIBUTE:
------------------
 
You can contribute to Indhist in various ways.  The first of these, of
course, is to popularize it among your Indian  friends, especially the
younger  ones who   have prematurely   lost   touch  with the   Indian
civilization, and get them to use it.
 
Also:
 
1)  You can help  add to the  existing database in Indhist.  Since I'm
volunteering to distribute  the package, you  can mail me the records,
and if the record  seems appropriate  enough  to go into the database,
I'll  make  sure it is  put   in and your  name  added to the  list of
contributors.   You  should  get  a  general   feel  of what  kind  of
historical  notes I hope  to  include in Indhist after  a few weeks of
using it.  Generally,    I place   a  greater   value  in   historical
observations  about  a  country by  a   person  not also of that  same
country.  This  is not  because they  may  be any more    objective or
accurate, but  because such observations are  usually easier to defend
against a charge  of `delusions of  grandeur.'   That is why I haven't
included any  observations  regarding India  from Basham, although his
book abounds with many of them.
 
2) You can help port the  program to environments it currently doesn't
run on.  You  can  perhaps  write a PC  version of Indhist, (I realize
that fifos cannot be implemented on the PC)
 
3) Arrange  for Indhist to be made  available  via anonymous ftp.  You
must provide me with  some publically readable  disk space I can write
the latest versions into.
 
4) Suggest improvements to Indhist and give me some feedback about it.
 
5) Notify me of any bugs you happen to discover in Indhist.  (It seems
in ancient India, if  a chemist should discover  a new poison, he will
be punished for it unless he also discovers an antidote. I won't be so
demanding.  I'll be happy if  you can just notify  me of the bugs, but
happier if you fix them and send me the fixes.)
 
6) Send little  notes  of appreciation to  the people  in  the list of
contributors when the  list has grown  longer, assuming of course, you
like certain aspects of Indhist.
 
LIST OF CONTRIBUTORS:
---------------------
 
Programs:
~~~~~~~~~
Indhist (Unix shell script)     anand v raman (A.Raman at massey.ac.nz)
fifo    (Unix shell script)     anand v raman (A.Raman at massey.ac.nz)
indhist (PC executable)         any takers?
indhist (VMS executable)        any takers?
getopt  (Unix binary)           Rich Salz (rs at mirror.tmc.com)
random  (Unix binary)           anand v raman (A.Raman at massey.ac.nz)
 
Essays:
~~~~~~~
        1) I really dread the day we Indians turn out to be like the Chinese
                - anand v raman (A.Raman at massey.ac.nz)
        2) The problem of the destitute East
                - anand v raman (A.Raman at massey.ac.nz)
 
Databases:
~~~~~~~~~~
Indhist (Indian History):
 
        Records 0-51 (McCrindle's translations)
           - anand v raman (A.Raman at massey.ac.nz)
 
Acknowledgements:
~~~~~~~~~~~~~~~~~
I would  like to extend  my sincere gratitude  to the following people
who volunteered  to test out Indhist  and its essays at various stages
of its development:
 
Vijay Rangarajan           (vijay at ncsa.uiuc.edu)
Sri Vidya                  (vidya at toru.isor.vuw.ac.nz)
Shankar Vaidya Nathan      (shankarv at microsoft.com)
Sree Kumar                 (kumar at csc.wcc.govt.nz)
 
Thanks are also due  to  everybody who  encouraged the  development of
this project.  My not mentioning them here individually is  solely due
to space restrictions  and   in   no way  belittles  their    valuable
contribution to Indhist.   I also  hope that  none  will  be the least
inclined to attribute the bugs  in Indhist to those whose  help I have
acknowledged.