Sender: richdawe AT bigfoot DOT com
Message-ID: <3A4BA452.BB6ADC3F@bigfoot.com>
Date: Thu, 28 Dec 2000 20:36:34 +0000
From: Richard Dawe <richdawe AT bigfoot DOT com>
X-Mailer: Mozilla 4.51 [en] (X11; I; Linux 2.2.17 i586)
X-Accept-Language: de,fr
MIME-Version: 1.0
To: DJGPP workers <djgpp-workers AT delorie DOT com>
Subject: Start to section for KB on how to contribute to DJGPP
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: 7bit
Reply-To: djgpp-workers AT delorie DOT com

Hello.

Please find below a start to section for the knowledge base on how to
contribute to DJGPP, collated from various e-mails. There's a lot of room
for improvement:

* What texinfo mark-up do you use for function names? Constants (e.g.
'errno' values)?

* I think that DJ has some details on his site about contributing, but I
haven't checked yet.

These can be added later.

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    Thu Dec 28 20:27:01 2000
--- src/docs/kb/contrib.txi     Thu Dec 28 20:22:48 2000
***************
*** 0 ****
--- 1,61 ----
+ @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
+ @end itemize