home *** CD-ROM | disk | FTP | other *** search
/ The Fred Fish Collection 1.5 / ffcollection-1-5-1992-11.iso / ff_progs / miscutil / p-index2.lha / P-Index.doc < prev    next >
Encoding:
Text File  |  1992-10-12  |  12.1 KB  |  295 lines
  1. PRE1
  2.  
  3.                           P - I N D E X  V1.1 
  4.  
  5.  
  6.   INTRODUCTION 
  7.  
  8.     There are a great many index/selector programmes around, some of them very
  9.  good.  They all have one thing in common - they replace icons and drawers with
  10.  simple arrays of boxes listing the files or commands to be called by a click
  11.  within the box or on a gadget within the box.  No alternative types of display
  12.  are offerred.  
  13.  
  14.     With P-Index appearance of the index is limited only by your imagination -
  15.  or your paint programme.  Arrays of boxes (of varying shapes) can be produced,
  16.  pages of icons can be simulated, anything that can be drawn as a "brush" can
  17.  be used to index a file, decorations and text can be added. The "index" from
  18.  which you called this doc will give you some idea of the possibilities. Have
  19.  a look at Sample 1 and Sample 2 which index some System2.0 files in two
  20.  alternative ways.  The index is active but will only work for you if you have
  21.  the files and they are on the precise path set into the index. 
  22.  
  23.     Another problem with existing programmes is that almost without exception
  24.  they will not handle script files containing conditional commands ('if' etc);
  25.  P-Index copes. 
  26.  
  27.     Icons are notoriously wasteful of disk space, so if they are replaced by
  28.  identical-looking brushes in a P-Index index file (as in Sample1), which is
  29.  automatically compressed, there will be a very substantial saving.
  30.  
  31.    Below are some examples of P-Index 'lines':
  32.    #! 1 4 10 0 :P-Index/linetypes.brush
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.   This is only a demonstration - the lines are not active.
  49.  
  50.   In the framed box the red 'P-Index' would be a dummy, the green 'P-Index
  51.  could call the programme and the others display the doc and asm files.
  52.  
  53.     Indexes are built by the program Indexbuilder and used by P-Index.
  54.  Indexbuilder can be called from WorkBench or the cli (no arguments).
  55.  
  56.   OPERATION 
  57.  
  58.   Window Size.
  59.  
  60.     When Indexmaker is called a small requester will appear with string
  61.   gadgets for width and height, and a toggle for Lace.  The width and height
  62.   figures set the size of any index pages subsequently called.  The Lace settin
  63.   g only affects Indexmaker and is not transmitted with the index. Click OK to
  64.   open the main window at the first index page. 
  65.  
  66.  Menus
  67.  
  68.   The main window has four menus  - Project, New, Color and Show.
  69.  
  70.   Project - Load.   Used to load an existing index for modification.
  71.  
  72.           - Modify-Line.  Change (including delete) an existin line.
  73.           - Modify-Delete Page.  Remove a complete page from the index.
  74.  
  75.           - Save.   Save the whole index to a file.
  76.           - About.  Short notice about P-Suite.
  77.           - Quit.   Clicking the closewindow gadget also terminates.
  78.  
  79.  New      - Page.   Opens the next page.
  80.           - Line.   Called to add a new line to the current page.
  81.  
  82.  Color    - Color1
  83.           - Color2
  84.           - Color3
  85.           - Color4  Sets the page color.
  86.  
  87.  Show     - Comds   Show the cli calls made by each line.
  88.           - Names   Show the names allocated to each line.
  89.  
  90.   Page Gadget
  91.  
  92.    The current page number is shown in a small gadget at the top left of the
  93.   window.  When New-Page is called the number shown will advance.  To move to
  94.   an existing page delete the number shown, enter the page-number wanted, and
  95.   press return.
  96.  
  97.  
  98.  Page-making 
  99.  
  100.    Call New-Page if necessary.
  101.    Create the lines required.   These will show the line text initially.
  102.  
  103.    To view the associated cli commands, call Show-Comds.
  104.    To return to showing the line text, call Show-Names. 
  105.  
  106.    To check the operation of a line, call Show-Comds or Show_Comds, then click
  107.  (LMB) the line to be checked.  It may be necessary to move the window to the 
  108.  back to see the result.
  109.  
  110.  Line-making 
  111.  
  112.    Call New-Line.  A requester will come up.  Shown on the next page.  Against
  113.  Form are five gadgets:
  114.  
  115.    RECT   Produces a simple rectangular border for the text.
  116.    CIRC   Produces an oval border.
  117.    OCT    Produces a rectangle with the corners cut off (octagon).
  118.    BRUSH  Calls a brush created by a Paint programme.
  119.    BLOCK  Produces a solid block of color as background for the text.
  120.  
  121.  Click (RMB) on the form required.
  122.    #! 1 27 8 0 :P-Index/page.brush
  123.  WIDTH. Not used if BRUSH
  124.  has been selected. Enter
  125.  width for the box or
  126.  block (pixels) and press 
  127.  return.
  128.  
  129.  WIDTH. Not used if BRUSH
  130.  has been selected. Enter
  131.  height for the box or 
  132.  block (screen lines) and
  133.  press return.
  134.  
  135.  COLOR. Enter pen number
  136.  (1 to 4). If BLOCK has
  137.  been selected this sets
  138.  the color of the block,
  139.  and the programme will select a suitable contrasting color for text. For other
  140.  Forms this sets the text color.
  141.  
  142.  TEXT.  Except where a BRUSH is being used for the line, text entered here is
  143.  what will be seen  when the index is in use.   Maximum length of text is 79
  144.  characters.  For brushes enter the file reference of the brush - which should
  145.  incorporate any text needed. 
  146.   
  147.  COMMAND.  The command line or instruction to be run or executed when the line
  148.  is selected by a user.  See Command Lines below for details.  Maximum length
  149.  of line is 79 characters.
  150.  
  151.  Click OK to accept the line, CANCEL to reject it.  Note that the box "Delete
  152. line" is not active.   If OK is selected the line will be drawn (it may be 
  153. off screen and not visible at this stage);  position the mouse at the upper
  154. right corner of the line, or where you want the line to appear, hold down the
  155. RMB and drag the line to its required position.  On releasing the RMB the line 
  156. will be fixed and the BUILD LINE requester will reappear ready for the next. If
  157. If no more lines are needed click CANCEL.
  158.  
  159.    Further lines can be added at any time by calling the menu item New-Line,
  160.  and the detail and position of a line can be changed using Modify-Line.  
  161.  
  162.  Brushes:  By the use of brushes index pages can be turned into works of highly
  163.  useful art.  Icons can be simulated by converting the icon into a brush (itb
  164.  by Stephen Vermeulen is recommended), loading into a paint program and adding
  165.  text.  Brushes wholly created in a Paint program incorporating a program
  166.  name can be used for active lines.  Brush lines with the Command text line
  167.  left blank or carrying # (see below) can be used as decorations.
  168.  
  169.       To create the framed set of lines shown in the example on page 2, the
  170.  lines P-Index(red), P-Index(green), Doc and Index.asm would be made as RECTs
  171.  and positioned.  The frame and joining lines drawn as a brush would then be
  172.  added and placed over the other lines (Command text of this brush left blank. 
  173.  Trial and error needed since the last brush must cover and obscure the early
  174.  ones.  Once the brush has been positioned the text of the P-Index etc lines
  175.  will be seen and the area of the invisible boxes will be active. 
  176.      
  177.   Command Lines 
  178.  
  179.   In general command lines should be entered as they would be at a cli, eg:
  180.  
  181.   dh0:P-Writer to start the executable P-Writer. There is no need to "Run".
  182.   Execute df1:display_script to execute a script file "display_script".
  183.   dh0:P-Reader df1:P-Compress.doc to use P-Reader to display the text
  184.  P-Compress.doc.
  185.   dh1:LHArc x y z ram:out To start an executable with command-line options.
  186.  
  187.   Use full path-names - you may not be able to ensure that the user is in the
  188.  correct directory.
  189.  
  190.   It is common for a program to require several commands in sequence - aliases,
  191.  setting the current directory, increasing the stack, loading a handler and so
  192.  on.  The way to deal with this is to write a small batch file, eg:
  193.  
  194.    cd Lib.2:Brazilnut
  195.    Stack 10000
  196.    Crackit  (the actual file to be run).
  197.  
  198.  save it as "Lib.2:Brazilnut.script", and in the appropriate line of the index
  199.  enter:
  200.  
  201.    Execute Lib.2:Brazilnut.script
  202.  
  203.   There are three "specials":
  204.  
  205.   1. Command starts with an asterisk * followed by a space, followed optionally
  206.  by a normal command.  When selected a string gadget will come up showing the
  207.  command (if any).  This can be edited or replaced with a totally different
  208.  command which is executed when the user presses return.  The changed command
  209.  is not saved.
  210.  
  211.  2.  Command Page x (note space).  When selected, the current page is replaced
  212.  by Page x.
  213.  
  214.  3.  Command #.  The line will be ignored. and any overlapping lines selected
  215.  instead.   Use this where you want a background such as the tree in the index 
  216.  for this drawer, and enter this line first so that overlapping lines are
  217.  fully visible.
  218.  
  219.   All commands are basically executed from a cli and WorkBench-only programs
  220.  cannot be called.  Luckily there are very, very few WorkBench programs that
  221.  cannot also be called from a cli.  Difficulties can be experienced with cli
  222.  programs; for example Screensave which opens and then waits for RETURN to be
  223.  pressed.  It finds one in the command stream from P-Index and goes ahead too
  224.  early. The usual solution is a single line script file (see Screensave.script)
  225.  which allows the programme to operate correctly although you will get a 
  226.  "failed return code" warning of no significance.
  227.  
  228.  MODIFY 
  229.  
  230.   To delete a page, display it using the Page gadget in the top left corner 
  231.  and call the menu item Modify - Delete Page.
  232.  
  233.   To modify or delete a line,  display the page containing it and call the menu
  234.  item Modify - Line.  If you then click the line the Build Index requester will
  235.  come up showing the original line data.  Click Delete or modify as required,
  236.  not forgetting to press return after changing a string gadget entry.  Click 
  237.  OK or CANCEL and reposition the line with the mouse as before - this must be
  238.  done even if the required position is not changed.  
  239.  GENERAL 
  240.  
  241.   Remember not to make index pages larger than the user's WorkBench screen. 
  242.  Initially selecting LACE only affects Indexbuilder and the setting is not
  243.  passed on in the index file.
  244.  
  245.  
  246.   INSTRUCTIONS -  P-Index 
  247.  
  248.   The output of Indexbuilder is a compressed index file or files.  P-Index is
  249.  used to display and operate the index.  It may be started from WorkBench, a
  250.  startup-sequence, or a cli.
  251.  
  252.   WorkBench:  Create a PROJECT icon for the index and call P-Index as the 
  253.  default tool.
  254.  
  255.   Startup:  If you are using System2.0 enter tooltype DONOTWAIT in the index
  256.  icon and drag it into the WBstartup drawer.  The drawer containing P-Index
  257.  should be in your current Path.  s:startup-sequence must open WorkBench since 
  258.  P-Index displays in the WorkBench screen.  Alternatively (and for System 1.3) 
  259.  include the call P-Index [file] in the startup-sequence - use Runback or the
  260.  equivalent if you wish.
  261.  
  262.   CLI: Call P-Index [file] or Run P-Index [file].
  263.  
  264.   When calling from the CLI note that if full pathnames (including drive) were
  265.  not used in making the index - sometimes unavoidable - it is necessary first
  266.  to CD to the disk containing P-Index . 
  267.  
  268.  
  269.        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  270.  
  271.     Indexmaker and P-Index are Freeware.  They may be copied and distributed  freely and used without charge for non_commercial purposes.  Authority for
  272.   commercial use should be obtained from the author below.
  273.  
  274.     No responsibility can be accepted for any loss occasioned by use of these
  275.   programmes.
  276.  
  277.     Comments, suggestions, bug-reports all welcome.
  278.    Chas A. Wyndham,
  279.    1265 Canning Mills Road,
  280.    Roleystone,
  281.    WA 6111.
  282.    Australia 
  283.  
  284.  
  285.  
  286.  
  287.  
  288.  
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.