now renaming restoring dir src_doc src.

git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@6452 ea41ed52-d2ee-0310-a9c1-e6b18d33e121

1 files changed, 353 insertions, 0 deletions

diff --git a/documentation/src/intro.dox b/documentation/src/intro.dox
new file mode 100644
index 000000000..2965883c1
--- /dev/null
+++ b/documentation/src/intro.dox
@@ -0,0 +1,353 @@
+/**
+
+ \page intro	1 - Introduction to FLTK
+
+The Fast Light Tool Kit ("FLTK", pronounced
+"fulltick") is a cross-platform C++ GUI toolkit for
+UNIX®/Linux® (X11), Microsoft® Windows®, and
+MacOS® X. FLTK provides modern GUI functionality without the
+bloat and supports 3D graphics via OpenGL® and its built-in
+GLUT emulation. It was originally developed by Mr. Bill Spitzak
+and is currently maintained by a small group of developers
+across the world with a central repository in the US.
+
+\section intro_history History of FLTK
+
+It has always been Bill's belief that the GUI API of all
+modern  systems is much too high level. Toolkits (even FLTK) are
+<I>not</I> what  should be provided and documented as part of an
+operating system. The  system only has to provide arbitrary
+shaped but featureless windows, a  powerful set of graphics
+drawing calls, and a simple <I>unalterable</I> method of
+delivering events to the owners of the windows. NeXT (if  you
+ignored NextStep) provided this, but they chose to hide it and
+tried to push their own baroque toolkit instead.
+
+Many of the ideas in FLTK were developed on a NeXT (but
+<I>not</I> using NextStep) in 1987 in a C toolkit Bill called
+"views". Here he came up with passing events downward
+in the tree and having the handle routine return a value
+indicating whether it used the event, and the table-driven menus. In
+general he was trying to prove that complex UI ideas could be
+entirely implemented in a user space toolkit, with no knowledge
+or support by the system.
+
+After going to film school for a few years, Bill worked at
+Sun Microsystems on the (doomed) NeWS project. Here he found an
+even better and cleaner windowing system, and he reimplemented
+"views" atop that. NeWS did have an unnecessarily
+complex method of delivering events which hurt it. But the
+designers did admit that perhaps the user could write just as
+good of a button as they could, and officially exposed the lower
+level interface.
+
+With the death of NeWS Bill realized that he would have to
+live with X. The biggest problem with X is the "window
+manager", which means that the toolkit can no longer
+control the window borders or drag the window around.
+
+At Digital Domain Bill discovered another toolkit,
+"Forms". Forms was similar to his work, but provided
+many more widgets, since it was used in many real applications,
+rather then as theoretical work. He decided to use Forms, except
+he integrated his table-driven menus into it. Several very large
+programs were created using this version of Forms.
+
+The need to switch to OpenGL and GLX, portability, and a
+desire to use C++ subclassing required a rewrite of Forms.
+This produced the first version of FLTK. The conversion to C++
+required so many changes it made it impossible to recompile any
+Forms objects. Since it was incompatible anyway, Bill decided
+to incorporate his older ideas as  much as possible by
+simplifying the lower level interface and the event passing
+mechanisim.
+
+Bill received permission to release it for free on the
+Internet, with the GNU general public license. Response from
+Internet users indicated that the Linux market dwarfed the SGI
+and high-speed GL market, so he rewrote it to use X for all
+drawing, greatly speeding it up on these machines. That is the
+version you have now.
+
+Digital Domain has since withdrawn support for FLTK. While
+Bill is no longer able to actively develop it, he still
+contributes to FLTK in his free time and is a part of the FLTK
+development team.
+
+\section intro_features Features
+
+FLTK was designed to be statically linked. This was done by
+splitting it into many small objects and designing it so that
+functions that are not used do not have pointers to them in the
+parts that are used, and thus do not get linked in. This allows
+you to make an easy-to-install program or to modify FLTK to
+the exact requirements of your application without worrying
+about bloat. FLTK works fine as a shared library, though, and
+is now included with several Linux distributions.
+
+Here are some of the core features unique to FLTK:
+
+\li sizeof(Fl_Widget) == 64 to 92.
+
+\li The "core" (the "hello" program compiled & linked with a static FLTK
+    library using gcc on a 486 and then stripped) is 114K.
+
+\li The FLUID program (which includes every widget) is 538k.
+
+\li Written directly atop core libraries (Xlib, WIN32 or Carbon) for
+    maximum speed, and carefully optimized for code size and performance.
+
+\li Precise low-level compatability between the X11, WIN32 and MacOS
+    versions - only about 10% of the code is different.
+
+\li Interactive user interface builder program. Output is human-readable
+    and editable C++ source code.
+
+\li Support for overlay hardware, with emulation if none is available.
+
+\li Very small & fast portable 2-D drawing library to hide Xlib, WIN32,
+    or QuickDraw.
+
+\li OpenGL/Mesa drawing area widget.
+
+\li Support for OpenGL overlay hardware on both X11 and WIN32, with
+    emulation if none is available.
+
+\li Text widgets with Emacs key bindings, X cut & paste, and  foreign
+   letter compose!
+
+\li Compatibility header file for the GLUT library.
+
+\li Compatibility header file for the XForms library.
+
+\section intro_licensing Licensing
+
+FLTK comes with complete free source code. FLTK is available
+under the terms of the <A href="license.html">GNU Library
+General Public License</A> with exceptions that allow for static
+linking. Contrary to popular belief, it can be used in
+commercial software - even Bill Gates could use it!
+
+\section intro_what What Does "FLTK" Mean?
+
+FLTK was originally designed to be compatible with the Forms
+Library written for SGI machines. In that library all the
+functions and structures started with "fl_". This
+naming was extended to all new  methods and widgets in the C++
+library, and this prefix was taken as the name of the library.
+It is almost impossible to search for "FL" on the
+Internet, due to the fact that it is also the abbreviation for
+Florida. After much debating and searching for a new name for
+the toolkit, which was already in use by several people, Bill
+came up with "FLTK", including a bogus excuse that it
+stands for "The Fast Light Toolkit".
+
+\section intro_unix Building and Installing FLTK Under UNIX and MacOS X
+
+In most cases you can just type "make". This will
+run configure with the default of no options and then compile
+everything.
+
+FLTK uses GNU autoconf to configure itself for your UNIX
+platform. The main things that the configure script will look
+for are the X11 and OpenGL (or Mesa) header and library files.
+If these cannot be found in the standard include/library
+locations you'll need to define the <tt>CFLAGS</tt>,
+<tt>CXXFLAGS</tt>, and <tt>LDFLAGS</tt> environment variables.
+For the Bourne and Korn shells you'd use:
+
+\code
+CFLAGS=-Iincludedir; export CFLAGS
+CXXFLAGS=-Iincludedir; export CXXFLAGS
+LDFLAGS=-Llibdir; export LDFLAGS
+\endcode
+
+For C shell and tcsh, use:
+
+\code
+setenv CFLAGS "-Iincludedir"
+setenv CXXFLAGS "-Iincludedir"
+setenv LDFLAGS "-Llibdir"
+\endcode
+
+By default configure will look for a C++ compiler named
+<tt>CC</tt>, <tt>c++</tt>, <tt>g++</tt>, or <tt>gcc</tt> in that
+order. To use another compiler you need to set the <tt>CXX</tt>
+environment variable:
+
+\code
+CXX=xlC; export CXX
+setenv CXX "xlC"
+\endcode
+
+The <tt>CC</tt> environment variable can also be used to
+override the default C compiler (<tt>cc</tt> or <tt>gcc</tt>),
+which is used for a few FLTK source files.
+
+You can run configure yourself to get the exact setup you need.
+Type  "./configure <options>", where options are:
+
+\par --enable-cygwin
+Enable the Cygwin libraries under WIN32
+
+\par --enable-debug
+Enable debugging code & symbols
+
+\par --disable-gl
+Disable OpenGL support
+
+\par --enable-shared
+Enable generation of shared libraries
+
+\par --enable-threads
+Enable multithreading support
+
+\par --enable-xdbe
+Enable the X double-buffer extension
+
+\par --enable-xft
+Enable the Xft library for anti-aliased fonts under X11
+
+\par --bindir=/path
+Set the location for executables [default = $prefix/bin]
+
+\par --datadir=/path
+Set the location for data files. [default = $prefix/share]
+
+\par --libdir=/path
+Set the location for libraries [default = $prefix/lib]
+
+\par --includedir=/path
+Set the location for include files. [default = $prefix/include]
+
+\par --mandir=/path
+Set the location for man pages. [default = $prefix/man]
+
+\par --prefix=/dir
+Set the directory prefix for files [default = /usr/local]
+
+When the configure script is done you can just run the
+"make" command. This will build the library, FLUID
+tool, and all of the test programs.
+
+To install the library, become root and type "make
+install". This will copy the "fluid" executable
+to "bindir", the header files to
+"includedir", and the library files to
+"libdir".
+
+\section intro_windows Building FLTK Under Microsoft Windows
+
+There are three ways to build FLTK under Microsoft Windows.
+The first is to use the Visual C++ 5.0 project files under the
+"visualc" directory. Just open (or double-click on)
+the "fltk.dsw" file to get the whole shebang.
+
+The second method is to use the <TT>configure</TT> script
+included with the FLTK software; this has only been tested with
+the CygWin tools:
+
+\code
+sh configure --prefix=C:/FLTK
+make
+\endcode
+
+The final method is to use a GNU-based development tool with
+the files in the "makefiles" directory. To build
+using one of these tools simply copy the appropriate
+makeinclude and config files to the main directory and do a
+make:
+
+\code
+copy makefiles\Makefile.<env> Makefile
+make
+\endcode
+
+\subsection intro_visualcpp Using the Visual C++ DLL Library
+
+The "fltkdll.dsp" project file builds a DLL-version
+of the FLTK library. Because of name mangling differences
+between PC compilers (even between different versions of Visual
+C++!) you can only use the DLL that is generated with the same
+version compiler that you built it with.
+
+When compiling an application or DLL that uses the FLTK DLL,
+you will need to define the <tt>FL_DLL</tt> preprocessor symbol
+to get the correct linkage commands embedded within the FLTK
+header files.
+
+\section intro_os2 Building FLTK Under OS/2
+
+The current OS/2 build requires XFree86 for OS/2 to work.  A
+native  Presentation Manager version has not been implemented
+yet (volunteers  are welcome!).
+
+The current set of Makefiles/configuration failes assumes that EMX 0.9d
+and libExt (from
+<A HREF="http://posix2.sourceforge.net">posix2.sourceforge.net</A>)
+is installed.
+
+To build the XFree86 version of FLTK for OS/2, copy the appropriate
+makeinclude and config files to the main directory and do a make: 
+
+\code
+copy makefiles\Makefile.os2x Makefile
+make
+\endcode
+
+\section intro_internet Internet Resources
+
+FLTK is available on the 'net in a bunch of locations:
+
+\par WWW
+<A href="http://www.fltk.org/">http://www.fltk.org/</A> <BR>
+<A href="http://www.fltk.org/str.php">http://www.fltk.org/str.php</A> 
+	  [for reporting bugs]<BR> 
+<A href="http://www.fltk.org/software.php">http://www.fltk.org/software.php</A> 
+	  [source code]
+
+\par FTP
+<A HREF="ftp://ftp.fltk.org/pub/fltk">California, USA (ftp.fltk.org)</A><BR> 
+<A HREF="ftp://ftp2.fltk.org/pub/fltk">Maryland, USA (ftp2.fltk.org)</A><BR> 
+<A HREF="ftp://ftp.funet.fi/pub/mirrors/ftp.fltk.org/pub/fltk">Espoo, Finland (ftp.funet.fi)</A><BR> 
+<A HREF="ftp://linux.mathematik.tu-darmstadt.de/pub/linux/mirrors/misc/fltk">Germany (linux.mathematik.tu-darmstadt.de)</A><BR>
+<A HREF="ftp://gd.tuwien.ac.at/hci/fltk">Austria (gd.tuwien.ac.at)</A>
+
+\par EMail
+<A href="mailto:fltk@fltk.org">fltk@fltk.org</A> [see instructions below]<BR> 
+<A href="mailto:fltk-bugs@fltk.org">fltk-bugs@fltk.org</A> [for	reporting bugs]
+
+\par NNTP Newsgroups
+news.easysw.com
+
+To send a message to the FLTK mailing list
+("fltk@fltk.org") you  must first join the list.
+Non-member submissions are blocked to avoid  problems with
+unsolicited email.
+
+To join the FLTK mailing list, send a message to
+"majordomo@fltk.org" with "subscribe fltk"
+in the message body. A digest of this list is available by
+subscribing to the "fltk-digest" mailing list.
+
+\section intro_reporting Reporting Bugs
+
+To report a bug in FLTK, send an email to
+"fltk-bugs@fltk.org". Please include the FLTK version,
+operating system & version, and compiler that you are using
+when describing the bug or problem. We will be unable to provide
+any kind of help without that basic information.
+
+Bugs can also be reported to the "fltk.bugs" newsgroup or on the
+SourceForge bug tracker pages.
+
+For general support and questions, please use the FLTK mailing list
+at "fltk@fltk.org" or one of the newsgroups.
+
+\htmlonly
+<hr>
+<a class="el" href="index.html">[Index]</a> &nbsp;&nbsp;
+<a class="el" href="preface.html">[Previous]&nbsp; Preface</a>&nbsp;
+<a class="el" href="basics.html">[Next]&nbsp; 2 - FLTK Basics</a>&nbsp;
+\endhtmlonly
+*/