Click above to get retro games delivered to your door ever month!

                      THE NANFORUM TOOLKIT (NANFOR.LIB)
            PUBLIC DOMAIN USER SUPPORTED CLIPPER FUNCTION LIBRARY

                                    (part 2)


     5    FUNCTION CODING STANDARDS

          The goal of this standard is not to force anyone to rewrite his
          code for this library, but to create some consistency among the
          functions so that they may more easily maintained and understood
          by all CA-Clipper developers, both novice and advanced.

          However, it is extremely important that anyone submitting code
          attach the proper headers and documentation and fill them out
          correctly.  This will make it much easier for code to be added to
          the library.

          5.1  Required sections for each function

               5.1.1     Header (author name/etc, version ctrl info)

                         Figure 1 shows a header that must be included at
                         the top of every piece of source code submitted to
                         the library.  This header will work with both CA-
                         Clipper and C code.  For ASM code, substitute each
                         asterisk ("*") with a semicolon (";") and delete
                         the slashes ("/").



                                     /*
                                      * File......:
                                      * Author....:
                                      * CIS ID....: x, x
                                      * Date......: $Date$
                                      * Revision..: $Revision$
                                      * Log file..: $Logfile$
                                      *
                                      *
                                      * Modification history:
                                      * ---------------------
                                      *
                                      * $Log$
                                      *
                                      */

                                   Figure 1 - Standard function header.

                         Note that the date, revision, logfile, and
                         modification history fields will be maintained by
                         the librarian and should not be edited or adjusted
                         by code authors.

                         The "File" field shall contain the source file
                         name.  This is often independent of the individual
                         function name.  For example, a function named
                         ft_screen() would be included in SCREEN.PRG.  As a
                         rule, source files (.PRG, .C, .ASM) should not
                         have the "FT" prefix.

                         The "Author" field should have the author's full
                         name, and CIS number.  A CIS number is important,
                         as this will make bug fixing and other
                         correspondence easier.


               5.1.2     Public domain disclaimer

                         Authors shall simply state "This is an original
                         work by [Author's name] and is hereby placed in
                         the public domain."

               5.1.3     Documentation block

                                     /*  $DOC$
                                      *  $FUNCNAME$
                                      *
                                      *  $ONELINER$
                                      *
                                      *  $SYNTAX$
                                      *
                                      *  $ARGUMENTS$
                                      *
                                      *  $RETURNS$
                                      *
                                      *  $DESCRIPTION$
                                      *
                                      *  $EXAMPLES$
                                      *
                                      *  $SEEALSO$
                                      *
                                      *  $INCLUDE$
                                      *
                                      *  $END$
                                      */



                                   Figure 2 - Standard Documentation Header

                         The documentation block must be carefully
                         formatted as it is used by the documenter to
                         produce the Norton Guide documentation for the
                         library.

                         The keywords enclosed in dollar-signs delimit
                         sections of the documentation header analogous to
                         those in the CA-Clipper 5.0 documentation.
                         Documentation should be written in the same style
                         and flavor as the CA material, if possible. Refer
                         to the CA-Clipper documentation for more detail
                         and numerous examples.

                         The documentation will appear on comment lines
                         between the keywords.  Examples are optional.  Do
                         not put documentation on the same line as the
                         comment keyword.

                         Note that the $DOC$ and $END$ keywords serve as
                         delimiters.  Do not place any text between $DOC$
                         and $FUNCNAME$, or any documentation after the
                         $END$ keyword, unless that documentation belongs
                         in the source code file and not in the resultant
                         Norton Guide file.

                         The $FUNCNAME$ keyword should be followed by the
                         function name, with parentheses, and no arguments
                         or syntax, such as:

                              $FUNCNAME$
                                   ft_screen()

                         Note the indent for readability.  Parentheses
                         shall be added after the function name as shown
                         above.

                         The $ONELINER$ keyword should be followed by a
                         simple statement expressing what the function
                         does, phrased in the form of a command, e.g.:

                              $ONELINER$
                                   Sum the values in an array

                         The length of the entire $ONELINER$ shall not
                         exceed 60 characters (this is a Norton Guide
                         limitation).

                         The $SYNTAX$ keyword should be followed by a CA-
                         standard syntax specifier, such as:

                              $SYNTAX$
                                   ft_screen( <nTop> [,<nBottom>] ) -> NIL

                         All parameters have proper prefixes (see paragraph
                         5.4), and are enclosed in <angle brackets>.
                         Optional parameters are enclosed in [square
                         brackets] as well.  An arrow should follow,
                         pointing to the return value.  If there is no
                         return value, it should be NIL.  Any others should
                         be preceded with the proper prefix (see the CA-
                         Clipper documentation).

                         The $SEEALSO$ field provides a way to generate
                         cross-references in the Norton Guide help
                         documentation.  Use it to point the user to other
                         related functions in the forum toolkit.  For
                         example, if ft_func1() is also related to
                         ft_func2() and ft_func3(), the field would look
                         like this:

                              $SEEALSO$
                                   ft_func2() ft_func3()

                         Note that fields are separated by spaces and the
                         parentheses are included.

                         The $INCLUDE$ area allows you to specify what
                         files are included by this function (this will be
                         used to organize the on-line help file, and
                         possibly the master makefile).  An example would
                         be

                              $INCLUDE$
                                   int86.ch int86.inc

                         Other documentation fields should be self-
                         explanatory.  Review the appendix for a sample.
                         All fields are required and must be filled in.
                         Examples should not be considered optional.

               5.1.4     Sample header and documentation block

                         Refer to the Appendix for a sample header and
                         documentation block.

               5.1.5     Test driver

                         A test driver is an optional section of C or CA-
                         Clipper code that will only be compiled under
                         certain circumstances.  Developers are encouraged
                         to include a short "test section" in front of
                         their code.

                         The test driver shall be surrounded by the
                         following pre-processor directives, and placed at
                         the top of the source file:

                              #ifdef FT_TEST
                                   [test code]
                              #endif

                         The test driver is currently optional, but authors
                         submitting CA-Clipper code should seriously
                         consider adding it.  It is a good way to include
                         short demos within a piece of source code, yet pay
                         no penalty because it is only compiled if needed.
                         It will be invoked when a #define is created that
                         says "#define FT_TEST."  This is a way for
                         submitters to include short test routines with
                         their functions and yet keep it all in one source
                         file.  This will be useful to end users.

                         This test driver may become required in a future
                         version of the RFC.

               5.1.6     Code

                         The source code shall be formatted as described in
                         paragraph 5.4.

          5.2  Function names

               All NANFOR.LIB functions start with one of two prefixes. If
               the function is to be called by user programs, then it will
               begin with the prefix

                    FT_      ("F", "T", underscore)

               Note that "FT" is a mnemonic for "Forum Toolkit."  If the
               function is "internal" to a module, then it will be prefixed
               by an underscore:

                    _FT      ( Underscore, "F", "T" )

               with no trailing underscore. Examples:

                    FT_CURDIR()            "external"
                    _ftAlloc()             "internal"

          5.3  Librarian's authority to change function names

               Some functions will be submitted that either (1) bear a
               similar name to another function in the library, or (2) bear
               an inappropriate name.  For example, a function called
               FT_PRINT that writes a character to the screen could be said
               to be named inappropriately, as a name like FT_PRINT implies
               some relationship to a printer.  The librarian shall have
               the responsibility to rename submitted functions for clarity
               and uniqueness.

               5.3.1     Changing a function name after it has been
                         released

                         Once the library is released with a particular
                         function included, then a function name should
                         generally be frozen and not renamed.  To do so
                         would probably cause difficulties with users who
                         had used the previous name and are not tracking
                         the changes to the library.

          5.4  Source code formatting

               5.4.1     CA-Clipper

                         CA-Clipper code shall be formatted in accordance
                         with CA's currently defined publishing standard.
                         Although there will surely be some debate over
                         whether this is a good idea, in general, the goal
                         is to provide something consistent that all CA-
                         Clipper developers will recognize.

                         Minor deviations will be permitted.

                         The CA standard usually means uppercase keywords,
                         and manifest constants, and lower case everything
                         else.

                         In addition, identifiers shall be preceded with
                         the proper metasymbol:

                              n    Numeric
                              c    Character or string
                              a    Array
                              l    Logical, or boolean
                              d    Date
                              m    Memo
                              o    Object
                              b    Code block
                              h    Handle
                              x    Ambiguous type

                         Refer to the CA-Clipper documentation for samples
                         of CA's code publishing format.

               5.4.2     C

                         C source code shall be formatted in a generally
                         accepted way, such as Kernighan and Ritchie's
                         style used in the book _The C Programming
                         Language_."  The use of CA's EXTEND.H is
                         encouraged.

               5.4.3     ASM

                         No particular formatting conventions are required
                         for assembly language source code, since assembly
                         code formatting is fairly standard.  Lowercase
                         code is preferred.  Be sure to include the proper
                         documentation header information, as described
                         above.

                         Do not place ASM code in DGROUP.  See paragraph
                         5.11.

          5.5  Organization into .PRGs

               Since many different people will be submitting routines, it
               is probably best if all routines that belong together are
               housed in the same .PRG.  If there is some reason to split
               the .PRG, the referees and the librarian will handle that as
               part of library organization.

          5.6  Header files

               Including a ".ch" or ".h" or ".inc" file with each function
               would get unwieldy.  For the purpose of NANFOR.LIB, all
               #defines, #ifdefs, #commands, #translates, etc that belong
               to a particular source file shall be included at the top of
               that source file.  Since few submissions will split over
               multiple source files, there will usually be no need to
               #include a header in more than one place.

               If a "ch" file will make the end user's job of supplying
               parameters and other information to NANFOR.LIB functions
               easier, then it shall be submitted as a separate entity.
               The referees will decide on whether to include these
               directives in a master NANFOR.CH file.

          5.7  CA-Clipper 5.0 Lexical Scoping

               NANFOR.LIB routines that are written in CA-Clipper will make
               use of CA-Clipper 5.0's lexical scoping features to insulate
               themselves from the rest of the user's application.

               For example, all "privates" shall generally be declared
               "local."

               If a package of CA-Clipper functions is added to the
               library, then the lower-level, support functions will be
               declared STATIC as necessary.

          5.8  Use of Publics

               Authors shall not use PUBLIC variables in NANFOR.LIB
               functions, due to the potential interference with an
               end-user's application or vice versa.

               If a global is required for a particular function or package
               of functions, that global shall be accessed through a
               function call interface defined by the author (.e.g,
               "ft_setglobal()", "ft_getglobal()", and so on).  Globals
               such as these shall be declared static in the .PRG that
               needs them.

          5.9  Use of Macros ("&" operator)

               The use of macros in NANFOR.LIB functions will be, for the
               most part, unnecessary.  Since this is a CA-Clipper 5.0
               library, the new 5.0 codeblock construct should be used
               instead.  Anyone having trouble figuring out how to convert
               a macro to a codeblock should post suitable questions on the
               CLIPPER forum on CompuServe.

          5.10 Use of Static Functions

               Any CA-Clipper 5.0 function that is only needed within the
               scope of one source file shall be declared STATIC.  This
               applies mostly to NANFOR.LIB "internals" (names with an
               "_ft" prefix) that user programs need not access.

          5.11 Use of DGROUP in ASM Functions

               Use of DGROUP in assembly language functions shall be
               avoided, in accordance with CA's recommendations. Assembly
               functions written for NANFOR.LIB shall use a segment named
               _NanFor, as in the following example:


                    Public    FT_ChDir

                    Extrn     _ftDir:Far

                    Segment   _NanFor   Word      Public    "CODE"
                    Assume    CS:_NanFor

                    Proc      FT_ChDir  Far
                              .
                              .
                              .
                              Ret
                    Endp      FT_ChDir
                    Ends      _NanFor

                    End

          5.12 Use of "Internals"

                    Use of CA-Clipper "internals" by code authors is
                    allowed.  However, should any code make use of an
                    internal, i.e., a function or variable that is not part
                    of the published CA-Clipper API, then that internal
                    shall be clearly marked in the documentation (under
                    "DESCRIPTION") and in the actual code, everywhere the
                    internal is used.

          5.13 Procedures for compiling functions

               5.13.1    CA-Clipper

                         CA-Clipper functions will be compiled under the
                         current release of CA-Clipper 5.0, with the
                         following compiler options:

                              /n /w /l /r

                         Note that neither line numbers nor debugging
                         information will find its way into NANFOR.LIB, to
                         keep the code size down.  End users may recompile
                         NANFOR.LIB with these options enabled if they want
                         to view NANFOR.LIB source in the debugger.

               5.13.2    ASM

                         Assembly functions must compile successfully
                         under any MSDOS assembler capable of producing the
                         proper .OBJ file.  However, care should be taken
                         not to use any macros or special syntax particular
                         to one vendor's assembler, because that would make
                         it difficult for end users to recompile the
                         source.  The preferred assembler is MASM, followed
                         by TASM.

               5.13.3    C

                         C functions must compile successfully under any C
                         compiler capable of interfacing to CA-Clipper.
                         Obviously, Microsoft C, version 5.1, is the
                         preferred development environment.  Care should be
                         taken, when writing C code, not to use any special
                         compiler features particular to one vendor's C
                         compiler, because that would make it difficult for
                         end users to recompile the source.

          5.14 Functions requiring other libraries

               It is very easy to write functions in C that call the
               compiler's standard C library functions.  However,
               NANFOR.LIB can make no assumptions about the end user's
               ability to link in the standard library or any other
               library.  Therefore, no function will be added to
               NANFOR.LIB that requires any other third party or compiler
               manufacturer's library.

     6    ADMINISTRATIVE DETAILS

          6.1  Librarian

               The librarian will be the person who rebuilds the library
               from the sources and uploads the resulting deliverables to
               the proper CLIPPER forum library on CompuServe.  The
               librarian generally does *not* test code or edit source code
               to repair formatting errors.

          6.2  Documenter

               The documenter is responsible for maintaining the  Norton
               and guides and keeping it in sync with each new release.

          6.3  Referees

               Referees are volunteers who read source code, clean it up,
               compile it, look for problems like potentially problematic C
               code, decide on which function is best, consolidate common
               functions, etc.  They make sure the header and documentation
               blocks are present.  There is no election or term for
               refereedom.  One simply performs the task as long as one can
               and bows out when necessary.

          6.4  Transitions

               Not everyone will be able to stay around forever to keep
               working on this project.  Therefore, it is the
               responsibility of each referee, documenter, or librarian to
               announce as far in advance as possible his or her intention
               to leave, in order to give everyone a chance to come up with
               a suitable replacement.  Don't let it die!

     7    CONTRIBUTORS

          Current contributors, directly and indirectly, to this
          document include:

               Don Caton [71067,1350]
               Bill Christison  [72247,3642]
               Robert DiFalco [71610,1705]
               Paul Ferrara  [76702,556]
               David Husnian [76064,1535]
               Ted Means [73067,3332]
               Steve Kolterman [76320,37]
               Alexander Santic [71327,2436]
               Glenn Scott [71620,1521]
               Keith Wire [73760,2427]
               Craig Yellick [76247,541]
               James Zack [75410,1567]