*****************************************************************************
For the impatient amongst you here is how to get
show-function-prototypes() up and running:

NOTE: You should be running the x-sb-mouse package written by
      Sullivan Beck.  If you prefer to use from a key-binding
      rather than from a mouse press then look in show-proto.el.

1.  Look through the makefile and change anything you deem necessary.
    On a Sun nothing should need changing unless you want some of the
    other sections from man3 included (by default only .3, .3m, .3s 
    and .3v are done).

2.  Type make.  This will make the scan and nuke-bs programs, and
    should then go ahead and create the database of prototypes.

3.  Insert the following in your .emacs file:

    (load-file "~/emacs/show-proto.el")       ; or wherever you have put it.
    (setq proto-database "~/proto-database")  ; or wherever you have
                                              ; put this file as well.

    And either:

    (x-mouse-define-key "x-mouse-m1-window-click"  ; or whatever button 
             t 'default 'show-function-prototypes) ; you want to use instead.

    or for keyboard use:

    (define-key  global-map  "\C-c\C-p"  'show-function-prototypes)

You should now be all set up to use show-function-prototypes().

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

What it does.

This function was  inspired by the  Unipress version of  Emacs which  had  it
implemented  as  standard.   (At  least, the  version  I   used did).  When I
switched to GNU  Emacs I decided it  would be nice to  still  have this nifty
function.

show-function-prototypes()   is  something which  I  find  quite useful.  I'm
always forgetting  which order the  arguments for functions  like fputc() and
sprintf() are specified.  What this function does  is  to pop up  a  one line
prototype in the minibuffer area of whatever  function  you click on with the
mouse.  i.e.

char *sprintf (s, format [ , arg... ] )

In order for it to do this it has  to have access to a  database of these one
line prototypes.  This database can be built by a bit of lex code which scans
through manual entries looking for a line with  just SYNOPSIS on it.  It then
extracts all function definitions from the following lines until it gets to a
line  with either DESCRIPTION  or SYSTEM V SYNOPSIS  on  it.
i.e.  for man 2 chown the man page looks like:

NAME
     chown, fchown - change owner and group of a file
 
SYNOPSIS
     int chown(path, owner, group)
     char *path;
     int owner;
     int group;
 
     int fchown(fd, owner, group)
     int fd;
     int owner;
     int group;
 
SYSTEM V SYNOPSIS
     #include <sys/types.h>
     int chown(path, owner, group)
     char *path;
     uid_t owner;
     gid_t group;
 
DESCRIPTION
     The file that is named by path or referenced by fd  has  its
     owner  and  group changed as specified.  Only the super-user
     may change the owner of the file, because if users were able
     to  give  files  away,  they  could  defeat  the  file-space
     accounting procedures (see NOTES). The owner of the file may
     change  the  group  to a group of which he is a member.  The
     super-user may change the group arbitrarily.

and scan would output:

int chown (path, owner, group)
int fchown (fd, owner, group)


USING ON MACHINES OTHER THAN SUN WORKSTATIONS

Obviously, in order for all this to work automatically your man pages must be
formatted as in the example above. The makefile uses nroff  to format the raw
manual pages into ascii  which is  then passed  to the nuke-bs  program which
removes all the garbage \b  sequences that nroff may  have left lying around.
It's output is then fed to the scan program.  On  Sun workstations this works
fine.  It also worked OK on the Hewlett Packard that I tried it on.

The makefile does have support for compressed man pages  (like on the  HP) or
uncompressed  (like  on our  Suns).   It  also lets   you   choose  which man
directories you want to search and which extensions you would like scanned.

If the format of your man pages differs too much then you may have  to change
the search criteria  in  scan.l.  This  shouldn't  be too  difficult  to  get
running on any machine.  Alternatively,  if you get  realy stuck I can  email
you a copy of my prototype database.


Please send any comments, suggestions or bug fixes to glenn@prl.philips.co.uk.
