@database "PSB Documentation"
@author "Stefano P.R. Peruzzi"
@(c) "Copyright © 1996 S.Peruzzi"
@$VER: PSB Documentation 1.0 (23-Mar-96)

@node main "Welcome to PSB"
@font helvetica.font 11

        @{b} PSB - PROSITE DATABASE BROWSER  V 1.00 @{ub}


        @{b}1.  INTRODUCTION @{ub}

             1.1  @{" Short description " link description}...........................................................What is PSB ?
             1.2  @{" System Requirements " link requirements}..................................What you need to run PSB
             1.3  @{" Features list " link features}..................................................Complete PSB feature list
             1.4  @{" Greetings " link greetings}.....................................................Greetings from the author

        @{b}2.  INSTALLATION @{ub}

             2.1  @{" Installing PSB " link install}.........................................................How to install PSB

        @{b}3.  USER GUIDE @{ub}

             3.1  @{" User Interface " link gui}.................................................GUI complete reference
             3.2  @{" ARexx Interface " link rexx}........................................Controlling PSB via ARexx
             3.3  @{" PROSITE Database " link prosite}...................................What is PROSITE database?

        @{b}4.  TECHNICAL GUIDE @{ub}

             4.1  @{" Inside PSB " link tech}...................................................................Technical details
             4.2  @{" History " link history}...............................................................Version & revision list
             4.3  @{" Bugs " link bugs}...............................................................................Bug reporting

        @{b}5.  DISTRIBUTION @{ub}

             5.1  @{" Copyright " link copyright}...................................................................Copyright notice
             5.2  @{" Licence " link licence}....................................................................Distribution licence
             5.3  @{" Disclaimer " link disclaimer}......................................................................Legal disclaimer
         



@endnode

@node description "Short Description"
@font helvetica.font 11
@{b} Short Description @{ub}

 PSB (PROSITE BROWSER) is the first Amiga browser for PROSITE database.
 In few words it helps browsing and scanning a useful 2Mb database
 available at the University of Geneva. PSB at the present time only
 allows browsing PROSITE.doc but in the future it will be completed by
 a protein sequence analysis package that will make use of PROSITE.dat,
 and that possibly will include many other features.

 PSB for now is intended for students & others that need a fast reference
 on any protein family, core-pattern and related stuff.
 While studying I often use PSB to check if there is something I don't know
 about certain receptors or proteins.

 In order to use PSB you need PROSITE.DOC, available on AMINET too.

 I really don't know how many people need such tools on Amiga but if
 so many molecular biology & physics tools are yet present for Mac & PC
 I really wonder why not so for Amiga (given such a powerful O.S.).

 I really need a feedback from students and biomol/biophys guys that
 think I am on the right way.  :-)
 So e-mail comments & suggestions to @{b}peru@maya.dei.unipd.it@{ub}




@endnode

@node requirements "System Requirements"
@font helvetica.font 11
@{b} System Requirements @{ub}

 PSB need MUI 3.x, Amiga O.S. 3.x, and about 500Kb of memory for
 internal lists and buffers. Searching buffers may require
 additional 10-400Kb.

 MUI 3.x can be found on every AMINET site, CD, and many BBS.

 PROSITE.doc can be found on AMINET or at http://expasy.hcuge.ch

@endnode

@node features "Features List"
@font helvetica.font 11
@{b} Features List @{ub}

 o Fully multitasking.
 o MUI fully configurable user interface
 o On line bubble help.
 o PDOC loading by name or PDOC access number.
 o Simply and fast browsing gadgets.
 o Easy saving and printing of current entry.
 o Fast scan of whole database for pattern matching.
 o Internal buffer for matched entries.
 o Information text on aminoacids & nucleotides code.
 o ARexx port for power users.
 o CX exchange broker for better control.


@endnode

@node greetings "Greetings"
@font helvetica.font 11
@{b} Greetings @{ub}

 Thanx to @{b}Amos Bairoch@{ub} for his great idea: PROSITE!

 Many thanx to @{b}Stefan Stuntz@{ub} for MUI, buy it, it does really
 worth the price! I coded other GUI's using intuition,
 gadtools and BOOPSI but are all nothing respect to MUI
 easy of use and configurability, best feature is surely
 the auto-layer-rescaling and positioning so easy to use
 that I changed completely my GUI after 85% of PSB was
 done and this just in few minutes !!! :)

 Thanks to my friends:

 @{b}Andsk (Andrea Rafreider)@{ub} that has written the installer script
 and that constantly updates my internet A4000 setup.

 @{b}Amex (Amedeo Petrella)@{ub} and @{b}Ire (Ireneo Toffano)@{ub} that debugged PSB
 and suggested improvements for future releases.

 @{b}Zanna (Claudio Zanella)@{ub} that we usually meet at his AmiProBBS
 for Pizza&Amiga parties.

 PS) Call AmiProBBS! Gb of Amiga files on line, every AMINET CD
     and much other stuff:

     @{b}AmiProBBS@{ub} 24/24h Zyxel Elite 28.8K
     BBS +39-49-604488  Voice +39-49-8641713


 @{b}AUTHOR:@{ub}
 Stefano P.R. Peruzzi
 peru@maya.dei.unipd.it
 University of Padua - ITALY

 Universa Universis Patavina Libertas


