home *** CD-ROM | disk | FTP | other *** search
/ Boston 2 / boston-2.iso / DOS / PROGRAM / CLIPPER / NFTROFF / 15.TR < prev    next >
Text File  |  1993-12-01  |  33KB  |  1,480 lines
  1. .de }n
  2. .bp
  3. .sp .5i
  4. ..
  5. .wh -.8i }n
  6. .sp .5i
  7. .po -.4i
  8. .ll 7.5i
  9. .ps 9
  10. .vs 9
  11. .in 0i
  12. .sp 2
  13. .ne 20
  14. .ps +3
  15. .vs +3
  16. Overview, Part 1
  17. .br
  18. .ps -3
  19. .vs -3
  20. .sp 2
  21. .sp
  22. .in 0.24i
  23. .ta 3.92i
  24. NANFOR\.LIB Working Group    G\. Scott [71620,1521]
  25. .br
  26. .ta
  27. .ta 5.28i
  28. Request for Comments    UCLA
  29. .br
  30. .ta
  31. .ta 4.72i
  32. Version 1\.0    March, 1991
  33. .br
  34. .ta
  35. .sp
  36. .in 1.76i
  37. \fBTHE NANFORUM TOOLKIT (NANFOR\.LIB)
  38. .in 0.96i
  39. \fBPUBLIC DOMAIN USER SUPPORTED CLIPPER FUNCTION LIBRARY
  40. .sp
  41. .in 0.24i
  42. .ta 0.4i
  43. \fB1    INTRODUCTION
  44. .br
  45. .ta
  46. .sp
  47. .in 0.64i
  48. This is a standard for establishing and maintaining NANFOR\.LIB, a
  49. public-domain, user-supported library of functions designed to
  50. interface with Nantucket Clipper, version 5\.0, and later\.  You
  51. are encouraged to read it over and forward comments to Glenn
  52. Scott, CIS ID [71620,1521]\.
  53. .sp
  54. .ta 0.4i
  55. \fB1\.1    History
  56. .br
  57. .ta
  58. .sp
  59. .in 1.04i
  60. In October and November of 1990, a discussion on the
  61. evolution of third-party products, vendors, and marketing
  62. took place on the CompuServe Information Service\'s Nantucket
  63. Forum (NANFORUM)\.  During this discussion, a NANFORUM
  64. subscriber named Alexander Santic suggested the idea of a
  65. user-supported Clipper function library, available to all on
  66. the CompuServe Information Service (CIS)\.  A number of
  67. subscribers, including several Clipper third party
  68. developers, and some Nantucket employees, expressed their
  69. support\. This standard is a first step toward organizing
  70. such an endeavor\.
  71. .sp
  72. .in 0.64i
  73. .ta 0.4i
  74. \fB1\.2    Trademarks
  75. .br
  76. .ta
  77. .sp
  78. .in 1.04i
  79. Clipper is a registered trademark of Nantucket Corporation\.
  80. .sp
  81. .in 0.64i
  82. .ta 0.4i
  83. \fB1\.3    Relationship to Nantucket and third party
  84. .br
  85. .ta
  86. .sp
  87. .in 1.04i
  88. NANFOR\.LIB is a project independent of any third party
  89. developer or Nantucket Corporation\.  There is no official
  90. "sanction" or "seal of approval" from Nantucket of any kind\.
  91. In addition, NANFOR\.LIB routines will be accepted and
  92. included without regard for whether or not routines
  93. performing a similar function are included in a commercial
  94. third party or Nantucket product\.
  95. .sp
  96. It is desired that NANFOR\.LIB not compete with third party
  97. products but rather fill in the holes in Clipper\'s standard
  98. library\.  However, there will be some overlap into
  99. commercial third-party library functions, so it would be
  100. best if this is never taken into consideration when deciding
  101. on including a particular function\.
  102. .sp
  103. Developers submitting NANFOR\.LIB routines can and will be
  104. corporate developers, third party developers, independent
  105. consultant / programmers, hobbyists, and other Clipper
  106. people\.  Perhaps even Nantucket employees will contribute\.
  107. No one is excluded or included due to any particular
  108. affiliation\.
  109. .sp
  110. Nantucket employees submitting functions are doing so as
  111. individuals, and are not making a policy of involving
  112. Nantucket in the project, nor are they committing Nantucket
  113. to supporting the public domain library\.
  114. .sp
  115. .in 0.64i
  116. .ta 0.4i
  117. \fB1\.4    Clipper version supported
  118. .br
  119. .ta
  120. .sp
  121. .in 1.04i
  122. NANFOR\.LIB functions, no matter what language they are
  123. written in, will be designed to work with Clipper version
  124. 5\.0 and later\.  Many of the functions, particularly those
  125. that use the EXTEND system, will be compatible with the
  126. Summer 1987 version of Clipper\. However, ensuring Summer 87
  127. compatibility will be the responsibility of the user\.  If a
  128. user wants a function to work with Summer 87, she will have
  129. to modify the code herself if necessary\.  In many cases,
  130. this is a trivial task\.
  131. .sp
  132. .in 0.64i
  133. .ta 0.4i
  134. \fB1\.5    Queries from new users
  135. .br
  136. .ta
  137. .sp
  138. .in 1.04i
  139. Queries from new users interested in finding NANFOR\.LIB will
  140. be handled in a uniform and courteous way\.  A short text
  141. file will be created that will briefly explain NANFOR\.LIB,
  142. who the current people maintaining it are, and how to get a
  143. hold of it\.  This text message will be sent in response to
  144. any query\.  TAPCIS users will find this method very easy to
  145. implement\.
  146. .sp
  147. .in 0.24i
  148. .ta 0.4i
  149. \fB2    DISTRIBUTION
  150. .br
  151. .ta
  152. .sp
  153. .in 0.64i
  154. .ta 0.4i
  155. \fB2\.1    Public Domain
  156. .br
  157. .ta
  158. .sp
  159. .in 1.04i
  160. NANFOR\.LIB, its source code, and documentation will be
  161. public-domain software\.  It is not for "sale", and shall not
  162. be sold\.  No fee or contribution of any kind will be
  163. required for anyone wanting a copy, other than what they
  164. would normally pay to download it from CompuServe\. Users
  165. will be encouraged to submit functions via CompuServe\.
  166. .sp
  167. .in 0.64i
  168. .ta 0.4i
  169. \fB2\.2    Official repository
  170. .br
  171. .ta
  172. .sp
  173. .in 1.04i
  174. It is possible that copies of NANFOR\.LIB will be downloaded
  175. and distributed elsewhere\.  That is all right, but the only
  176. copy of NANFOR\.LIB and all associated documentation that
  177. will be maintained by volunteers is in an appropriate
  178. library on the CIS Nantucket Forum\.
  179. .sp
  180. .ta 0.8i
  181. \fB2\.2\.1    Contents
  182. .br
  183. .ta
  184. .sp
  185. .in 1.84i
  186. The nature of the official posting on CompuServe
  187. shall be:
  188. .sp
  189. .in 1.44i
  190. .ta 0.8i
  191. 2\.2\.1\.1    NFLIB\.ZIP
  192. .br
  193. .ta
  194. .sp
  195. .in 2.24i
  196. This will contain the files NANFOR\.LIB
  197. (library), and NANFOR\.NG (Norton Guide)\.
  198. .sp
  199. .in 1.44i
  200. .ta 0.8i
  201. 2\.2\.1\.2    NFSRC\.ZIP
  202. .br
  203. .ta
  204. .sp
  205. .in 2.24i
  206. This will contain all the library source
  207. code, makefile, and other source-code related
  208. materials\.
  209. .sp
  210. .in 1.44i
  211. .ta 0.8i
  212. 2\.2\.1\.3    FTINQ\.TXT
  213. .br
  214. .ta
  215. .sp
  216. .in 2.24i
  217. This is a short text file used as a response
  218. to new user queries (see paragraph 1\.5)
  219. .sp
  220. .in 1.44i
  221. .ta 0.8i
  222. 2\.2\.1\.4    NFRFC\.ZIP
  223. .br
  224. .ta
  225. .sp
  226. .in 2.24i
  227. This contains an ASCII copy of NANFOR\.RFC
  228. (this document) named NFRFC\.TXT\.
  229. .sp
  230. .in 1.44i
  231. .ta 0.8i
  232. 2\.2\.1\.5    NFHDRS\.ZIP
  233. .br
  234. .ta
  235. .sp
  236. .in 2.24i
  237. This contains templates of the file and
  238. documentation header blocks, including a
  239. sample, for prospective authors (FTHDR\.PRG,
  240. FTHDR\.ASM, FTHDR\.SAM)
  241. .sp
  242. .sp
  243. .in 0.24i
  244. .ta 0.4i
  245. \fB3    POLICY ON INCLUDING FUNCTIONS
  246. .br
  247. .ta
  248. .sp
  249. .in 0.64i
  250. .ta 0.4i
  251. \fB3\.1    "Best Function"
  252. .br
  253. .ta
  254. .sp
  255. .in 1.04i
  256. It is possible that more than one developer will submit a
  257. function or package of functions that perform substantially
  258. the same services\.  In that event, the referees will choose
  259. one to be included based on power, functionality,
  260. flexibility, and ease of use\.  Due to the cooperative,
  261. non-commercial nature of the library, no one\'s feelings
  262. should be hurt by excluding duplicate functions\.
  263. .sp
  264. In addition, it is possible that two substantially
  265. similar functions or packages will benefit from merging them
  266. together to provide new functionality\.  This will be the
  267. prerogative of the referees (see paragraph 6\.3), in
  268. consultation with the author, if possible\.
  269. .sp
  270. .in 0.64i
  271. .ta 0.4i
  272. \fB3\.2    Public Domain
  273. .br
  274. .ta
  275. .sp
  276. .in 1.04i
  277. .ta 4.56i
  278. Each author submitting source code must include as part    of
  279. .br
  280. .ta
  281. that code a statement that this is an original work and that
  282. he or she is placing the code into the public domain\. The
  283. librarian (see paragraph 6\.1) and referees should make a
  284. reasonable effort to be sure no copyrighted source code,
  285. such as that supplied with some third party libraries, makes
  286. it into NANFOR\.LIB\.  However, under no circumstances will
  287. the librarian, referees, or any other party other than the
  288. submitter be responsible for copyrighted code making it into
  289. the library accidentally\.
  290. .sp
  291. .in 0.64i
  292. .ta 0.4i
  293. \fB3\.3    Source code
  294. .br
  295. .ta
  296. .sp
  297. .in 1.04i
  298. Full source code must be provided by the author for every
  299. routine to be included in NANFOR\.LIB\.  No routine, no matter
  300. what language, will be put into the library on the basis of
  301. submitted object code\.
  302. .sp
  303. .in 0.64i
  304. .ta 0.4i
  305. \fB3\.4    Proper submission
  306. .br
  307. .ta
  308. .sp
  309. .in 1.04i
  310. Due to the volume of submissions expected, librarians and
  311. referees may not have the time to fix inconsistencies in
  312. documentation format, function naming, and other
  313. requirements\.  Therefore, the librarian shall expect source
  314. code to arrive in proper format before proceeding further
  315. with it\.
  316. .sp
  317. .in 0.64i
  318. .ta 0.4i
  319. \fB3\.5    Quality and perceived usefulness
  320. .br
  321. .ta
  322. .sp
  323. .in 1.04i
  324. In a cooperative effort like this, it is very difficult to
  325. enforce some standard of quality and/or usefulness\.  For
  326. example, a package of functions to handle the military\'s
  327. "Zulu time" may be very useful to some, and unnecessary to
  328. others\.
  329. .sp
  330. The Nanforum Toolkit will by its very nature be a hodgepodge
  331. of routines, some of very high quality, some not so high\.
  332. It is up to the users to improve it\.  It will be complete in
  333. some areas and vastly inadequate in others\.  It is up to the
  334. users to fill in the holes\.
  335. .sp
  336. We shall err on the side of including "questionable"
  337. functions, provided they seem to work\.  Debates on the
  338. quality of the library\'s source code shall be encouraged and
  339. will take place in the proper message section of NANFORUM\.
  340. .sp
  341. .in 0.24i
  342. .ta 0.4i
  343. \fB4    LIBRARY MAINTENANCE PROCEDURE
  344. .br
  345. .ta
  346. .sp
  347. .in 0.64i
  348. .ta 0.4i
  349. \fB4\.1    Selection procedure
  350. .br
  351. .ta
  352. .sp
  353. .in 1.04i
  354. Source code will be submitted to the librarian, the
  355. documenter (see paragraph 6\.2), or one of the referees\.
  356. Code will be added if it has been reviewed, and approved by
  357. at least two referees\.
  358. .sp
  359. Code not meeting the documentation or source code formatting
  360. standards will generally be returned to the author with
  361. instructions\.
  362. .sp
  363. .ta 4.4i
  364. When the referees have finished selecting a function,    they
  365. .br
  366. .ta
  367. will compile it and submit both source and \.OBJ to the
  368. librarian who shall add the \.OBJ(s) into the library\.
  369. .sp
  370. Every effort should be made to make sure that the C and ASM
  371. functions are reviewed by referees with suitable C and ASM
  372. experience\.
  373. .sp
  374. .in 0.64i
  375. .ta 0.4i
  376. \fB4\.2    Update interval
  377. .br
  378. .ta
  379. .sp
  380. .in 1.04i
  381. As new functions are submitted, they will added to the
  382. library, and the documentation updated\.  However, the
  383. library will only be updated at a fixed interval\.
  384. .sp
  385. This interval is currently set at: QUARTERLY\.  After the
  386. initial release, updates occur on or around April 1, July 1,
  387. October 1, January 1, etc\.  Of course, these dates are never
  388. guaranteed, and there is always an honorary release date of
  389. September 15, which will always be missed\.
  390. .sp
  391. If there are some very important functions that have been
  392. added, and the next update interval is, say, two months
  393. away, the librarian, documenter, and referees will release a
  394. maintenance update anyway, regardless of update intervals\.
  395. .sp
  396. .in 0.64i
  397. .ta 0.4i
  398. \fB4\.3    Version control
  399. .br
  400. .ta
  401. .sp
  402. .in 1.04i
  403. NANFOR\.LIB will use a numeric version number as follows:
  404. .sp
  405. .ta 4.4i
  406. The major version will be numeric, starting from 1\.    This
  407. .br
  408. .ta
  409. will change with each quarterly update\.  The minor version
  410. .ta 3.92i
  411. will change with each bug fix\.  This will start    with zero
  412. .br
  413. .ta
  414. and continue until the next major update, at which point it
  415. will revert to zero again\.
  416. .sp
  417. Typical version numbers might be 1\.1, 2\.12, 15\.2, etc\.
  418. .sp
  419. The \.LIB file, and all associated files, will carry a
  420. day/time stamp of the first day of the particular release\'s
  421. quarter, 12:00am\.
  422. .sp
  423. .in 0.64i
  424. .ta 0.4i
  425. \fB4\.4    Announcing updates
  426. .br
  427. .ta
  428. .sp
  429. .in 1.04i
  430. As the library and its associated documentation are updated,
  431. simple announcements will be posted on NANFORUM\.  This is
  432. the only place where an update shall be announced\.  An
  433. update will be announced after it has been successfully
  434. uploaded to the appropriate library on CompuServe\.
  435. .sp
  436. .in 0.64i
  437. .ta 0.4i
  438. \fB4\.5    Bug reports and fixes
  439. .br
  440. .ta
  441. .sp
  442. .in 1.04i
  443. The librarian will correlate and verify all bug reports,
  444. with the help of the referees\.  If the referees believe a
  445. bug to be serious, they will fix it and the librarian will
  446. release a maintenance upgrade immediately\.  If they consider
  447. it a minor bug, they will fix it but wait for the next
  448. scheduled upgrade to release it\.  In this case, a bug fix
  449. may be released as a "Patch\."
  450. .sp
  451. .ta 0.8i
  452. \fB4\.5\.1    Patches
  453. .br
  454. .ta
  455. .sp
  456. .in 1.84i
  457. A "patch" is simply an ASCII text file containing
  458. instructions for editing the source code to a
  459. misbehaving function or group of functions\.
  460. Patches may appear in the CIS library before a
  461. maintenance release or quarterly upgrade\.  A patch
  462. file will have a name of the form
  463. .sp
  464. .in 2.24i
  465. PATn\.ZIP
  466. .sp
  467. .in 1.84i
  468. where <n> is a number starting from 1\.  Patches
  469. will be numbered sequentially\. Patches will be
  470. deleted every time a new version of NANFOR\.LIB
  471. goes on-line\.
  472. .sp
  473. A patch zipfile may optionally contain \.OBJ files
  474. to be replaced in user libraries via a LIB
  475. utility\.
  476. .sp
  477. .in 0.64i
  478. .ta 0.4i
  479. \fB4\.6    Technical Support
  480. .br
  481. .ta
  482. .sp
  483. .in 1.04i
  484. Technical support will work just as any technical subject on
  485. NANFORUM works\.  Users will post questions and suggestions
  486. .ta 3.28i
  487. to a particular message area or thread,    and anyone who
  488. .br
  489. .ta
  490. knows the answer should respond\.  No one is obliged to
  491. answer, but it is considered good form to respond with
  492. something, even if one doesn\'t know the answer\.
  493. .sp
  494. Support will include help on recompiling the routines or
  495. modifying the source\.
  496. .sp
  497. .in 0.64i
  498. .ta 0.4i
  499. \fB4\.7    Linker Compatibility
  500. .br
  501. .ta
  502. .sp
  503. .in 1.04i
  504. In order to assist users of Clipper third party linkers
  505. (such as WarpLink or Blinker), NANFOR\.LIB may need to broken
  506. up into root and overlay sections\.  How this will be done
  507. will be determined when splitting becomes necessary\.
  508. .sp
  509. .in 0.64i
  510. .ta 0.4i
  511. \fB4\.8    Splitting NANFOR\.LIB by functional category
  512. .br
  513. .ta
  514. .sp
  515. .in 1.04i
  516. It is possible that at some future date, it will make sense
  517. to split NANFOR\.LIB into separate functional areas (e\.g\.,
  518. video routines vs\. date routines, etc)\.  This RFC will be
  519. modified accordingly should that need arise\.
  520. .sp
  521. .in 2.24i
  522. \fB(continued in part 2\.\.\.)
  523. .in 0i
  524. .sp
  525. .in 1.5i
  526. .ti -1.5i
  527. .ta 1.5i
  528. .ft B
  529. See Also:    
  530. .ft R
  531. Overview, Part 2
  532. .ta
  533. .in 0i
  534. .sp 2
  535. .ne 20
  536. .ps +3
  537. .vs +3
  538. Overview, Part 2
  539. .br
  540. .ps -3
  541. .vs -3
  542. .sp 2
  543. .sp
  544. .in 1.76i
  545. \fBTHE NANFORUM TOOLKIT (NANFOR\.LIB)
  546. .in 0.96i
  547. \fBPUBLIC DOMAIN USER SUPPORTED CLIPPER FUNCTION LIBRARY
  548. .sp
  549. .in 2.88i
  550. (part 2)
  551. .sp
  552. .sp
  553. .in 0.24i
  554. .ta 0.4i
  555. \fB5    FUNCTION CODING STANDARDS
  556. .br
  557. .ta
  558. .sp
  559. .in 0.64i
  560. The goal of this standard is not to force anyone to rewrite his
  561. code for this library, but to create some consistency among the
  562. functions so that they may more easily maintained and understood
  563. by all Clipper developers, both novice and advanced\.
  564. .sp
  565. However, it is extremely important that anyone submitting code
  566. attach the proper headers and documentation and fill them out
  567. correctly\.  This will make it much easier for code to be added to
  568. the library\.
  569. .sp
  570. .ta 0.4i
  571. \fB5\.1    Required sections for each function
  572. .br
  573. .ta
  574. .sp
  575. .in 1.04i
  576. .ta 0.8i
  577. \fB5\.1\.1    Header (author name/etc, version ctrl info)
  578. .br
  579. .ta
  580. .sp
  581. .in 1.84i
  582. Figure 1 shows a header that must be included at
  583. the top of every piece of source code submitted to
  584. the library\.  This header will work with both
  585. Clipper and C code\.  For ASM code, substitute each
  586. asterisk ("*") with a semicolon (";") and delete
  587. the slashes ("/")\.
  588. .sp
  589. .sp
  590. .in 2.8i
  591. .br
  592. /*
  593. .in 2.88i
  594. .br
  595. * File\.\.\.\.\.\.:
  596. .br
  597. * Author\.\.\.\.:
  598. .br
  599. * CIS ID\.\.\.\.:
  600. .br
  601. * Date\.\.\.\.\.\.: $Date$
  602. .br
  603. * Revision\.\.: $Revision$
  604. .br
  605. * Log file\.\.: $Logfile$
  606. .br
  607. *
  608. .br
  609. *
  610. .br
  611. * Modification history:
  612. .br
  613. * ---------------------
  614. .br
  615. *
  616. .br
  617. * $Log$
  618. .br
  619. *
  620. .br
  621. */
  622. .sp
  623. .in 2.64i
  624. Figure 1 - Standard function header
  625. .sp
  626. .in 1.84i
  627. Note that the date, revision, logfile, and
  628. modification history fields will be maintained by
  629. the librarian and should not be edited or adjusted
  630. by code authors\.
  631. .sp
  632. The "File" field shall contain the source file
  633. name\.  This is often independent of the individual
  634. function name\.  For example, a function named
  635. ft_screen() would be included in SCREEN\.PRG\.  As a
  636. rule, source files (\.PRG, \.C, \.ASM) should not
  637. have the "FT" prefix\.
  638. .sp
  639. The "Author" field should have the author\'s full
  640. name, and CIS number\.  A CIS number is important,
  641. as this will make bug fixing and other
  642. correspondence easier\.
  643. .sp
  644. .sp
  645. .in 1.04i
  646. .ta 0.8i
  647. \fB5\.1\.2    Public domain disclaimer
  648. .br
  649. .ta
  650. .sp
  651. .in 1.84i
  652. Authors shall simply state "This is an original
  653. work by [Author\'s name] and is hereby placed in
  654. the public domain\."
  655. .sp
  656. .in 1.04i
  657. .ta 0.8i
  658. \fB5\.1\.3    Documentation block ( for \.DOC, \.NG, \.TRH )
  659. .br
  660. .ta
  661. .sp
  662. .in 2.8i
  663. .ta 0.32i
  664. .br
  665. /*    $DOC$
  666. .br
  667. .ta
  668. .in 2.88i
  669. .ta 0.24i
  670. .br
  671. *    $FUNCNAME$
  672. .br
  673. .ta
  674. .br
  675. *
  676. .ta 0.24i
  677. .br
  678. *    $ONELINER$
  679. .br
  680. .ta
  681. .br
  682. *
  683. .ta 0.24i
  684. .br
  685. *    $SYNTAX$
  686. .br
  687. .ta
  688. .br
  689. *
  690. .ta 0.24i
  691. .br
  692. *    $ARGUMENTS$
  693. .br
  694. .ta
  695. .br
  696. *
  697. .ta 0.24i
  698. .br
  699. *    $RETURNS$
  700. .br
  701. .ta
  702. .br
  703. *
  704. .ta 0.24i
  705. .br
  706. *    $DESCRIPTION$
  707. .br
  708. .ta
  709. .br
  710. *
  711. .ta 0.24i
  712. .br
  713. *    $EXAMPLES$
  714. .br
  715. .ta
  716. .br
  717. *
  718. .ta 0.24i
  719. .br
  720. *    $INCLUDE$
  721. .br
  722. .ta
  723. .br
  724. *
  725. .ta 0.24i
  726. .br
  727. *    $SEEALSO$
  728. .br
  729. .ta
  730. .br
  731. *
  732. .ta 0.24i
  733. .br
  734. *    $END$
  735. .br
  736. .ta
  737. .br
  738. */
  739. .sp
  740. .sp
  741. .sp
  742. .in 2.64i
  743. Figure 2 - Standard Documentation Header
  744. .sp
  745. .in 1.84i
  746. The keywords enclosed in dollar-signs delimit
  747. sections of the documentation header analagous to
  748. those in Nantucket\'s Clipper 5\.0 documentation\.
  749. Documentation should be written in the same style
  750. and flavor as the Nantucket material, if possible\.
  751. Refer to the Clipper documentation for more detail
  752. and numerous examples\.
  753. .sp
  754. The documentation will appear on comment lines
  755. between the keywords\.  Examples are optional\.  Do
  756. not put documentation on the same line as the
  757. comment keyword\.
  758. .sp
  759. Note that the $DOC$ and $END$ keywords serve as
  760. delimiters\.  Do not place any text between $DOC$
  761. and $FUNCNAME$, or any documentation after the
  762. $END$ keyword, unless that documentation belongs
  763. in the source code file and not in the NG/TRH
  764. file\.
  765. .sp
  766. The $FUNCNAME$ keyword should be followed by the
  767. function name, with parentheses, and no arguments
  768. or syntax, such as:
  769. .sp
  770. .in 2.24i
  771. .br
  772. $FUNCNAME$
  773. .in 2.56i
  774. .br
  775. FT_SCREEN()
  776. .sp
  777. .in 1.84i
  778. or in the case of commands:
  779. .sp
  780. .in 2.24i
  781. .br
  782. $FUNCNAME$
  783. .in 2.56i
  784. .br
  785. @\.\.\.PROMPT
  786. .sp
  787. .in 1.84i
  788. Note the indent for readibility\.  The function or
  789. command name shall be in all caps and parentheses
  790. shall be added after the function name as shown
  791. above\.
  792. .sp
  793. The $ONELINER$ keyword should be followed by a
  794. simple statement expressing what the function
  795. does, phrased in the form of a command, e\.g\.:
  796. .sp
  797. .in 2.24i
  798. $ONELINER$
  799. .in 2.56i
  800. Sum the values in an array
  801. .sp
  802. .in 1.84i
  803. The length of the entire $ONELINER$ shall not
  804. exceed 60 characters (this is a Norton Guide
  805. limitation)\.
  806. .sp
  807. The $SYNTAX$ keyword should be followed by a
  808. Nantucket-standard syntax specifier, such as:
  809. .sp
  810. .in 2.24i
  811. .br
  812. $SYNTAX$
  813. .in 2.56i
  814. .br
  815. FT_SCREEN( <nTop> [,<nBottom>] ) -> NIL
  816. .sp
  817. .in 1.84i
  818. All parameters have proper prefixes (see paragraph
  819. 5\.4), and are enclosed in <angle brackets>\.
  820. Optional parameters are enclosed in [square
  821. brackets] as well\.  An arrow should follow,
  822. pointing to the return value\.  If there is no
  823. return value, it should be NIL\.  Any others should
  824. be preceded with the proper prefix (see the
  825. Clipper documentation)\.
  826. .sp
  827. The $INCLUDE$ field is for the name of a Clipper
  828. "\.CH" header file that contains preprocessor
  829. directives for use with this command or function\.
  830. If no header file is needed, leave this field
  831. blank\.
  832. .sp
  833. Please indicate in your description and examples
  834. if this file is mandantory (in the case of commands)
  835. or optional\.
  836. .sp
  837. Note that header files that are used only in the
  838. compilation of the library function itself should
  839. NOT be included in this field\.
  840. .sp
  841. The $SEEALSO$ field provides a way to generate
  842. cross-references in the Norton Guide help
  843. documentation\.  Use it to point the user to other
  844. related functions in the forum toolkit\.  For
  845. example, if FT_FUNC1() is also related to
  846. FT_FUNC2() and FT_FUNC3(), the field would look
  847. like this:
  848. .sp
  849. .in 2.24i
  850. $SEEALSO$
  851. .in 2.56i
  852. FT_FUNC2() FT_FUNC3()
  853. .sp
  854. .in 1.84i
  855. Note that function names are in all CAPS the
  856. parenthesis are included, and each funation name
  857. is seperated by a single space\.
  858. .sp
  859. Other documenation fields should be self-
  860. explanatory\.  Review the appendix for a sample\.
  861. All fields are required and must be filled in\.
  862. Examples should not be considered optional\.
  863. .sp
  864. .in 1.04i
  865. .ta 0.8i
  866. \fB5\.1\.4    Sample header and documentation block
  867. .br
  868. .ta
  869. .sp
  870. .in 1.84i
  871. Refer to the Appendix for a sample header and
  872. documentation block\.
  873. .sp
  874. .in 1.04i
  875. .ta 0.8i
  876. \fB5\.1\.5    Test driver
  877. .br
  878. .ta
  879. .sp
  880. .in 1.84i
  881. A test driver is an optional section of C or
  882. Clipper code that will only be compiled under
  883. certain circumstances\.  Developers are encouraged
  884. to include a short "test section" in front of
  885. their code\.
  886. .sp
  887. The test driver shall be surrounded by the
  888. following pre-processor directives, and placed at
  889. the top of the source file:
  890. .sp
  891. .in 2.24i
  892. .br
  893. #ifdef FT_TEST
  894. .in 2.64i
  895. .br
  896. [test code]
  897. .in 2.24i
  898. .br
  899. #endif
  900. .sp
  901. .in 1.84i
  902. The test driver is currently optional, but authors
  903. submitting Clipper code should seriously consider
  904. adding it\.  It is a good way to include short
  905. demos within a piece of source code, yet pay no
  906. penalty because it is only compiled if needed\.  It
  907. will be invoked when a #define is created that
  908. .ta 2i
  909. says "#define FT_TEST\."    This is a way for
  910. .br
  911. .ta
  912. submitters to include short test routines with
  913. their functions and yet keep it all in one source
  914. file\.  This will be useful to end users\.
  915. .sp
  916. This test driver may become required in a future
  917. version of the RFC\.
  918. .sp
  919. .in 1.04i
  920. .ta 0.8i
  921. \fB5\.1\.6    Code
  922. .br
  923. .ta
  924. .sp
  925. .in 1.84i
  926. The source code shall be formatted as described in
  927. paragraph 5\.4\.
  928. .sp
  929. .in 0.64i
  930. .ta 0.4i
  931. \fB5\.2    Function names
  932. .br
  933. .ta
  934. .sp
  935. .in 1.04i
  936. All NANFOR\.LIB functions start with one of two prefixes\. If
  937. the function is to be called by user programs, than it will
  938. begin with the prefix
  939. .sp
  940. .in 1.44i
  941. .ta 0.72i
  942. FT_    ("F", "T", underscore)
  943. .br
  944. .ta
  945. .sp
  946. .in 1.04i
  947. .ta 4.08i
  948. Note that "FT" is a mnemonic for "Forum Toolkit\."    If the
  949. .br
  950. .ta
  951. function is "internal" to a module, then it will be prefixed
  952. by an underscore:
  953. .sp
  954. .in 1.44i
  955. .ta 0.72i
  956. _FT    ( Underscore, "F", "T" )
  957. .br
  958. .ta
  959. .sp
  960. .in 1.04i
  961. with no trailing underscore\. Examples:
  962. .sp
  963. .in 1.44i
  964. .ta 1.84i
  965. .br
  966. FT_CURDIR()    "external"
  967. .br
  968. .ta
  969. .ta 1.84i
  970. .br
  971. _ftAlloc()    "internal"
  972. .br
  973. .ta
  974. .sp
  975. .in 0.64i
  976. .ta 0.4i
  977. \fB5\.3    Librarian\'s authority to change function names
  978. .br
  979. .ta
  980. .sp
  981. .in 1.04i
  982. Some functions will be submitted that either (1) bear a
  983. similar name to another function in the library, or (2) bear
  984. an inappropriate name\.  For example, a function called
  985. FT_PRINT that writes a character to the screen could be said
  986. to be named inappropriately, as a name like FT_PRINT implies
  987. some relationship to a printer\.  The librarian shall have
  988. the responsibility to rename submitted functions for clarity
  989. and uniqueness\.
  990. .sp
  991. .ta 0.8i
  992. \fB5\.3\.1    Changing a function name after it has been
  993. .br
  994. .ta
  995. .in 1.84i
  996. released
  997. .sp
  998. Once the library is released with a particular
  999. function included, then a function name should
  1000. generally be frozen and not renamed\.  To do so
  1001. would probably cause difficulties with users who
  1002. had used the previous name and are not tracking
  1003. the changes to the library\.
  1004. .sp
  1005. .in 0.64i
  1006. .ta 0.4i
  1007. \fB5\.4    Source code formatting
  1008. .br
  1009. .ta
  1010. .sp
  1011. .in 1.04i
  1012. .ta 0.8i
  1013. \fB5\.4\.1    Clipper
  1014. .br
  1015. .ta
  1016. .sp
  1017. .in 1.84i
  1018. Clipper code shall be formatted in accordance with
  1019. Nantucket\'s currently defined publishing standard\.
  1020. Although there will surely be some debate over
  1021. whether this is a good idea, in general, the goal
  1022. is to provide something consistent that all
  1023. Clipper developers will recognize\.
  1024. .sp
  1025. Minor deviations will be permitted\.
  1026. .sp
  1027. The Nantucket standard usually means uppercase
  1028. keywords, and manifest constants, and lower case
  1029. everything else\.
  1030. .sp
  1031. In addition, identifiers shall be preceded with
  1032. the proper metasymbol:
  1033. .sp
  1034. .in 2.24i
  1035. .ta 0.4i
  1036. n    Numeric
  1037. .br
  1038. .ta
  1039. .ta 0.4i
  1040. c    Character or string
  1041. .br
  1042. .ta
  1043. .ta 0.4i
  1044. a    Array
  1045. .br
  1046. .ta
  1047. .ta 0.4i
  1048. l    Logical, or boolean
  1049. .br
  1050. .ta
  1051. .ta 0.4i
  1052. d    Date
  1053. .br
  1054. .ta
  1055. .ta 0.4i
  1056. m    Memo
  1057. .br
  1058. .ta
  1059. .ta 0.4i
  1060. o    Object
  1061. .br
  1062. .ta
  1063. .ta 0.4i
  1064. b    Code block
  1065. .br
  1066. .ta
  1067. .ta 0.4i
  1068. h    Handle
  1069. .br
  1070. .ta
  1071. .ta 0.4i
  1072. x    Ambiguous type
  1073. .br
  1074. .ta
  1075. .sp
  1076. .in 1.84i
  1077. Refer to the Clipper documentation for samples of
  1078. Nantucket\'s code publishing format\.
  1079. .sp
  1080. .in 1.04i
  1081. .ta 0.8i
  1082. \fB5\.4\.2    C
  1083. .br
  1084. .ta
  1085. .sp
  1086. .in 1.84i
  1087. C source code shall be formatted in a generally
  1088. accepted way, such as Kernighan and Ritchie\'s
  1089. style used in the book _The C Programming
  1090. .ta 1.04i
  1091. Language_\."    The use of Nantucket\'s EXTEND\.H is
  1092. .br
  1093. .ta
  1094. encouraged\.
  1095. .sp
  1096. .in 1.04i
  1097. .ta 0.8i
  1098. \fB5\.4\.3    ASM
  1099. .br
  1100. .ta
  1101. .sp
  1102. .in 1.84i
  1103. No particular formatting conventions are required
  1104. for assembly language source code, since assembly
  1105. code formatting is fairly standard\.  Lowercase
  1106. code is preferred\.  Be sure to include the proper
  1107. documentation header information, as described
  1108. above\.
  1109. .sp
  1110. Do not place ASM code in DGROUP\.  See paragraph
  1111. 5\.12\.
  1112. .sp
  1113. .in 0.64i
  1114. .ta 0.4i
  1115. \fB5\.5    Organization into \.PRGs
  1116. .br
  1117. .ta
  1118. .sp
  1119. .in 1.04i
  1120. Since many different people will be submitting routines, it
  1121. is probably best if all routines that belong together are
  1122. housed in the same \.PRG\.  If there is some reason to split
  1123. the \.PRG, the referees and the librarian will handle that as
  1124. part of library organization\.
  1125. .sp
  1126. .in 0.64i
  1127. .ta 0.4i
  1128. \fB5\.6    Header files
  1129. .br
  1130. .ta
  1131. .sp
  1132. .in 1.04i
  1133. Including a "\.ch" or "\.h" or "\.inc" with each function would
  1134. get unwieldy\.  For the purpose of NANFOR\.LIB, all #defines,
  1135. #ifdefs, #commands, #translates, etc that belong to a
  1136. particular source file shall be included at the top of that
  1137. source file\.  Since few submissions will split over multiple
  1138. source files, there will usually be no need to #include a
  1139. header in more than one place\.
  1140. .sp
  1141. If a "ch" file will make the end user\'s job of supplying
  1142. parameters and other information to NANFOR\.LIB functions
  1143. easier, then it shall be submitted as a separate entity\.
  1144. The referees will decide on whether to include these
  1145. directives in a master NANFOR\.CH file\.
  1146. .sp
  1147. .in 0.64i
  1148. .ta 0.4i
  1149. \fB5\.7    Clipper 5\.0 Lexical Scoping
  1150. .br
  1151. .ta
  1152. .sp
  1153. .in 1.04i
  1154. NANFOR\.LIB routines that are written in Clipper will make
  1155. use of Clipper 5\.0\'s lexical scoping features to insulate
  1156. themselves from the rest of the user\'s application\.
  1157. .sp
  1158. For example, all "privates" shall generally be declared
  1159. "local\."
  1160. .sp
  1161. If a package of Clipper functions is added to the library,
  1162. then the lower-level, support functions will be declared
  1163. STATIC as necessary\.
  1164. .sp
  1165. .in 0.64i
  1166. .ta 0.4i
  1167. \fB5\.8    Use of Publics
  1168. .br
  1169. .ta
  1170. .sp
  1171. .in 1.04i
  1172. Authors shall not use PUBLIC variables in NANFOR\.LIB
  1173. functions, due to the potential interference with an
  1174. end-user\'s application or vice versa\.
  1175. .sp
  1176. If a global is required for a particular function or package
  1177. of functions, that global shall be accessed through a
  1178. function call interface defined by the author (\.e\.g,
  1179. "ft_setglobal()", "ft_getglobal()", and so on)\.  Globals
  1180. such as this shall be declared static in the \.PRG that needs
  1181. them\.
  1182. .sp
  1183. .in 0.64i
  1184. .ta 0.4i
  1185. \fB5\.9    Use of Macros ("&" operator)
  1186. .br
  1187. .ta
  1188. .sp
  1189. .in 1.04i
  1190. The use of macros in NANFOR\.LIB functions will be, for the
  1191. most part, unnecessary\.  Since this is a Clipper 5\.0
  1192. library, the new 5\.0 codeblock construct should be used
  1193. instead\.  Anyone having trouble figuring out how to convert
  1194. a macro to a codeblock should post suitable questions on
  1195. NANFORUM\.
  1196. .sp
  1197. .in 0.64i
  1198. \fB5\.10 Use of Static Functions
  1199. .sp
  1200. .in 1.04i
  1201. Any Clipper 5\.0 function that is only needed within the
  1202. scope of one source file shall be declared STATIC\.  This
  1203. applies mostly to NANFOR\.LIB "internals" (names with an
  1204. "_ft" prefix) that user programs need not access\.
  1205. .sp
  1206. .in 0.64i
  1207. \fB5\.11 Use of SPI_ interface
  1208. .sp
  1209. .in 1.04i
  1210. A common library of low-level routines that are useful in C
  1211. and assembler functions, called the "Shared Programming
  1212. Interface", shall be used as a practical alternative to a
  1213. compiler\'s standard library, where applicable\.  These
  1214. functions were developed by Dirk Lesko and a consortium of
  1215. third party developers to help reduce the amount of
  1216. duplicated code pulled in by multiple libraries\.
  1217. .sp
  1218. SPI\.LIB, including its source, is available as a separate
  1219. library and will always be posted wherever NANFOR\.LIB is
  1220. posted\.
  1221. .sp
  1222. Use of SPI\.LIB will be required if and only if SPI\.LIB is
  1223. widely available in source code form so that authors may see
  1224. what functions need not be duplicated\.
  1225. .sp
  1226. .in 0.64i
  1227. \fB5\.12 Use of DGROUP in ASM Functions
  1228. .sp
  1229. .in 1.04i
  1230. Use of DGROUP in assembly language functions shall be
  1231. avoided, in accordance with Nantucket\'s recommendations\.
  1232. Assembly functions written for NANFOR\.LIB shall use a
  1233. segment named _NanFor, as in the following example:
  1234. .sp
  1235. .sp
  1236. .in 1.44i
  1237. .ta 0.8i
  1238. .br
  1239. Public    FT_ChDir
  1240. .br
  1241. .ta
  1242. .sp
  1243. .ta 0.8i
  1244. .br
  1245. Extrn    _ftDir:Far
  1246. .br
  1247. .ta
  1248. .sp
  1249. .ta 0.8i 1.6i 2.4i 3.2i
  1250. .br
  1251. Segment    _NanFor    Word    Public    "CODE"
  1252. .br
  1253. .ta
  1254. .ta 0.8i
  1255. .br
  1256. Assume    CS:_NanFor
  1257. .br
  1258. .ta
  1259. .sp
  1260. .ta 0.8i 1.6i
  1261. .br
  1262. Proc    FT_ChDir    Far
  1263. .br
  1264. .ta
  1265. .in 2.24i
  1266. .br
  1267. \.
  1268. .br
  1269. \.
  1270. .br
  1271. \.
  1272. .br
  1273. Ret
  1274. .in 1.44i
  1275. .ta 0.8i
  1276. .br
  1277. Endp    FT_ChDir
  1278. .br
  1279. .ta
  1280. .sp
  1281. .ta 0.8i
  1282. .br
  1283. Ends    _NanFor
  1284. .br
  1285. .ta
  1286. .br
  1287. End
  1288. .sp
  1289. .in 0.64i
  1290. \fB5\.13 Use of "Internals"
  1291. .sp
  1292. .in 1.44i
  1293. Use of Nantucket "internals" by code authors is
  1294. allowed\.  However, should any code make use of an
  1295. internal, i\.e\., a function or variable that is not part
  1296. of the published Clipper API, then that internal shall
  1297. be clearly marked in the documentation (under
  1298. "DESCRIPTION") and in the actual code, everywhere the
  1299. internal is used\.
  1300. .sp
  1301. .in 0.64i
  1302. \fB5\.14 Procedures for compiling functions
  1303. .sp
  1304. .in 1.04i
  1305. .ta 0.8i
  1306. \fB5\.14\.1    Clipper
  1307. .br
  1308. .ta
  1309. .sp
  1310. .in 1.84i
  1311. Clipper functions will be compiled under the
  1312. current release of Clipper 5\.0, with the following
  1313. compiler options:
  1314. .sp
  1315. .in 2.24i
  1316. /n /w /l
  1317. .sp
  1318. .in 1.84i
  1319. Note that neither line numbers nor debugging
  1320. information will find its way into NANFOR\.LIB, to
  1321. keep the code size down\.  End users may recompile
  1322. NANFOR\.LIB with these options enabled if they want
  1323. to view NANFOR\.LIB source in the debugger\.
  1324. .sp
  1325. .in 1.04i
  1326. .ta 0.8i
  1327. \fB5\.14\.2    ASM
  1328. .br
  1329. .ta
  1330. .sp
  1331. .in 1.84i
  1332. Assembly functions must compile successfully
  1333. under any MSDOS assembler capable of producing the
  1334. proper \.OBJ file\.  However, care should be taken
  1335. not to use any macros or special syntax particular
  1336. to one vendor\'s assembler, because that would make
  1337. it difficult for end users to recompile the
  1338. source\.
  1339. .sp
  1340. .in 1.04i
  1341. .ta 0.8i
  1342. \fB5\.14\.3    C
  1343. .br
  1344. .ta
  1345. .sp
  1346. .in 1.84i
  1347. C functions must compile successfully under any C
  1348. compiler capable of interfacing to Clipper\.
  1349. Obviously, Microsoft C, version 5\.1, is the
  1350. preferred development environment\.  Care should be
  1351. taken, when writing C code, not to use any special
  1352. compiler features particular to one vendor\'s C
  1353. compiler, because that would make it difficult for
  1354. end users to recompile the source\.
  1355. .sp
  1356. .in 0.64i
  1357. \fB5\.15 Functions requiring other libraries
  1358. .sp
  1359. .in 1.04i
  1360. It is very easy to write functions in C that call the
  1361. compiler\'s standard C library functions\.  However,
  1362. NANFOR\.LIB can make no assumptions about the end user\'s
  1363. ability to link in the standard library or any other
  1364. library\.  Therefore, no function will be added to
  1365. NANFOR\.LIB that requires any other third party or compiler
  1366. manufacturer\'s library, except for SPI\.LIB, described above\.
  1367. .sp
  1368. .in 0.24i
  1369. .ta 0.4i
  1370. \fB6    ADMINISTRATIVE DETAILS
  1371. .br
  1372. .ta
  1373. .sp
  1374. .in 0.64i
  1375. .ta 0.4i
  1376. \fB6\.1    Librarian
  1377. .br
  1378. .ta
  1379. .sp
  1380. .in 1.04i
  1381. The librarian will the person who physically creates the
  1382. library via a library utility and uploads it to the proper
  1383. NANFORUM library on CompuServe\.  The librarian generally
  1384. does *not* test code or edit source code to repair
  1385. formatting errors\.
  1386. .sp
  1387. .in 0.64i
  1388. .ta 0.4i
  1389. \fB6\.2    Documenter
  1390. .br
  1391. .ta
  1392. .sp
  1393. .in 1.04i
  1394. .ta 4.08i
  1395. The documenter is responsible for maintaining the    Norton
  1396. .br
  1397. .ta
  1398. and/or Tom Rettig guides and keeping it in sync with each
  1399. new release\.
  1400. .sp
  1401. .in 0.64i
  1402. .ta 0.4i
  1403. \fB6\.3    Referees
  1404. .br
  1405. .ta
  1406. .sp
  1407. .in 1.04i
  1408. Referees are volunteers who read source code, clean it up,
  1409. compile it, look for problems like potentially problematic C
  1410. code, decide on which function is best, consolidate common
  1411. functions, etc\.  They make sure the header and documentation
  1412. blocks are present\.  There is no election or term for
  1413. refereedom\.  One simply performs the task as long as one can
  1414. and bows out when necessary\.
  1415. .sp
  1416. .in 0.64i
  1417. .ta 0.4i
  1418. \fB6\.4    Transitions
  1419. .br
  1420. .ta
  1421. .sp
  1422. .in 1.04i
  1423. Not everyone will be able to stay around forever to keep
  1424. working on this project\.  Therefore, it is the
  1425. responsibility of each referee, documenter, or librarian to
  1426. announce as far in advance as possible his or her intention
  1427. to leave, in order to give everyone a chance to come up with
  1428. a suitable replacement\.  Don\'t let it die!
  1429. .sp
  1430. .in 0.24i
  1431. .ta 0.4i
  1432. \fB7    CONTRIBUTORS
  1433. .br
  1434. .ta
  1435. .sp
  1436. .in 0.64i
  1437. Current contributors, directly and indirectly, to this
  1438. document include:
  1439. .sp
  1440. .in 1.04i
  1441. .br
  1442. Don Caton [71067,1350]
  1443. .ta 1.36i
  1444. .br
  1445. Bill Christison    [72247,3642]
  1446. .br
  1447. .ta
  1448. .br
  1449. Robert DiFalco [71610,1705]
  1450. .ta 1.12i
  1451. .br
  1452. Paul Ferrara    [76702,556]
  1453. .br
  1454. .ta
  1455. .br
  1456. David Husnian [76064,1535]
  1457. .br
  1458. Ted Means [73067,3332]
  1459. .br
  1460. Steve Kolterman [76320,37]
  1461. .br
  1462. Alexander Santic [71327,2436]
  1463. .br
  1464. Glenn Scott [71620,1521]
  1465. .br
  1466. Keith Wire [73760,2427]
  1467. .br
  1468. Craig Yellick [76247,541]
  1469. .br
  1470. James Zack [75410,1567]
  1471. .in 0i
  1472. .sp
  1473. .in 1.5i
  1474. .ti -1.5i
  1475. .ta 1.5i
  1476. .ft B
  1477. See Also:    
  1478. .ft R
  1479. Overview, Part 1
  1480.