Date: Mon, 01 Jan 2001 16:22:13 +0000
From: "Richard Dawe" <rich AT phekda DOT freeserve DOT co DOT uk>
Sender: rich AT phekda DOT freeserve DOT co DOT uk
To: djgpp-workers AT delorie DOT com
X-Mailer: Emacs 21.0.93 (via feedmail 8.3.emacs20_6 I) and Blat ver 1.8.6
Subject: Section for KB on DJGPP development (was 'contributing...')
Message-Id: <E14D7mG-0000ad-00@phekda.freeserve.co.uk>
Reply-To: djgpp-workers AT delorie DOT com

Hello.

Here's mark 3 of the patch, hopefully addressing all issues with
the last one.

Bye, Rich =]

*** src/docs/kb/kb.txi.orig	Thu Dec 28 19:51:42 2000
--- src/docs/kb/kb.txi	Mon Jan  1 16:11:06 2001
***************
*** 32,38 ****
  This document is a place to store random bits of information about
  DJGPP and how to use it efficiently.
  
! Copyright (c) 1995,1996,1997,1998,1999 DJ Delorie
  
  @menu
  * Introduction::
--- 32,38 ----
  This document is a place to store random bits of information about
  DJGPP and how to use it efficiently.
  
! Copyright @copyright{} 1995,1996,1997,1998,1999,2001 DJ Delorie
  
  @menu
  * Introduction::
***************
*** 50,55 ****
--- 50,58 ----
  * Hidden Features::	Things that are in djgpp but aren't
  			intended for the casual user.
  
+ * Development::         Miscellaneous information on the
+                         development of DJGPP itself.
+ 
  * Index::
  @end menu
  
***************
*** 68,73 ****
--- 71,78 ----
  @chapter Known Anti-Bugs
  
  @include hidden.txi
+ 
+ @include develop.txi
  
  @node Index,,,Top
  @chapter Index
*** /dev/nul	Mon Jan  1 16:20:48 2001
--- src/docs/kb/develop.txi	Mon Jan  1 16:19:28 2001
***************
*** 0 ****
--- 1,101 ----
+ @node Development, , , Top
+ 
+ @section Internal header files
+ 
+ @subsection libc/stubs.h
+ @cindex libc/stubs.h
+ 
+ The @strong{only} time you put something in @file{stubs.h} is if an
+ ANSI/POSIX function in libc needs to call a non-ANSI/POSIX function
+ in libc, in which case the non-ANSI/POSIX function needs to be listed
+ in @file{stubs.h} (or, for ANSI functions calling POSIX-only functions).
+ 
+ There is no other reason why a function would get listed in stubs.
+ 
+ @cindex stubbed name
+ The @dfn{stubbed name} (@samp{__foo}) is @strong{not} part of
+ the published API.
+ 
+ @section Texinfo documentation
+ 
+ @subsection Formatting
+ 
+ @itemize
+ @item
+ Use two spaces after every period/full-stop ending a sentence.
+ 
+ @item
+ Don't use capital letters for emphasis---use @samp{@@strong@{@}} instead.
+ 
+ @item
+ Don't put a newline between a function's return type and its name, e.g.:
+ 
+ @example
+ int
+ somefunc (void);
+ @end example
+ 
+ is incorrect;
+ 
+ @example
+ int somefunc (void);
+ @end example
+ 
+ is correct.
+ 
+ @item
+ When introducing a new term, it is usually a good idea to use
+ @samp{@@dfn@{@}} to mark it as a definition.  It may also be a good idea
+ to add it to the concept index using @samp{@@cindex@{@}}.  E.g.:
+ 
+ @example
+ @@cindex definition
+ 
+ This is a @@dfn@{definition@}.
+ @end example
+ 
+ @item
+ Command-line options should use the @samp{@@samp@{@}} or
+ @samp{@@option@{@}} mark-up.  @samp{@@option@{@}} is new in Texinfo 4.0.
+ 
+ @item
+ Names of programs should use @samp{@@code@{@}} (unless program's name
+ has become a proper name, like GCC or GDB).
+ 
+ @item
+ Constants like @code{EINVAL} should be enclosed in @samp{@@code@{@}}.
+ 
+ @item
+ Avoid the urge to use @samp{@@ref@{@}} or variant in the middle of sentence,
+ because it will look ugly in info documentation and terrible in printed
+ documentation.  Instead use a textual reference followed by a comma followed
+ by the reference command, e.g.
+ 
+ @example
+ @@code@{yabbadabbadoo()@}, @@ref@{yabbadabbadoo()@}.
+ 
+ @end example
+ 
+ @item
+ Be aware of how you use the @samp{-} character.  Use the following mark-up
+ correctly:
+ 
+ @itemize @bullet
+ @item
+ @samp{@@minus@{@}} to insert a minus sign;
+ 
+ @item
+ @samp{---} to insert an em-dash---do not put spaces on either side of
+ @samp{---};
+ 
+ @item
+ @samp{-} to hyphenate;
+ 
+ @item
+ @samp{@@-} to insert a discretionary hyphenation point.
+ @end itemize
+ 
+ @item
+ Finally, for some relevant texinfo technique, look at the source
+ of this page in the DJGPP sources--- AT file{src/docs/kb/contrib.txi}.
+ @end itemize