@endnode

@node install "Installing PSB"
@font helvetica.font 11
@{b} Installing PSB @{ub}

 Installation is very simple thanks to Amiga Technologies official
 installer. Simply run the installer script and follow on line
 requests and instructions.

 If you want do it manually then follow these steps:

 - Copy PSB drawer where you want in your hard disk.
 - Open a shell and ASSIGN PSB: to the PSB-drawer.
 - Add to your S:User-Startup file "ASSIGN PSB: PSB-drawer" entry.

@endnode


@node start "Getting Started"
@endnode

@node gui "User Interface"
@font helvetica.font 11
@{b} User Interface @{ub}

 @{b}Gadgets@{ub}

    @{b}Help@{ub} leaving the mouse pointer resting on any GUI gadget will
    popup a bubble help text.

    @{b}PDOC@{ub} shows current PDOC access number and allows changing
    and loading another document just clicking and moving a popup slider.

    @{b}Entry text@{ub} shows the complete title of currently selected entry.

    @{b}Entry popup@{ub} allows selection of any entry by title.

    @{b}Info@{ub} toggles a information text on IUPAC codes for aminoacids
    and nucleotides and a detailed reference on PROSITE pattern syntax.

    @{b}Save@{ub} saves the current entry with current title as filename in
    "PSB:" directory. A file with the same name is always overwritten.

    @{b}Save As@{ub} pops up an ASL requester and saves the current entry
    with given name in chosen directory.

    @{b}Print@{ub} prints the current entry on preferences printer, if
    printer is not on line, PSB will sleep until printer device reply
    with an OKAY/CANCEL message, please wait for printer device requester.

    @{b}First@{ub}, @{b}Last@{ub} and @{b}arrows@{ub} load respectively
    the first or the last entry or step forward and backward through
    database entries.

    @{b}Search@{ub} scans whole database looking for selected string.
    In this version search is case sensitive. Every hit will be buffered
    in a special list. The list is cleared before any new scansion.

    @{b}Search string@{ub} inputs a pattern to search for.

    @{b}Buffer text@{ub} shows the complete title of currently selected
    buffer entry.

    @{b}Buffer popup@{ub} allows selection of search buffer entries by title.

    @{b}Buffer arrows@{ub} step backward and forward through buffer entries.
    
    @{b}Text window@{ub} shows currently selected document, text is scrollable.



 @{b}Menus@{ub}

    @{b}About@{ub} Information on version of PSB, author and ARexx port.

    @{b}Save, Save As, Print@{ub} see gadgets.

    @{b}Iconify@{ub} Iconify application. This action is possible also via
    CX exchanger utility and MUI popup menu.

    @{b}Quit@{ub} Exits PSB.


@endnode

@node rexx "ARexx Interface"
@font helvetica.font 11
@{b} ARexx Interface @{ub}

 PSB include an ARexx interface. Port name consists of basename
 plus an index number. This allows multiple PSB windows to work
 in multitasking without sharing the same public message port
 for ARexx messages exchange.

 The first time PSB is run the public port name will be "PSB.1",
 but you can check the current ARexx port name just selecting
 "About PSB" menu item.

 At the present time PSB V1.00 provides only 1 ARexx command,
 in future versions and revisions all other GUI actions will
 be implemented and more.


@{b} ARexx Commands@{ub}

@{b} QUIT@{ub} Simply exits PSB without any requester.


@endnode

@node prosite "PROSITE Database"
@font helvetica.font 11
@{b} PROSITE database @{ub}

 PROSITE database consists mainly of two files, "PROSITE.doc" and
 "PROSITE.dat". These files form a complete dictionary of protein
 sites and patterns assembled by Amos Bairoch at the Medical
 Biochemistry Department of Geneva University.
 The database helps determining what is the probable function of
 uncharacterized proteins translated  from genomic  or cDNA  sequences.
 It  consists  of  a database of biologically significant sites and
 patterns formulated in such a way  that with  appropriate
 computational  tools  it  can  rapidly  and reliably identify  to
 which  known family  of protein  (if  any)  the  new sequence belongs.
 While "PROSITE.dat" is to be considered the real database,
 "PROSITE.doc" is useful complement to the former and could be really
 considered a protein families database.

 For detailed informations on PROSITE and for database updates contact
