Date: Sat, 30 Dec 2000 19:26:09 +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: Patch to add 'contributing...' section of KB - version 2
Message-Id: <E14CRhO-0006zo-00@phekda.freeserve.co.uk>
Reply-To: djgpp-workers AT delorie DOT com

Hello.

Here's version 2 of the patch to add the start of a 'contributing to
DJGPP' section to the knowledge base.

Bye, Rich =]

*** src/docs/kb/kb.txi.orig	Thu Dec 28 19:51:42 2000
--- src/docs/kb/kb.txi	Thu Dec 28 20:26:52 2000
***************
*** 50,55 ****
--- 50,57 ----
  * Hidden Features::	Things that are in djgpp but aren't
  			intended for the casual user.
  
+ * Contributing::        How to contribute to DJGPP.
+ 
  * Index::
  @end menu
  
***************
*** 68,73 ****
--- 70,77 ----
  @chapter Known Anti-Bugs
  
  @include hidden.txi
+ 
+ @include contrib.txi
  
  @node Index,,,Top
  @chapter Index
*** /dev/nul	Sat Dec 30 19:22:34 2000
--- src/docs/kb/contrib.txi	Sat Dec 30 19:16:40 2000
***************
*** 0 ****
--- 1,84 ----
+ @node Contributing, , , 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.
+ 
+ @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
+ 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;
+ 
+ @item
+ @samp{-} to hyphenate;
+ 
+ @item
+ @samp{@@-} to insert a discretionary hyphenation point.
+ @end itemize
+ 
+ @item
+ Finally, for some texinfo technique that is relevant look at the source
+ of this page in the DJGPP sources --- @file{src/docs/kb/contrib.txi}.
+ @end itemize