!short: Submitting code for the Library
'------------------------------------------------------------------------------

  When submitting code for the Nanforum Tooklit Library, please
  observe the following rules and formatting:

   1. Please format your headers ^bexactly^n as shown in the samples.
      A good deal of time went into the creation of a program to generate
      this Norton Guide.  By submitting your headers in the requested
      format, future versions of the library can be released much more
      quickly then the first.

   2. Include at least one example of your function, no matter how
      trivial or obvious it may be.  An example is worth a thousand words.

   3. Enclose all references to parameters within angle brackets, ie:
      <nElements>.  The NG generator program will automatically
      highlight parameter references in the "Arguments" section.

   4. Do not put any blank lines between $sections$, the NG generator
      will insert them as needed.  Blank lines are ok within sections.

   5. The $ONELINER$ field must be no longer than 60 characters.  It is
      intended for a brief description of the function only.

   6. All fields except $FUNCNAME$, $CATEGORY$ and $ONELINER$ can
      contain as many lines as necessary.

   7. The $ARGUMENTS$ and $DESCRIPTION$ fields should contain blank lines
      between paragraphs or argument descriptions.

   8. The $RETURNS$ field is only necessary for functions.  If your
      submission is a command, omit this entry.

   9. The $INCLUDE$ field is for the name of the header file, if any,
      that is required for the use of your function.  Generally this
      will apply only to commands.

  10. The $SEEALSO$ filed is for the names of related functions or
      commands, and is used to generate the "See also:" references in
      the Norton Guide.  This field is optional and may be filled in by
      the librarian or documenter.

      If a $SEEALSO$ entry contains two or more words, enclose the
      entry within quotes, ie:

            $SEEALSO$
               "MENU TO" FT_MENUTO()

  11. It is preferable to have only one function per file, except for
      STATIC functions or internal support routines.  Do not document
      STATIC or internal support functions with a standard header
      (although they should be documented with comments).

      If it is necessary to include more than one "PUBLIC" function in
      a source code file, do not duplicate the initial file header (the
      one with the "File...." and "Author...." fields).


      Thank you.
!seealso: "Sample Clipper or C header" "Sample ASM header" 
'------------------------------------------------------------------------------



!short: Sample Clipper or C header
'------------------------------------------------------------------------------

                ^bThis example shows how you would set up the
               ^bheaders for either a Clipper or C source file.

/*
 * File......: PRTSCR.C
 * Author....: Ted Means
 * CIS ID....: 73067,3332
 * Date......: $Date$
 * Revision..: $Revision$
 * Log file..: $Logfile$
 *
 * This is an original work by Ted Means and is placed in the
 * public domain.
 *
 * Modification history:
 * ---------------------
 *
 * $Log$
 *
 */

/*  $DOC$
 *  $FUNCNAME$
 *     FT_PrtScr()
 *  $ONELINER$
 *     Enable or disable printscreens
 *  $SYNTAX$
 *     FT_PrtScr( <lSetStat> ) -> lCurStat
 *  $ARGUMENTS$
 *     <lSetStat> set to .T. will enable printscreens, .F. will
 *     disable printscreens.
 *  $RETURNS$
 *     The current state ( .T. for enabled, .F. for disabled).
 *  $DESCRIPTION$
 *     This function is valuable if you have a need to disable the
 *     printscreen key.  It works by fooling the BIOS into thinking
 *     that a printscreen is already in progress.  The BIOS will then
 *     refuse to invoke the printscreen handler.
 *  $EXAMPLES$
 *     FT_PrtScr( .F. )       // Disable the printscreen key
 *     FT_PrtScr( .T. )       // Enable the printscreen key
 *     MemVar := FT_PrtScr()  // Get the current status
 *  $INCLUDE$
 *     FTVIDEO.CH
 *  $SEEALSO$
 *     ft_peek() ft_poke()
 *  $END$
 */

