Update FAQ's for release.

doc/FAQ_Linux

@@ -4,7 +4,7 @@ Frequently Asked Questions (FAQ) for PostgreSQL >= V6.1
 Linux Specific
 TO BE READ IN CONJUNCTION WITH THE NORMAL FAQ
 =======================================================
-last updated:           Thu Dec 15 12:05:00 GMT 1997
+last updated:           Wed Feb 18 13:00:00 GMT 1997
 
 current maintainer:     Andrew C.R. Martin (martin@biochem.ucl.ac.uk)
 original author:        Andrew C.R. Martin (martin@biochem.ucl.ac.uk)
@@ -12,10 +12,8 @@ original author:        Andrew C.R. Martin (martin@biochem.ucl.ac.uk)
 
 Changes in this version (* = modified, + = new, - = removed):
 
-*1.3)   [REDHAT] Why do I get problems with missing libdl and dlfcn.h?
++1.20)  How can I optimise for 486 or pentium processors
-*1.4)   [SLACKWARE 3.1] Why do I get problems with missing libdl and dlfcn.h?
++3.10)  Why do I get funny rounding results in some date/time arithmetic...
-+1.19)  Why does make exit or crash?
-
 
 This file is divided approximately as follows:
 1.*)    Installing PostgreSQL
@@ -55,6 +53,7 @@ Questions answered:
 1.17)   When compiling postgres, gcc reports signal 11 and aborts.
 1.18)   Can I install 6.1.1 under MkLinux?
 1.19)   Why does make exit or crash?
+1.20)   How can I optimise for 486 or pentium processors
 2.1)    The linker fails to find libX11 when compiling pgtclsh
 3.1)    I get an error reporting _fUnKy_POSTPORT_sTuFf_ undefined when 
         running scripts like createuser
@@ -77,6 +76,10 @@ Questions answered:
 3.8)    When PostgreSQL is running when the system is shutdown, Linux
         always fsck's the disk when rebooted.
 3.9)    Why does Query 32 in the regression tests take so long?
+3.10)   Why do I get funny rounding results in some date/time arithmetic,
+        such as
+           select '4 hours'::timespan;
+        returning '3 hours 59 minutes 60 seconds'?
 
 ----------------------------------------------------------------------
 Section 1:      Compiling PostgreSQL
@@ -298,7 +301,7 @@ Section 1:      Compiling PostgreSQL
 
         Some versions of SuSE provide only ncurses, so you may need
         to force use of ncurses rather than curses by changing 
-        -lcurses to -lncurses.
+        -lcurses to -lncurses. (Reported true for SuSE 5.1)
 
 
 1.9)    Why do I get problems with ld.so?
@@ -430,6 +433,19 @@ Section 1:      Compiling PostgreSQL
         In short, try upgrading gmake to the latest version you can 
         find before reporting this as a problem
 
+1.20)   How can I optimise for 486 or pentium processors
+
+        The default compiler flags perform no optimisation for 486
+        or Pentium processors. To add such optimisation, edit
+        Makefile.custom and add:
+
+           CFLAGS+= -m486
+
+        or (for the new compilers that most people are not yet running)
+
+           CFLAGS+= -mpentium
+        or
+           CFLAGS+= -mpentiumpro
 
 ----------------------------------------------------------------------
 Section 2:      Compiling accessory programs
@@ -617,6 +633,15 @@ exit 0
         then type:
                 sh ./perquery < bench.out > & bench.out.perquery
 
+
+
+3.10)   Why do I get funny rounding results in some date/time arithmetic,
+        such as
+           select '4 hours'::timespan;
+        returning '3 hours 59 minutes 60 seconds'?
+
+        You are running the new glibc2 libraries and have a version earlier than
+        2.0.7. It is a math rounding problem in the library. Upgrade your library.
 ----------------------------------------------------------------------------
 Dr. Andrew C.R. Martin                             University College London
 EMAIL: (Work) martin@biochem.ucl.ac.uk    (Home) andrew@stagleys.demon.co.uk

src/tools/FAQ_DEV