@{b} http://expasy.hcuge.ch@{ub}.

@endnode

@node tech "Inside PSB"
@font helvetica.font 11
@{b} Inside PSB @{ub}

 @{b}PSB@{ub} has been developed with A4000 platform, SAS 6.56, MUI 3.3
 GoldED and many other tools that runs in multitasking and that
 makes great Amiga and Amiga O.S.

 PSB makes use of memory pools method in order to avoid memory
 fragmentation. No memory loss or enforcer hit has been detected.

 PSB on startup tries to load "PSB:PROSITE.doc" and if not present
 quits and releases resources. Then it looks for "PSB:psb.idx" where
 there is stored every information PSB need to retrieve PDOCS.
 If the index file is not present, PSB creates a new one and saves
 into "PSB:" directory.
 When updating "PROSITE.doc", index need to be rebuilt to be
 consistent with new informations and offsets; were it the case,
 it is simply sufficient to delete the old "PSB.idx" file and let
 PSB create a new one.

 Due to the length of "PROSITE.doc" database (nearly 2Mb at the
 present time but bigger and bigger in the future) and to the
 memory constraints of average user (see students), PSB explicitly
 avoids loading whole database in memory, it just loads an index
 and builds up an internal exec bidirectional list with pointers
 to the real disk based database. This method allows loading
 an entry only when required and wasting only few Kb for loading
 buffer.

 For database search the question is different: an entry by entry
 load and scan routine is a time lengthy process. For this
 reason PSB tries and allocates some 400Kb fast memory and, in
 case of failure, tries again with 200Kb, 50Kb, 10Kb buffers
 respectively. A vanilla A1200 not overloaded should have no
 problems at all. The bigger the buffer PSB is able to allocate,
 the faster the buffer scanning will be.


@endnode

@node history "History"
@font helvetica.font 11
@{b} History@{ub}

 @{b}V1.00 (25.03.96)@{ub}
  o First AMINET release.

@endnode

@node bugs "Bugs"
@font helvetica.font 11
@{b} Bugs & bug reporting @{ub}

 For bug reporting, be sure that bug is reproducible at given
 conditions. Report the exact configuration of your platform, the
 version of PSB used and of AOS (Amiga O.S.) and the circumstances
 that trigger the buggy behaviour.
 Some strange behaviour may be due to MUI library and, were it the
 case, it could be present in other MUI applications.

 Bugs could be reported via postal service or (much better)
 via e-mail to the following address:

@{b}    Stefano Peruzzi
    Via S. Dall'Arzere, 23
    I-35138 Padova - ITALY
    peru@maya.dei.unipd.it @{ub}


@{b} Possible bugs & other stuff@{ub}

 * Window area damages due to ASL or system requesters are fixed
   using "smart refresh" for PSB in MUI settings.
   Also window position automatic snapshot, iconification and all
   graphical user interface parameters are fully configurable by
   user with MUI preferences program.

 * Printing current document without printer on line puts application
   to sleep for while, it could seem a deadlock condition but it
   is sufficient to wait for the proper requester from printer device.

 * Using MCP multi-commodity with SaveGIRPort option, could severely
   slow down PSB video refresh, causing the gadget imagery to be
   damaged when moving the sliders or using the popup gadget.

 * After first time you entered (by clicking) the string gadget,
   the string gadget itself activates whenever the PSB window gets
   the active one or after de-iconification.
   This behaviour does not seem related to any cx or patch present,
   because it persists on vanilla A4000 and A1200 with MUI 3.3, and
   it is present in all other MUI 3.3 applications.


@endnode

@node copyright "Copyright"
@font helvetica.font 11
@{b} Copyright @{ub}

  @{b}PSB © Copyright 1996 by Stefano P.R. Peruzzi. All rights reserved.@{ub}

  This software has been entirely developed by the author who
  owns all rights on his product. The author is free to change
  the copyright conditions at any moment.

@endnode

@node licence "Licence"
@font helvetica.font 11
@{b} Licence @{ub}

  PSB is freely distributable provided that no more than a nominal
  fee is charged to cover costs of media or network transmission and
  that the PSB distribution archive is kept intact.
  PSB could be included in any CD, BBS, Internet and Aminet site.

@endnode

@node disclaimer "Disclaimer"
@font helvetica.font 11
@{b} Disclaimer @{ub}

 Author makes no warranties, either expressed or implied, or
 representations with respect to the software or the informations
 included in this distribution archive.
 Software and informations are provided on an "as is" basis and is
 expressly subject to change without notice by the author.
 In no event will the author be liable for any direct, indirect,
 incidental, or consequential damages resulting from any claim
 arising from using the software or out of the information herein
 included.

@endnode