!=============================================================================!
!  DIVISION   I	:				     HELP MODULE DECLARATION  !
!=============================================================================!
!									      !
!      -----------------------------------------------------------------      !
!      SECTION 01 :					 INITIAL VERSION      !
!      -----------------------------------------------------------------      !
!									      !
!      File Specification: ACCSRC_HELPUSER:LISTER.HLP			      !
!      Author		 : Marlys A. Nelson				      !
!      Initial version	 : 01.00.00 28-OCT-1984	VMS 3.6			      !
!									      !
!      -----------------------------------------------------------------      !
!      SECTION 02 :				    MODIFICATION HISTORY      !
!      -----------------------------------------------------------------      !
!									      !
!      01.00.01 31-OCT-1985 VMS 4.2: Marlys A. Nelson			      !
!		One text line began with the number  '3'  and  this  was      !
!		  being interpretted as a help level marker.   Rearrange      !
!		  text so that the number 3 was not at the beginning.	      !
!									      !
!=============================================================================!
!  DIVISION  II	:				  HELP MODULE SPECIFICATIONS  !
!=============================================================================!
!									      !
!      Key 1 (Command name)............	LISTER				      !
!	 Key 2 ........................	  Parameters                          !
!	 Key 2 ........................	  Qualifiers                          !
!	 /qualifier ...................	    /FORMFEED                         !
!	 /qualifier ...................     /HEADER			      !
!	 /qualifier ...................     /LOG			      !
!	 /qualifier ...................	    /NARROW			      !
!	 /qualifier ...................	    /NUMBERS			      !
!	 /qualifier ...................	    /OUTPUT=filespec		      !
!	 /qualifier ...................	    /PRINT			      !
!	 /qualifier ...................	    /TAB			      !
!	 /qualifier ...................	  /UNPRINTABLES			      !
!	 Key 2 ........................   %PAGE				      !
!	 Key 2 ........................   %TITLE			      !
!	 Key 2 ........................   Examples			      !
!	 Key 2 ........................   Errors			      !
!									      !
!=============================================================================!
!  DIVISION III	:					       SPECIAL NOTES  !
!=============================================================================!
!									      !
!									      !
!=============================================================================!
!
!
!=============================================================================!
! Key 1								       LISTER !
!=============================================================================!
!
1 LISTER
LISTER  is  designed to provide printer listings in a more useful form
than either the DCL $PRINT command or compiler  listings.

Format:

     LISTER	filespec[,...]

The  major features of LISTER are:

  o  Each page contains a heading line.  The heading line contains the
     date and time when the listing was generated, the page number and
     the  "complete"  file  specification  (not  just the filename and
     filetype provided by $PRINT/HEADER) of the file listed.

  o  You may specify a title string to be printed on the  header  line
     in  place  of  the  filespecification.  This allows sections of a
     large program to be easily located.

  o  "Unprintable"  characters  will   be  displayed  as  a  character
     sequence  which  indicates  the  non-printing character, i.e. the
     escape character is displayed as "<esc>".

  o  LISTER provides two columns of sequence numbers  identifying  the
     line  in  the  source  file.   Compilers provide only one column.
     When program aborts occur, the line number shown on the traceback
     cannot  always  be  located  easily  in  the  source  file due to
     'INCLUDE' files or  the  presence  of  procedures,  functions  or
     subroutines.    Compiler  listings  start  numbering  at  1,  and
     increment by 1, for each line read, regardless of where the  line
     originated (main source file or an include file).  Some compilers
     will restart the line numbering for each procedure,  function  or
     subroutine  encountered.  LISTER will provide this same numbering
     sequence as the compiler.  However, LISTER provides a second  set
     of  line  numbers specific to the file.  This set of line numbers
     start at 1 and are incremented by 1 for each  line  in  the  main
     source file.  Line numbering restarts at 1 for each include file.
     Hence, you can cross-reference the traceback line number  to  the
     actual source file line number.

  o  By default, listings generated by LISTER are  formatted  for  132
     characters  per line.  You may select /NARROW mode however.  This
     instructs LISTER to format the lines for 80  characters.   LISTER
     will  automatically  wrap  long  lines onto multiple lines on the
     resulting listfile.