^b                        Formatting Guidelines
/*
 * File......: PRTSCR.C
 * Author....: Ted Means
 * CIS ID....: 73067,3332
 * Date......: $Date$        ^b  <- Leave blank, for librarian's use
 * Revision..: $Revision$    ^b  <-    "
 * Log file..: $Logfile$     ^b  <-    "
 *
 * This is an original work by Ted Means and is placed in the
 * public domain.
 *
 * Modification history:
 * ---------------------
 *                           ^b   
 * $Log$                     ^b    Leave blank, for librarian's use
 *                           ^b   
 */

/*  $DOC$
 *  $FUNCNAME$
^b   indent all items 6 spaces after asterisk
 * ^b^n   FT_PRTSCR()                           ^b<- 15 characters MAXIMUM
 * ^b^n$ONELINER$
 * ^b^n   Enable or disable printscreens        ^b<- 60 character MAXIMUM
 * ^b^n$SYNTAX$
 * ^b^n   FT_PRTSCR( <lSetStat> ) -> lCurStat
 * ^b^n$ARGUMENTS$  Parameters in angle brackets
 * ^b^n   <lSetStat> set to .T. will enable printscreens, .F. will
 * ^b^n   disable printscreens.
 * ^b^n$RETURNS$
 * ^b^n   The current state ( .T. for enabled, .F. for disabled).
 * ^b^n$DESCRIPTION$
 * ^b^n   This function is valuable if you have a need to disable the
 * ^b^n   printscreen key.  It works by fooling the BIOS into thinking
 * ^b^n   that a printscreen is already in progress.  The BIOS will then
 * ^b^n   refuse to invoke the printscreen handler.
   ^b^n   ^b Lines no longer than 65 characters 
 * ^b^n$EXAMPLES$
 * ^b^n   FT_PRTSCR( .F. )       // Disable the printscreen key
 * ^b^n   FT_PRTSCR( .T. )       // Enable the printscreen key
 * ^b^n   MemVar := FT_PRTSCR()  // Get the current status
 * ^b^n$INCLUDE$
 * ^b^n   FTVIDEO.CH                            ^b<- optional
 * ^b^n$SEEALSO$
 * ^b^n   FT_PEEK() FT_POKE()                   ^b<- optional
 * ^b^n$END$
 */^b^n
   ^b Function names in all caps
!seealso: "Sample ASM header" "Submitting code for the Library" 
'------------------------------------------------------------------------------



!short: Sample ASM header
'------------------------------------------------------------------------------

^b               This example shows how you would set up
^b                 the headers for an ASM source file.

; File......: ADAPTER.ASM
; Author....: Ted Means
; CIS ID....: 73067,3332
; Date......: $Date$
; Revision..: $Revision$
; Log file..: $Logfile$
;
; This is an original work by Ted Means and is placed in the
; public domain.
;
; Modification history:
; ---------------------
;
; $Log$
;
;
;  $DOC$
;  $FUNCNAME$
;     FT_ADAPTER()
;  $CATEGORY$
;     Video
;  $ONELINER$
;     Report the type of video adapter installed
;  $SYNTAX$
;     FT_ADAPTER() -> nResult
;  $ARGUMENTS$
;     None
;  $RETURNS$
;     0  if monochrome
;     1  if CGA
;     2  if EGA
;     3  if VGA
;  $DESCRIPTION$
;     This function is valuable if you use a graphics library and need to
;     know what type of graphics adapter is installed.
;
;     The source code is written to adhere to Turbo Assembler's IDEAL mode.
;     To use another assembler, you will need to rearrange the PROC and
;     SEGMENT directives, and also the ENDP and ENDS directives (a very
;     minor task).
;  $EXAMPLES$
;     iVideo := FT_ADAPTER()
;
;     DO CASE
;        CASE iVideo == 0
;           Qout( "You have a monochrome adapter." )
;        CASE iVideo == 1
;           Qout( "You have a CGA adapter." )
;        CASE iVideo == 2
;           Qout( "You have an EGA adapter." )
;        CASE iVideo == 3
;           Qout( "You have a VGA adapter." )
;     ENDCASE
;  $INCLUDE$
;     FTVIDEO.CH
;  $SEEALSO$
;     FT_SETMODE()  FT_GETMODE()
;  $END$
;
!seealso: "Sample Clipper or C header" "Submitting code for the Library" 
'------------------------------------------------------------------------------