@@ -0,0 +1,140 @@
+Developer's Frequently Asked Questions (FAQ) for PostgreSQL
+
+Last updated: Wed Feb 11 20:23:01 EST 1998
+
+Current maintainer: Bruce Momjian (maillist@candle.pha.pa.us)
+
+The most recent version of this document can be viewed at the postgreSQL Web
+site, http://postgreSQL.org.
+
+  ------------------------------------------------------------------------
+
+Questions answered:
+
+1) What tools are available for developers?
+2) What books are good for developers?
+3) Why do we use palloc() and pfree() to allocate memory?
+4) Why do we use Node and List to make data structures?
+5) How do I add a feature or fix a bug?
+6) How do I download/update the current source tree?
+7) How do I test my changes?
+
+  ------------------------------------------------------------------------
+
+1) What tools are available for developers?
+
+Aside from the User documentation mentioned in the regular FAQ, there are
+several development tools available. First, all the files in the /tools
+directory are designed for developers.
+
+        RELEASE_CHANGES         changes we have to make for each release
+        SQL_keywords            standard SQL'92 keywords
+        backend                 web flowchart of the backend directories
+        ccsym                   find standard defines made by your compiler
+        entab                   converts tabs to spaces, used by pgindent
+        find_static             finds functions that could be made static
+        find_typedef            get a list of typedefs in the source code
+        make_ctags              make vi 'tags' file in each directory
+        make_diff               make *.orig and diffs of source
+        make_etags              make emacs 'etags' files
+        make_keywords.README    make comparison of our keywords and SQL'92
+        make_mkid               make mkid ID files
+        mkldexport              create AIX exports file
+        pgindent                indents C source files
+
+Let me note some of these. If you point your browser at the tools/backend
+directory, you will see all the backend components in a flow chart. You can
+click on any one to see a description. If you then click on the directory
+name, you will be taken to the source directory, to browse the actual source
+code behind it. We also have several README files in some source directories
+to describe the function of the module. The browser will display these when
+you enter the directory also. The tools/backend directory is also contained
+on our web page under the title Backend Flowchart.
+
+Second, you really should have an editor that can handle tags, so you can
+tag a function call to see the function definition, and then tag inside that
+function to see an even lower-level function, and then back out twice to
+return to the original function. Most editors support this via tags or etags
+files.
+
+Third, you need to get mkid from ftp.postgresql.org. By running
+tools/make_mkid, an archive of source symbols can be created that can be
+rapidly queried like grep or edited.
+
+make_diff has tools to create patch diff files that can be applied to the
+distribution.
+
+pgindent will format source files to match our standard format, which has
+four-space tabs, and an indenting format specified by flags to the your
+operating system's utility indent.
+
+2) What books are good for developers?
+
+I have two good books, An Introduction to Database Systems, by C.J. Date,
+Addison, Wesley and A Guide to the SQL Standard, by C.J. Date, et. al,
+Addison, Wesley.
+
+3) Why do we use palloc() and pfree() to allocate memory?
+
+palloc() and pfree() are used in place of malloc() and free() because we
+automatically free all memory allocated when a transaction completes. This
+makes it easier to make sure we free memory that gets allocated in one
+place, but only freed much later. There are several contexts that memory can
+be allocated in, and this controls when the allocated memory is
+automatically freed by the backend.
+
+4) Why do we use Node and List to make data structures?
+
+We do this because this allows a consistent way to pass data inside the
+backend in a flexible way. Every node has a NodeTag which specifies what
+type of data is inside the Node. Lists are lists of Nodes. lfirst(),
+lnext(), and foreach() are used to get, skip, and traverse through Lists.
+
+5) How do I add a feature or fix a bug?
+
+The source code is over 250,000 lines. Many problems/features are isolated
+to one specific area of the code. Others require knowledge of much of the
+source. If you are confused about where to start, ask the hackers list, and
+they will be glad to assess the complexity and give pointers on where to
+start.
+
+Another thing to keep in mind is that many fixes and features can be added
+with surprisingly little code. I often start by adding code, then looking at
+other areas in the code where similar things are done, and by the time I am
+finished, the patch is quite small and compact.
+
+When adding code, keep in mind that it should use the existing facilities in
+the source, for performance reasons and for simplicity. Often a review of
+existing code doing similar things is helpful.
+
+6) How do I download/update the current source tree?
+
+There are several ways to obtain the source tree. Occasional developers can
+just get the most recent source tree snapshot from ftp.postgresql.org. For
+regular developers, you can get CVSup, which is available from
+ftp.postgresql.org too. CVSup allows you to download the source tree, then
+occasionally update your copy of the source tree with any new changes. Using
+CVSup, you don't have to download the entire source each time, only the
+changed files. CVSup does not allow developers to update the source tree.
+
+To update the source tree, there are two ways. You can generate a patch
+against your current source tree, perhaps using the make_diff tools
+mentioned above, and send them to the patches list. They will be reviewed,
+and applied in a timely manner. If the patch is major, and we are in beta
+testing, the developers may wait for the final release before applying your
+patches.
+
+For hard-core developers, Marc(scrappy@postgresql.org) will give you a Unix
+shell account on postgresql.org, and you can ftp your files into your
+account, patch, and cvs install the changes directly into the source tree.
+
+6) How do I test my changes?
+
+First, use psql to make sure it is working as you expect. Then run
+src/test/regress and get the output of src/test/regress/checkresults with
+and without your changes, to see that your patch does not change the
+regression test in unexpected ways. This practice has saved me many times.
+The regression tests test the code in ways I would never do, and has caught
+many bugs in my patches. By finding the problems now, you save yourself a
+lot of debugging later when things are broken, and you can't figure out when
+it happened.