!
!=============================================================================!
! Key 2								   Parameters !
!=============================================================================!
!
2 Parameters
filespec[,...]

  Specifies the files to be listed.  The files must  reside  on  disk.
  You  may  specify  multiple  files  by  separating  each  individual
  filespecification with a comma (,) or plus sign  (+).   The  results
  differ depending upon the delimiter used.

  Files  separated  by  commas  will  each  be listed to an individual
  output  file.   This  will  create  one  print  job  for  each  file
  specified, each with its own preceding flag page.  Note: This result
  can be overridden by use of the /OUTPUT qualifier.

  Files  separated by plus signs are concatenated into one output file
  and result in only one print job.  A page break occurs at  each  new
  file  however.   Page  numbering and line numbering also restart for
  each file.

  Wildcard characters can be used in the directory, filename, filetype
  and version number fields.  Multiple files listed in this manner are
  treated  as  if  each  file  was  specified  individually, with each
  filespecification separated by a comma.

  Unless defined explicitly by  use  of  the  /OUTPUT  qualifier,  the
  listing file is created in the current default device and directory,
  regardless of the source file location.   LISTER  will  resolve  all
  internal  "include"  file specifications relative to the source file
  location however.
!
!=============================================================================!
! Key 2								   Qualifiers !
!=============================================================================!
!
2 Qualifiers
/FORMFEED

  /FORMFEED (D)
  /NOFORMFEED

  Instructs  LISTER  on  the  manner  in  which  to  process  FORMFEED
  characters (control-L).  By default, a formfeed character located as
  the first, and only, character on a line is interpretted as  a  page
  break  mark.   It is not replaced by the mnemonic "<ff>".  All other
  formfeed characters are  replaced  by  "<ff>".   If  /NOFORMFEED  is
  specified, all formfeed characters are replaced by "<ff>" regardless
  of their location on the line.

/HEADER

  /HEADER (D)
  /NOHEADER

  Page  headers  are  normally  printed  on  each  page.   The heading
  includes the page number, date, time and page title.   If  /NOHEADER
  is selected, no page headings are printed.

/LOG

  /LOG
  /NOLOG (D)

  Controls whether the LISTER command displays the file  specification
  of each file successfully listed.

/NARROW

  /NARROW
  /NONARROW (D)

  Determines the length of the lines written to the output  file.   By
  default,  LISTER  assumes  132  characters  per line.  If /NARROW is
  specified, LISTER formats the listing for 80  characters  per  line.
  In  either  case,  longer  lines will be wrapped to multiple listing
  lines.

/NUMBERS

  /NUMBERS (D)
  /NONUMBERS

  Determines  if LISTER assigns sequence numbers to each line printed.
  By default, sequence numbers are assigned.  The numbers are  grouped
  into  two columns and occupy the leftmost 16 positions of each line.
  The actual text of  the  source  lines  begins  in  column  17.   By
  specifying  /NONUMBERS,  LISTER  will  suppress the display of these
  sequence numbers and the source lines will be  printed  starting  in
  column 1.

  The  leftmost  column of numbers corresponds to the sequence numbers
  generated by the compilers.  These numbers can be  used  in  program
  abort tracebacks to locate the source line which caused the abort.

  The  rightmost column of numbers identifies the source line relative
  to the file in which it is found.  This column helps when  using  an
  editor to locate a particular line in a file.  This column is useful
  because of the way the compiler line numbering works on files  which
  "include"  other  files.  The compiler numbers all lines, even those
  in "include" files, sequentially.  A traceback  may  point  to  line
  number 255 but the line in the source file which corresponds to this
  line may actually be line number 205.  This  column  also  helps  in
  those  languages where the compiler restarts its line numbering at 1
  for every subroutine and function encountered (i.e.  FORTRAN).   The
  error  traceback  may indicate line 10 in subroutine ABC.  The inner
  column of numbers can be used to find the corresponding line in  the
  source file.

  Another  column  of  information  may also appear on a LISTER output
  file.  This column is located between the two  columns  of  sequence
  numbers  discussed  previously.  This column contains the letter 'I'
  followed by a single-digit number.   This  indicates  the  line  has
  originated  in  an  "include" file at the nesting level indicated by
  the digit.  For example, "I1"  identifies  lines  found  in  a  file
  "included"  by  the  main  source  file.  "I2"  would identify lines
  "included" by the "I1" include file (i.e. the "I1" file contains  an
  "include" statement also).

