home *** CD-ROM | disk | FTP | other *** search
/ ProfitPress Mega CDROM2 …eeware (MSDOS)(1992)(Eng) / ProfitPress-MegaCDROM2.B6I / PROG / MISC / PAGER2.ZIP / PAGER2.DOC next >
Encoding:
Text File  |  1989-06-17  |  14.3 KB  |  482 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.                                      PAGER2
  7.  
  8.                                 by Richard Conn
  9.  
  10.                   PAGER2 is   a  tool  for  creating  paged  files,
  11.              extracting  the component files from a paged file, and
  12.              scanning  paged  files,   where   a  paged  file  is a
  13.              file  composed  of  one  or  more  files  prefixed  by
  14.              banners.    PAGER2   is  based  in  concept   on   the
  15.              UNPAGE   tool submitted to the Ada Software Repository
  16.              on SIMTEL20 by Mitre Corporation.  
  17.  
  18.                   Paged files   are   convenient   mechanisms   for
  19.              storing  related   files.   They   reduce   cluttering
  20.              in   the  directories  and  simplify the file transfer
  21.              process  by requiring  the  user  to transfer only one
  22.              file  in  order  to  obtain  all  files pertinent to a
  23.              particular  project  or  tool.   Additionally,   paged
  24.              files   are  text  files  which  can  be  handled more
  25.              readily  than  the 8-bit binary images associated with
  26.              other   file   grouping   mechanisms  (see   the  file
  27.              OILBR.DOC     in   the   directory   PD2:<ADA.GENERAL>
  28.              in   the   Ada  Software Repository).  Paged files may
  29.              be  manipulated  by  a  text  editor  if necessary.  
  30.  
  31.                   For these   reasons,   paged   files   have  been
  32.              adopted   as   a   standard  for  file  storage in the
  33.              Ada  Software Repository.  The file type of SRC (as in
  34.              MYFILE.SRC) indicates that a file is paged.  
  35.  
  36.  
  37.  
  38.  
  39.           1.  PAGED FILE FORMAT 
  40.  
  41.                A paged  file  is  a file composed of one or more files
  42.           prefixed  by banners of the form: 
  43.  
  44.                           ::::::::::
  45.                           filename
  46.                           ::::::::::
  47.           or
  48.                           --::::::::::
  49.                           --filename
  50.                           --::::::::::
  51.  
  52.                The first   banner   conforms   to  the  PAGE  standard
  53.           employed  on  UNIX.  The  second  banner is an adaptation of
  54.           the  first  form  which  resembles Ada comments.  The second
  55.           banner  is  convenient   when   the   paged   file  contains
  56.           several   files   associated  with  a particular Ada program
  57.           and  they  are  placed  in  the  paged  file  in compilation
  58.  
  59.  
  60.           Richard Conn                                          Page 1
  61.  
  62.  
  63.                                      PAGER2
  64.  
  65.  
  66.           order.   The  resulting  paged  file  may  then  be compiled
  67.           without being disassembled first.  
  68.  
  69.  
  70.  
  71.  
  72.           2.  PAGER2 COMMANDS 
  73.  
  74.                PAGER2 responds to the following commands: 
  75.  
  76.                 1.  PAGE or P - create a paged file 
  77.  
  78.                 2.  UNPAGE  or U - extract the components of a
  79.                   paged file into their separate files 
  80.  
  81.                 3.  LIST  or  L  -  list components of a paged
  82.                   file to the screen 
  83.  
  84.                 4.  INCLUDE  or I - list components of a paged
  85.                   file into an include file 
  86.  
  87.                 5.  HELP or H - print a command summary 
  88.  
  89.                 6.  EXIT or X - exit PAGER2 
  90.  
  91.                The case  used  to  enter  these  command  verbs is not
  92.           significant.    The  case  used  to  enter  the  file  names
  93.           referenced  as arguments to the command verbs is significant
  94.           if  the  host  operating  system  distinguishes case in file
  95.           names, as does UNIX (but not MSDOS).  
  96.  
  97.  
  98.           2.1.  PAGE Command 
  99.  
  100.                The PAGE  function  is  used  to  created a paged  file
  101.           from   one  or more component files.  The syntax of the PAGE
  102.           command is: 
  103.  
  104.                PAGE [filename | @include_filename]+ paged_file_name
  105.  
  106.                Two or  more file names may be specified after the PAGE
  107.           verb.   The  last file name is the name of the paged file to
  108.           be  created.  The other file names are the names of files to
  109.           be  placed into the paged file or the names of include files
  110.           from  which  the  names of files to be placed into the paged
  111.           file are to be extracted.  
  112.  
  113.                If the  user prefixes the name of a component file with
  114.           an   atsign  character  (@), the indicated file is processed
  115.           as  an  include  file.   An  include  file  is  a file which
  116.           contains   the   names  of  zero  or  more component  files,
  117.           one   name   per  line  starting in the first column.  Other
  118.  
  119.  
  120.           Richard Conn                                          Page 2
  121.  
  122.  
  123.                                      PAGER2
  124.  
  125.  
  126.           include  files  may   be   referenced   within   an  include
  127.           file    by   prefixing   their   names   with   the   atsign
  128.           character.   Comments  may  be placed within an include file
  129.           by  placing  two  dashes  in  the   first   two columns of a
  130.           line.  The following is an example of an include file: 
  131.  
  132.                    Example                      Comments
  133.                    =======                      ========
  134.           --
  135.           -- This is an include file for        Comment at the beginning
  136.           --  my favorite tool
  137.           --
  138.                                                 Blank lines are allowed
  139.           --
  140.           -- The following include file
  141.           --  contains the names of the         Another comment
  142.           --  Ada source files in compilation
  143.           --  order
  144.           --
  145.           @mytool.cmp
  146.           --
  147.           -- The following are the documentation
  148.           --  files
  149.           --
  150.           mytool.ref
  151.           mytool.doc
  152.           mytool.idx
  153.  
  154.                A single  letter  "P"  may be used rather than the full
  155.           "PAGE"  verb.   An  example  of  the  execution  of the PAGE
  156.           command is: 
  157.  
  158.           PAGER2> page
  159.            PAGE Command requires the name of the paged file and include file
  160.              Syntax: page [@include_file_name|file_name]+ paged_file_name
  161.           PAGER2> p @demo.inc demo.src
  162.            Adding demo.inc -- 8 Lines
  163.            Adding demo1.txt -- 1 Lines
  164.            Adding demo2.txt -- 1 Lines
  165.  
  166.  
  167.           2.2.  UNPAGE Command 
  168.  
  169.                The UNPAGE  function  extracts  the   components   from
  170.           the   indicated  paged   file,  leaving  the  original paged
  171.           file intact.  The syntax of UNPAGE is: 
  172.  
  173.               UNPAGE paged_filename
  174.  
  175.                The single  letter "U" may be used rather than the full
  176.           "UNPAGE"  verb.   An  example of the execution of the UNPAGE
  177.           command is: 
  178.  
  179.  
  180.           Richard Conn                                          Page 3
  181.  
  182.  
  183.                                      PAGER2
  184.  
  185.  
  186.           PAGER2> unpage
  187.            UNPAGE Command requires the name of a paged file
  188.              Syntax: unpage paged_file_name
  189.           PAGER2> u demo.src
  190.            Extracting demo.inc -- 8 Lines
  191.            Extracting demo1.txt -- 1 Lines
  192.            Extracting demo2.txt -- 1 Lines
  193.  
  194.  
  195.           2.3.  LIST Command 
  196.  
  197.                The LIST  function  is  used  to  create  a  text  file
  198.           containing   the  names   of   the  component files within a
  199.           paged file.  The syntax of the LIST command is: 
  200.  
  201.                LIST paged_file_name
  202.  
  203.                The single  letter "L" may be used rather than the full
  204.           "LIST"  verb.   An  example  of  the  execution  of the LIST
  205.           command is: 
  206.  
  207.           PAGER2> list
  208.            LIST Command requires the name of a paged file
  209.              Syntax: list paged_file_name
  210.           PAGER2> list demo.src
  211.            demo.inc -- 8 Lines
  212.            demo1.txt -- 1 Lines
  213.            demo2.txt -- 1 Lines
  214.  
  215.  
  216.           2.4.  INCLUDE Command 
  217.  
  218.                The INCLUDE  command  performs the same function of the
  219.           LIST  command, but it places the output into an include file
  220.           which  is  suitable  for  building  a  new  paged file.  Its
  221.           syntax is: 
  222.  
  223.               INCLUDE paged_file_name include_file_name
  224.  
  225.                The single  letter "I" may be used rather than the full
  226.           "INCLUDE"  verb.  An example of the execution of the INCLUDE
  227.           command is: 
  228.  
  229.           PAGER2> include
  230.            INCLUDE Command requires the name of a paged file
  231.              Syntax: include paged_file_name output_include_file
  232.           PAGER2> include demo.src demo2.inc
  233.            demo.inc -- 8 Lines
  234.            demo1.txt -- 1 Lines
  235.            demo2.txt -- 1 Lines
  236.  
  237.  
  238.  
  239.  
  240.           Richard Conn                                          Page 4
  241.  
  242.  
  243.                                      PAGER2
  244.  
  245.  
  246.           2.5.  HELP Command 
  247.  
  248.                The HELP  command  displays  a brief help text  to  the
  249.           user.   The syntax of this command is: 
  250.  
  251.               HELP
  252.  
  253.                The single  letter "H" may be used rather than the full
  254.           "HELP" verb.  
  255.  
  256.  
  257.           2.6.  EXIT Command 
  258.  
  259.                The EXIT command exits PAGER.  Its syntax is: 
  260.  
  261.               EXIT
  262.  
  263.                The single  letter "X" may be used rather than the full
  264.           "EXIT" verb.  
  265.  
  266.  
  267.  
  268.  
  269.           3.  INVOKING PAGER2 FROM THE COMMAND LINE 
  270.  
  271.                PAGER2 may  also  be  run  from  the command line.  The
  272.           PAGER2  verb  may  be  followed  by  a  conventional  PAGER2
  273.           command,  in  which  case  the  PAGER2 command alone will be
  274.           executed  and  then PAGER2 will exit.  In addition, the verb
  275.           recognized  by  PAGER2 (like HELP or UNPAGE) may be prefixed
  276.           with  a  dash  (-),  making the syntax of the PAGER2 command
  277.           line  similar  to  a  conventional  UNIX  command line.  For
  278.           example,  to  obtain  a  display  of the brief help message,
  279.           either of these commands may be used: 
  280.  
  281.               PAGER2 HELP
  282.               PAGER2 H
  283.               PAGER2 -H
  284.               PAGER2 -help
  285.  
  286.                Likewise, to  create  a  paged file, named MYFILES.SRC,
  287.           from   the   component   files   FILE1.TXT,  FILE2.TXT,  and
  288.           FILE3.TXT, a command like the following could be issued: 
  289.  
  290.               PAGER2 -PAGE FILE1.TXT FILE2.TXT FILE3.TXT MYFILES.SRC
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.           Richard Conn                                          Page 5
  301.  
  302.  
  303.                                      PAGER2
  304.  
  305.  
  306.           4.  SAMPLE SESSION 
  307.  
  308.                The following  is  a  sample  PAGER2  session.   It was
  309.           run  on  a  SUN 3 Model 260 running SunOS 3.5.  
  310.  
  311.           ifsun0/xanadu> ls -l
  312.           total 3
  313.           -rw-r--r--  1 xanadu        166 Jun 16 10:23 demo.inc
  314.           -rw-r--r--  1 xanadu         23 Jun 16 10:23 demo1.txt
  315.           -rw-r--r--  1 xanadu         23 Jun 16 10:23 demo2.txt
  316.  
  317.           ifsun0/xanadu> cat demo.inc
  318.           -- This is a demonstration of the PAGER2 program
  319.  
  320.           -- The include file is named DEMO.INC
  321.           demo.inc
  322.  
  323.           -- The source files are DEMO1.TXT and DEMO2.TXT
  324.           demo1.txt
  325.           demo2.txt
  326.  
  327.           ifsun0/xanadu> cat demo1.txt
  328.           This is file DEMO1.TXT
  329.  
  330.           ifsun0/xanadu> cat demo2.txt
  331.           This is file DEMO2.TXT
  332.  
  333.           ifsun0/xanadu> pager2
  334.           PAGER2, Ada Version 1.1
  335.           Type 'h' for Help
  336.  
  337.           PAGER2> page
  338.            PAGE Command requires the name of the paged file and include file
  339.              Syntax: page [@includefilename|filename]+ pagedfilename
  340.  
  341.           PAGER2> p @demo.inc demo.src
  342.            Adding demo.inc -- 8 Lines
  343.            Adding demo1.txt -- 1 Lines
  344.            Adding demo2.txt -- 1 Lines
  345.  
  346.           PAGER2> list
  347.            LIST Command requires the name of a paged file
  348.              Syntax: list pagedfilename
  349.  
  350.           PAGER2> list demo.src
  351.            demo.inc -- 8 Lines
  352.            demo1.txt -- 1 Lines
  353.            demo2.txt -- 1 Lines
  354.  
  355.           PAGER2> include
  356.            INCLUDE Command requires the name of a paged file
  357.              Syntax: include pagedfilename outputincludefile
  358.  
  359.  
  360.           Richard Conn                                          Page 6
  361.  
  362.  
  363.                                      PAGER2
  364.  
  365.  
  366.  
  367.           PAGER2> include demo.src demo2.inc
  368.            demo.inc -- 8 Lines
  369.            demo1.txt -- 1 Lines
  370.            demo2.txt -- 1 Lines
  371.  
  372.           PAGER2> x
  373.  
  374.           ifsun0/xanadu> cat demo.src
  375.           --::::::::::
  376.           --demo.inc
  377.           --::::::::::
  378.           -- This is a demonstration of the PAGER2 program
  379.  
  380.           -- The include file is named DEMO.INC
  381.           demo.inc
  382.  
  383.           -- The source files are DEMO1.TXT and DEMO2.TXT
  384.           demo1.txt
  385.           demo2.txt
  386.           --::::::::::
  387.           --demo1.txt
  388.           --::::::::::
  389.           This is file DEMO1.TXT
  390.           --::::::::::
  391.           --demo2.txt
  392.           --::::::::::
  393.           This is file DEMO2.TXT
  394.  
  395.           ifsun0/xanadu> cat demo2.inc
  396.           -- Include file for demo.src
  397.           demo.inc
  398.           demo1.txt
  399.           demo2.txt
  400.  
  401.           ifsun0/xanadu> pager2
  402.           PAGER2, Ada Version 1.1
  403.           Type 'h' for Help
  404.  
  405.           PAGER2> u demo.src
  406.            Extracting demo.inc -- 8 Lines
  407.            Extracting demo1.txt -- 1 Lines
  408.            Extracting demo2.txt -- 1 Lines
  409.  
  410.           PAGER2> unpage
  411.            UNPAGE Command requires the name of a paged file
  412.              Syntax: unpage pagedfilename
  413.  
  414.           PAGER2> u demo.src
  415.            Extracting demo.inc -- 8 Lines
  416.            Extracting demo1.txt -- 1 Lines
  417.            Extracting demo2.txt -- 1 Lines
  418.  
  419.  
  420.           Richard Conn                                          Page 7
  421.  
  422.  
  423.                                      PAGER2
  424.  
  425.  
  426.  
  427.           PAGER2> x
  428.           ifsun0/xanadu> ls -l
  429.           total 5
  430.           -rw-r--r--  1 xanadu        166 Jun 16 10:26 demo.inc
  431.           -rw-r--r--  1 xanadu        325 Jun 16 10:25 demo.src
  432.           -rw-r--r--  1 xanadu         23 Jun 16 10:26 demo1.txt
  433.           -rw-r--r--  1 xanadu         58 Jun 16 10:25 demo2.inc
  434.           -rw-r--r--  1 xanadu         23 Jun 16 10:26 demo2.txt
  435.  
  436.  
  437.  
  438.  
  439.  
  440.  
  441.  
  442.  
  443.  
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469.  
  470.  
  471.  
  472.  
  473.  
  474.  
  475.  
  476.  
  477.  
  478.  
  479.  
  480.           Richard Conn                                          Page 8
  481.  
  482.