Shareware Grab Bag/Shareware Grab Bag.iso/007/c_doc.arc/C_DOC.M

Text File | 1987-03-10 | 5.8 KB | 132 lines

;*****************************************************************************
;*            (c) COPYRIGHT LIFE SCIENCES, INC. 1987, ALL RIGHTS RESERVED     **
;*****************************************************************************
;**    This macro is released for use but may not be included in any
;**    package sold for commercial gain.
;**
;**                                 Douglas Hill
;**                                Life Sciences, Inc
;**                                RR1, Box 37F
;**                                 W. Lebanon, NH  03784
;**                                 [phone]
;**
;**          NOTE: needs BRIEF v1.33 for the "date" function
;** C_DOC creates and updates a functional description, modification history,
;** and copyright notice for c programs.  This is the easiest way I know for
;** a team of programmers to keep each other informed of changes they have
;** made.  The uniform format also makes it possible to write programs to
;** extract the change notices from all the c files in a directory, sort them
;** and produce lists of changes made in a project arranged by date, author,
;** or module.  (If you write such a program, you might send me a copy.)
;**
;** The first time C_DOC is invoked on a given file, it creates the outline
;** of a functional description and copyright notice, giving your name as
;** author and the current date as the creation date.  It inserts the name
;** of the file and leaves you in a position to describe the file name.  I
;** find this useful for explaining cryptic filenames, like pbtoouts.c -
;** Paste Buffer to Output String.
;**
;** The next time c_doc is invoked on the file, it will leave you in a position
;** to describe the functions of the procedures in the file.
;**
;** All subsequent invocations will add your name and the date to the
;** modification history and leave you in a position to describe the change.
;** If the current year is later than the latest year on the copyright notice
;** the notice will be updated.
;**
;** I assign C_DOC to a key and press it once when I have just created the
;** file (and the rationale for that file name is still fresh), once to
;** describe how the functions are called, what they do and what they return,
;** and then any time I make a change worth recording.
;**
;** C_DOC needs to know two things, the current author's name, and the name
;** to use as the copyright owner.  (If the copyright owner name changes, the
;** copyright date will not be updated with changes.)
;** You may insert these into the program as shown below, or put them in the
;** environmental variables C_AUTHOR and C_OWNER.  For example,
;** SET C_AUTHOR=Doug Hill
;** You must exit Brief to set these; if you just pop out temporarily to set
;** them, they'll be gone when you type "exit".  If the environmental strings
;** exist, they will take precedence over the names defined below.
;**
;** Thanks to Wendin, Inc.  This format is similar to the modification history
;** in their Operating System Toolbox (TM).

(macro c_doc
   (
      (string bname date_str year_str copy_str new_copy_str
              tem_str owner author)
      (int year month day)

      (= author (inq_environment "C_AUTHOR"))
      (if (== (strlen author) 0)
         (= author "D. P. Hill")         ;** PUT YOUR NAME HERE **
      )
      (= owner (inq_environment "C_OWNER"))
      (if (== (strlen owner) 0)
         (= owner "Life Sciences, Inc.") ;** PUT COPYRIGHT OWNER HERE **
      )

      (date year month day)        ;** modify these 3 lines to put date
      (sprintf year_str "%d" year) ;** in the format you like
      (sprintf date_str "%02d/%02d/%s" month day (substr year_str 3))

      (move_abs 1 1)             ;** move to beginning of file
      (if (<= (search_fwd "Modification history") 0)  ;** if no header yet
         (                       ;** create it
            (insert "/*\n")
            (insert "1.      Proc name.\n\n\n")
            (insert "2.      Functional description.\n\n")
            (insert "3.      Modification history.\n")
            (sprintf tem_str "        %s\n\n\n" author)
            (insert tem_str)
            (sprintf tem_str
               "4.      NOTICE:  Copyright (C) %d %s\n*/\n" year owner
            )
            (insert tem_str)
            (move_abs 8 25)      ;** put in date
            (insert date_str)
            (end_of_line)
            (insert "  Creation")
            (move_rel 1 0)
            (delete_line)
            (move_abs 3 9)       ;** add name of file
            (inq_names NULL NULL bname);  ;** get name of buffer
            (insert bname)
            (insert " - ")       ;** leave cursor after name
         )
         ;else                   ;** modification history exists - add to it
         (
            (save_position)
            (sprintf copy_str "%d %s" year owner) ;** update copyright message
            (if (< (search_fwd copy_str 0) 1)  ;** if message not current
               (
                  (sprintf copy_str "19{??} %s" owner)
                  (sprintf new_copy_str "19\\0, %d %s" year owner)
                  (translate copy_str new_copy_str 0)
               )
            )
            (restore_position)
            (move_rel -2 -8)
            (if (== (read 2) "2.")  ;** haven't described function yet
               (
                  (end_of_line)
                  (insert "\n        ")
               )
               ;else       ;** add next modification
               (
                  (search_fwd "4.")
                  (move_rel -1 8)
                  (insert author)
                  (move_abs 0 25)
                  (insert ( + date_str "\n"))
                  (move_rel -1 0)
                  (end_of_line)
                  (insert "  ") ;** leave cursor here for change description
               )
            )
         )
      )
   )
)