/OUTPUT

  /OUTPUT=filespec

  Specifies  a  file  to  contain  the  output  generated  by  LISTER.
  Normally, LISTER will generate a  separate  listing  file  for  each
  input  file by using the input file name with the file type of .LIS.
  If the /OUTPUT qualifier is specified,  all  the  listings  for  the
  input  files will be concatenated into a single output file with the
  name  specified  as  "filespec".   The  default  filetype  for   the
  "filespec"  is  .LIS.  (Note: use of the plus sign (+) as a filespec
  delimiter will also produce the same  effect,  however,  the  output
  filename will be derived from the first input file in the list.)

/PRINT

  /PRINT (D)
  /NOPRINT

  Determines what action LISTER  takes  after  generating  the  output
  file.   By  default,  LISTER will queue the file for printing on the
  standard line printer queue.  If you specify /NOPRINT,  LISTER  will
  not  queue  the file for printing.  In either case, the listing file
  is left on disk.

/TAB

  /TAB (D)
  /NOTAB

  Instructs  LISTER  on  the manner in which to process TAB characters
  (control-I).  By default, a tab character is treated in the  normal,
  system-defined  manner.   Each  tab  causes movement to the next tab
  stop.  Tab stops are defined in 8-column intervals.   If  /NOTAB  is
  specified, all tab characters are replaced by the mnemonic "<tab>".

/UNPRINTABLES

  /UNPRINTABLES (D)
  /NOUNPRINTABLES

  Instructs LISTER on the manner  in  which  to  process  non-printing
  characters.   Non-printing characters are usually control characters
  and the  escape  character.   By  default,  LISTER  will  replace  a
  non-printing  character  with  a  mnemonic code which identifies the
  non-printing character (i.e. the  escape  character  is  printed  as
  "<esc>").    If   /NOUNPRINTABLES  is  specified,  the  non-printing
  characters appear in the output file without interpretation.  Output
  listings can cause unexpected results if non-printing characters are
  interpretted.   Note:   the  formfeed  (control-L)   and   the   tab
  (control-I)  are  exceptions  to  this  rule  as explained under the
  qualifiers /FORMFEED and /TAB.
!
!=============================================================================!
! Key 2									%PAGE !
!=============================================================================!
!
2 %PAGE
LISTER recognizes  a  single  formfeed  character  (control-L)  as  an
"advance-to-next-page"  command.   All  the  language  compilers  also
recognize this character.  This  allows  you  to  create  easy-to-read
listings by forcing specific sections of code to begin at the top of a
new page.

LISTER will also recognize the keyword %PAGE as  performing  the  same
function.   The  BASIC  language  compiler recognizes %PAGE also, thus
BASIC source files may use %PAGE directly.  For all other files,  this
keyword  MUST  be enclosed within a comment.  The exact manner used to
specify the comment  depends  upon  the  source  file  language.
Examples for several languages are shown below:

  Fortran: C     %PAGE
           !     %PAGE

  Macro  : ; %PAGE

  Pascal : { %PAGE }
           (* %PAGE *)

