commit 10da46a5a62012fb6467ef48cc8cabd05690262a
Author:     Albrecht Schlosser <albrechts.fltk@online.de>
AuthorDate: Mon Oct 4 14:42:32 2021 +0200
Commit:     Albrecht Schlosser <albrechts.fltk@online.de>
CommitDate: Mon Oct 4 14:42:32 2021 +0200

    Improve documentation about library build folders and more
    
    lib/README.txt: clarify where built libraries are located
    
    documentation/src/basics.dox: clarify (C++) compiler command usage
      and improve documentation of the fltk-config script

 documentation/src/basics.dox | 60 ++++++++++++++++++++++++++++----------------
 lib/README.txt               | 43 +++++++++++++++++++------------
 2 files changed, 66 insertions(+), 37 deletions(-)

diff --git documentation/src/basics.dox documentation/src/basics.dox
index abcc54a..a29d710 100644
--- documentation/src/basics.dox
+++ documentation/src/basics.dox
@@ -260,15 +260,14 @@ include lines:</i>
 
 \section basics_compiling Compiling Programs that Use FLTK
 
-This section needs a major rework. Since FLTK 1.4 CMake is the recommended build
-system. The details below show the "old" methods and reference information
-in case you like to write your build configuration manually (e.g. Makefiles,
-Visual Studio, or other IDE's etc.).
+Since FLTK 1.4 CMake is the recommended build system. The details below show
+the "old" methods and reference information in case you like to write your
+build configuration manually (e.g. Makefiles, Visual Studio, other IDE's ...).
 
 CMake can simplify this task substantially. For now, refer to README.CMake.txt
 for further information.
 
-\todo Add a chapter "Building FLTK with CMake" or similar.
+\todo This section needs a major rework. Add a chapter "Building FLTK with CMake".
 
 
 \subsection basics_standard_compiler Compiling Programs with Standard Compilers
@@ -278,23 +277,35 @@ tools) you will probably need to tell the compiler where to find the
 header files. This is usually done using the \p -I option:
 
 \code
-CC -I/usr/local/include ...
-gcc -I/usr/local/include ...
+c++ -I/usr/local/include ...
 \endcode
 
-The \p fltk-config script included with FLTK can be
-used to get the options that are required by your compiler:
+\note You need a C++ compiler to build FLTK. The commands given in this
+  chapter are \b examples using \p 'c++'. Please replace this command with
+  the C++ compiler suitable for your system or use the `fltk-config` script
+  as described below (this is recommended).
+
+The \p fltk-config script included with FLTK can be used to get the compiler
+and the options that are required by your compiler:
+
+\code
+  fltk-config --cc
+  fltk-config --cxx
+\endcode
+
+return the C and C++ compiler commands used to build FLTK.
 
 \code
-CC `fltk-config --cxxflags` ...
+c++ `fltk-config --cxxflags` ...
 \endcode
 
+can be used to include the required compiler flags in the command line.
+
 Similarly, when linking your application you will need to tell the
 compiler to use the FLTK library:
 
 \code
-CC  ... -L/usr/local/lib -lfltk -lXext -lX11 -lm -ldl
-gcc ... -L/usr/local/lib -lfltk -lXext -lX11 -lm -ldl
+c++ ... -L/usr/local/lib -lfltk -lXext -lX11 ... -lm -ldl
 \endcode
 
 Aside from the "fltk" library, there are also the following libraries
@@ -304,8 +315,8 @@ Aside from the "fltk" library, there are also the following libraries
   - "fltk_cairo" for optional integrated Cairo support.
 
 \note
-  The separate library \p fltk_cairo will likely be removed in FLTK 1.4.0;
-  this is work in progress.
+  The separate \p fltk_cairo library will likely be removed in FLTK 1.4.0
+  (this is work in progress).
 
 \note
 The libraries are named "fltk.lib", "fltk_gl.lib", "fltk_forms.lib", "fltk_images.lib",
@@ -315,7 +326,7 @@ As before, the \p fltk-config script included with FLTK can be
 used to get the options that are required by your linker:
 
 \code
-CC ... `fltk-config --ldflags`
+c++ ... `fltk-config --ldflags`
 \endcode
 
 <!-- NEED 2in -->
@@ -324,11 +335,11 @@ The forms, GL, and images libraries are included with the "--use-foo"
 options, as follows:
 
 \code
-CC ... `fltk-config --use-forms --ldflags`
-CC ... `fltk-config --use-gl --ldflags`
-CC ... `fltk-config --use-images --ldflags`
-CC ... `fltk-config --use-forms --use-gl --use-images --ldflags`
-CC ... `fltk-config --use-cairo --ldflags`
+c++ ... `fltk-config --use-forms --ldflags`
+c++ ... `fltk-config --use-gl --ldflags`
+c++ ... `fltk-config --use-images --ldflags`
+c++ ... `fltk-config --use-forms --use-gl --use-images --ldflags`
+c++ ... `fltk-config --use-cairo --ldflags`
 \endcode
 
 Finally, you can use the \p fltk-config script to
@@ -347,7 +358,14 @@ Any of these will create an executable named \p filename (or \p filename.exe
 under Windows).
 
 \note <kbd>'fltk-config \-\-compile'</kbd> accepts only a limited set of file
-  extensions for C++ source files: \p '.cpp', \p '.cxx',  \p '.cc',  and \p '.C' .
+  extensions for C++ source files: \p '.cpp', \p '.cxx',  \p '.cc',  and \p '.C'
+  (capital 'C').
+
+\code
+fltk-config --help
+\endcode
+
+displays all available options.
 
 \subsection basics_makefile Compiling Programs with Makefiles
 
diff --git lib/README.txt lib/README.txt
index 6177984..24938be 100644
--- lib/README.txt
+++ lib/README.txt
@@ -1,16 +1,27 @@
-README.lib
-----------
-
-This README file is a placeholder for library files on your
-system.
-
-Under Microsoft Windows a successful build of all projects and
-configurations will contain debug and release libraries for you
-to link to - all are built using the multi-threaded DLL
-settings.  The DLL files (fltkdll.dll and fltkdlld.dll) required
-for a complete DLL-based binary distribution are located in the
-"visualc" directory.
-
-Under UNIX a single set of library files will be built, with or
-without debug information depending on the options you provided
-to the configure script.
+lib/README.txt
+--------------
+
+This README file is a placeholder for FLTK library files on your system
+if FLTK is built using 'configure' and 'make'.
+
+
+Building FLTK with CMake
+
+If FLTK is built using CMake all static and shared libraries are created
+in the 'lib' subdirectory of the build tree. We strongly recommend to
+build with CMake outside the source tree ("out-of-tree") as described
+in README.CMake.txt in the root folder of the FLTK distribution.
+
+If FLTK is built out-of-tree as recommende this folder will not be touched.
+
+
+Building FLTK with configure + make
+
+Under UNIX/Linux and other systems that support 'configure' and 'make'
+(e.g. MinGW, MSYS) a single set of library files will be built, with
+or without debug information depending on the options you provided to
+the configure script.
+
+The FLTK build system based on configure does not support out-of-tree
+builds, hence the static libraries will be built in this 'lib' folder
+and the shared libraries (if enabled) can be found in the 'src' folder.