home *** CD-ROM | disk | FTP | other *** search
/ The Developer Connection…ice Driver Kit for OS/2 3 / DEV3-D1.ISO / prodtool / util2 / list2bm.doc < prev    next >
Encoding:
Text File  |  1993-11-17  |  4.3 KB  |  105 lines
  1.                   list2bm.doc : The 'list2bm' command
  2.                           By:  Brian E. Yoder.
  3.                                 11/17/93
  4.  
  5. The list2bm command reads a list file that names a set of files.  It
  6. combines the named set of files into one output file, converting special
  7. characters in each file to BookMaster symbols.  The output file can be
  8. processed by BookMaster to produce a nicely formatted document that
  9. contains all of the named files, one file per chapter.
  10.  
  11. ========================================================================
  12. Command syntax
  13. ========================================================================
  14.  
  15.         list2bm [-n] listfile outfile
  16.  
  17. This program reads a list file and writes a BookMaster document to
  18. outfile.  The output document contains a title page and the contents of
  19. the files named in the listfile.  Each named file is contained in its
  20. own ":h1." heading and is enclosed with example tags.  The entire
  21. document is enclosed by :userdoc and :euserdoc tags.
  22.  
  23. If -n is specified, no title page is written to the output and the
  24. output file has no :userdoc and :euserdoc tags.  However, each file
  25. named in the listfile is written to the output file.  The output file is
  26. then suitable for a high-level document to imbed.
  27.  
  28. ========================================================================
  29. Format of the list file
  30. ========================================================================
  31.  
  32. In general, the list file is a text file.  Blank lines are ignored.
  33. Lines that begin with a # are assumed to contain comments and are
  34. ignored.  Any text on a line that begins with a # (except within a
  35. string) is assumed to be a comment and is ignored.
  36.  
  37. The rest of the list file consists of a series of tokens.  A token is a
  38. series of contiguous non-blank characters, a series of characters
  39. enclosed by either double quotes or by single quotes, or an equal sign.
  40.  
  41. --------------------- Title page ---------------------------------------
  42.  
  43. The first lines in the list file define the title page as follows:
  44.  
  45.         -sec     "Security Classification"
  46.         -date    "Date of Document"
  47.         -author  "Author of Document"
  48.         -title   "Title of Document"
  49.  
  50. In place of each string, you can specify the name of an environment
  51. variable preceeded by a $. In this case, the value of the environment
  52. variable is used.  For example, if your environment contains the
  53. variable 'DATE=March 3, 1989', then the following two date
  54. specifications are the same:
  55.  
  56.         -date    "March 3, 1989"
  57.         -date    $DATE
  58.  
  59. --------------------- File names ---------------------------------------
  60.  
  61. The remaining lines in the list file specify file names and section
  62. headings as follows:
  63.  
  64.         -section "Title of Section"
  65.  
  66.         filename
  67.  
  68. A section heading is simply an ":h0."  tag.
  69.  
  70. A file is put into its own ":h1."  tag, with the name of the heading set
  71. to the name of the file.  If the name of the file has a drive letter and
  72. colon in it, such as 'd:string', only the 'string' portion is written to
  73. the heading.
  74.  
  75. ========================================================================
  76. Sample List File:  This is an excerpt from the "utilsrc.txt" file in
  77. this directory.  It illustrates a properly formatted listfile.
  78. ========================================================================
  79.  
  80. #------------------------------------------------------------------------------
  81. # Title page
  82. #------------------------------------------------------------------------------
  83.  
  84. -sec    "Unclassified"
  85. -title  "util Source Code (OS/2)"
  86. -author "Brian E. Yoder"
  87. -date   "October 16, 1991"
  88.  
  89. #------------------------------------------------------------------------------
  90. # Body of the output document
  91. #------------------------------------------------------------------------------
  92.  
  93. -section "Makefile and Listfiles"
  94. makefile                            # Primary makefile
  95. util.rsp                            # Response file for LIB command
  96. util.def                            # Module definition file for utilities
  97.  
  98. -section "Command Files"
  99. c.cmd                               # Compile
  100. l.cmd                               # Link
  101.  
  102. -section "Library Subroutines"
  103. crcfile.c                           # Get CRC and length of a file
  104. cfaccess.c                          # Customization (text) file subroutines
  105.