By enclosing the LISTER %PAGE directive  within  comments  allows  the
source  file  to be compiled by any of the language compilers.  (Note:
the language compilers will NOT recognize the %PAGE keyword however so
formfeed characters are a better choice).

The  %PAGE  directive  should  not  be  enclosed  by  quotes or single
apostrophes.  LISTER will ignore any such %PAGE  directives,  even  if
the %PAGE is within a comment.

Also, the comment which contains the %PAGE directive must BEGIN on the
line containing the %PAGE keyword.  This  is  important  to  note  for
those  languages  which allow multiline comments, such as Pascal.  For
example,

  Example 1: line 10 (* %PAGE *)
  Example 2: line 10 (* %PAGE
                  11 *)
  Example 3: line 10 (*
                  11 %PAGE
                  12 *)

All  the  examples  above  would  compile  successfully  by the Pascal
compiler.  LISTER  would  fail  to  recognize  the  keyword  %PAGE  in
Example 3 as valid - LISTER would  not  believe  it  to  be  within  a
comment.
!
!=============================================================================!
! Key 2								       %TITLE !
!=============================================================================!
!
2 %TITLE
The  page  heading  printed by LISTER includes an area called the page
title.    The   page   title   initially   contains    the    complete
filespecification  of  the  file currently being listed.  The title is
designed to be changed by the user to provide a means by which program
listings can be more useful.

Format:

     %TITLE 'string'

LISTER recognizes the keyword %TITLE  as  a  special  directive  which
defines  this  page  title.   The  BASIC  language compiler recognizes
%TITLE also.  This allows BASIC source files to use  %TITLE  directly.
For  all  other files, this keyword MUST be enclosed within a comment.
The exact manner used to specify the comment depends upon  the  source
file language.  Examples for several languages are shown below:

  Fortran:  C     %TITLE 'string'
            !     %TITLE 'string'

  Macro  :  ; %TITLE 'string'
     
  Pascal :  { %TITLE 'string' }
            (* %TITLE 'string' *)

By  enclosing  the  LISTER %TITLE directive within comments allows the
source file to be compiled by any of the language  compilers.   (Note:
the language compilers will NOT recognize the %TITLE keyword however).

The  %TITLE  keyword itself should not be enclosed by quotes or single
apostrophes.  LISTER will ignore any such %TITLE directives,  even  if
the %TITLE is within a comment.

The string to be used as the page title must  be  enclosed  by  single
apostrophes.   If no string is specified, the title remains unchanged.
The %TITLE directive and the title string, surrounded by  apostrophes,
must be contained entirely on one source line.

When  LISTER  encounters  a  %PAGE  directive  or  a  single  formfeed
character, it checks the succeeding line in the source file.  If  that
line  contains  a  %TITLE  directive,  the  title  string  is  updated
immediately and the new  page  contains  this  new  title.   You  will
usually  want to use %TITLE directives following the formfeed or %PAGE
directive to which the title string applies.  If the first line in the
source  file  contains  a %TITLE, this title string will appear on the
first page of the listing.

The comment which contains the %TITLE directive must BEGIN on the line
containing  the  %TITLE  keyword.  This is important to note for those
languages  which  allow  multiline  comments,  such  as  Pascal.   For
example,

  Example 1: line 10 (* %TITLE 'string' *)
  Example 2: line 10 (* %TITLE 'string'
                  11 *)
  Example 3: line 10 (*
                  11 %TITLE 'string'
                  12 *)

All  the  examples  above  would  compile  successfully  by the Pascal
compiler.  LISTER would  fail  to  recognize  the  keyword  %TITLE  in
Example 3 as valid - LISTER would not believe it to be in a comment.
!
!=============================================================================!
! Key 2								     Examples !
!=============================================================================!
!
!2 Examples
!
!=============================================================================!
! Key 2								       Errors !
!=============================================================================!
!
!2 Errors
!
!=============================================================================!
! END OF HELP MODULE                                                          !
!=============================================================================!
