Update more README files for 1.5.0

1 files changed, 78 insertions, 114 deletions

diff --git a/README.txt b/README.txt
index 1e14c43e4..e8bc87233 100644
--- a/README.txt
+++ b/README.txt
@@ -5,11 +5,11 @@ WHAT IS FLTK?
 
     The Fast Light Tool Kit is a cross-platform C++ GUI toolkit for
     UNIX®/Linux® (X11 or Wayland), Microsoft® Windows®, and macOS®.
-    FLTK provides modern GUI functionality without 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 on GitHub.
+    FLTK provides modern GUI functionality without 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 on GitHub.
 
         https://www.fltk.org/
         https://github.com/fltk/fltk/
@@ -35,92 +35,31 @@ ON-LINE DOCUMENTATION
 
 BUILDING AND INSTALLING FLTK UNDER UNIX AND macOS
 
-    Beginning with FLTK 1.4 the main and recommended build system
-    is CMake. CMake is a "build system generator" and can be used
-    to create Makefile's, Ninja build files, Xcode (macOS),
-    Visual Studio (Windows) IDE files and many more.
-
-    Please see README.CMake.txt for further information.
-
-    Alternatively FLTK can be built with autoconf + make, the
-    build system used in FLTK 1.3 and earlier versions. Please
-    be aware that the following information may be outdated
-    because it is no longer actively maintained.
-
-    Note: autoconf + configure + make is still supported in FLTK 1.4.x
-    but will be removed in FLTK 1.5.0 or any higher version.
-
-    In most cases you can just type "make".  This will run configure
-    with the default (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, OpenGL (or Mesa), and JPEG header and
-    library files.  Make sure that they are in the standard
-    include/library locations.  If they aren't you need to
-    define the CFLAGS, CXXFLAGS, and LDFLAGS environment
-    variables.
-
-    If you aren't using "gcc", "g++", "c++", or "CC" for your
-    C++ compiler, you'll also need to set the CXX environment
-    variable. Similarly, if you aren't using "gcc" or "cc" for
-    your C compiler you'll need to set the CC environment variable.
-
-    You can run configure yourself to get the exact setup you
-    need. Type "./configure <options>".  Options include:
-
-        --help                  - display help and exit
-        --enable-cygwin         - Enable the Cygwin DLL (Cygwin only)
-        --enable-debug          - Enable debugging code & symbols
-        --disable-forms         - Disable generation of the forms library
-        --disable-gl            - Disable OpenGL support
-        --enable-shared         - Enable generation of shared libraries
-        --enable-threads        - Enable multithreading support
-        --enable-xft            - Enable the Xft library (anti-aliased fonts)
-        --enable-pango          - Draw text with the pango library
-        --disable-wayland       - Force building for X11 only (no Wayland support)
-        --enable-x11            - Force building for X11 (macOS and Cygwin)
-        --disable-x11           - Force building for Wayland only (Linux/Unix)
-        --bindir=/path          - Set the location for executables
-                                  [default = /usr/local/bin]
-        --libdir=/path          - Set the location for libraries
-                                  [default = /usr/local/lib]
-        --includedir=/path      - Set the location for include files.
-                                  [default = /usr/local/include]
-        --prefix=/dir           - Set the directory prefix for files
-                                  [default = /usr/local]
-
-    For more options please see './configure --help'.
-
-    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".
-
-    To install additional files and icons to be used by the main
-    desktop environments such as KDE, GNOME and XFCE, you will also
-    need to run "make install-desktop" as root.
-
-
-GIT USERS
-
-    If you've just checked out a fresh copy of FLTK from  Git (GitHub),
-    you'll need to generate an initial version of 'configure'
-    by running 'make makeinclude' or 'make clean' (we don't
-    include a copy of configure in git).
-
-
-MAKE TARGETS
-
-    make            -- builds the library + test programs (does not install)
-    make install    -- builds and installs
-    make clean      -- clean for a rebuild
-    make distclean  -- like 'clean', but also removes docs, configure, fltk-config
-    ( cd src; make ) -- builds just the fltk libraries
+    Since FLTK 1.5.0 the only available build system is CMake. CMake is a
+    "build system generator" and can be used to create Makefile's, Ninja
+    build files, Xcode (macOS), Visual Studio (Windows) IDE files, and
+    many more. Use `cmake --help` to display the available generators
+    on your platform.
+
+    Please see also README.CMake.txt for further details. There are *many*
+    options to configure the build as you need.
+
+    In a nutshell:
+
+      $ cd /path/to/fltk
+      $ cmake . -B build
+      $ cmake --build build
+
+    These commands create the build folder 'build' inside your source tree,
+    build the library and all test programs. You may want to test the demo
+    programs by running `build/bin/test/demo`.
+
+    After successful tests you may install the library with the following
+    command, but please be aware that this will install FLTK in a system
+    directory for system-wide use. We don't recommend this unless you know
+    what you're doing.
+
+      $ sudo cmake --install build  # default: to /usr/local/...
 
 
 BUILDING FLTK UNDER MICROSOFT WINDOWS
@@ -131,48 +70,69 @@ BUILDING FLTK UNDER MICROSOFT WINDOWS
     in your favorite development directory, then build FLTK with Visual Studio.
 
     The second method is to use a GNU-based development tool. To build with
-    the Cygwin or MinGW tools, use the supplied configure script as specified
-    in the UNIX section above:
+    the Cygwin, MinGW, or MSYS2 tools, use CMake to create the build files
+    as described above.
 
-        ./configure ...options...
+    In most cases it's useful to install a binary CMake distribution from
+    https://cmake.org/download/ .
+
+    Then execute `cmake-gui` and generate Visual Studio project files or any
+    other build files of your choice, e.g. "Unix Makefiles" for MinGW, but
+    note that there are other options as well.
 
     See README.Windows.txt and README.CMake.txt for more info.
 
 
 BUILDING HTML DOCUMENTATION
 
-    If you want to build the HTML documentation:
+    FLTK uses Doxygen for documentation, so you'll at least need doxygen
+    installed for creating html docs, and LaTeX for creating PDF docs.
+
+    If you want to build the documentation, change directory to your build
+    folder, for instance
 
-        ( cd documentation && make html )
+        cd /path/to/fltk/build
 
-    If you want to build the PDF documentation:
+    To build the HTML or PDF documentation, use these CMake commands:
 
-        ( cd documentation && make pdf )
+        cmake --build . --target html
+        cmake --build . --target pdf
 
-    FLTK uses doxygen for documentation, so you'll at least need doxygen
-    installed for creating html docs, and LaTeX for creating PDF docs.
+    Note: instead of using the generic CMake commands above you can also
+    use equivalent commands of your build system, e.g. `make html` or
+    `ninja pdf`.
 
 
 INTERNET RESOURCES
 
-    FLTK is available on the 'net in a bunch of locations:
+    FLTK is available on the internet in a bunch of locations:
 
-        - WWW:   https://www.fltk.org/
-                 https://www.fltk.org/bugs.php [for reporting bugs]
-                 https://www.fltk.org/software.php [source code]
+    - https://www.fltk.org/                   - homepage
+    - https://github.com/fltk/fltk            - source code and discussions
+    - https://www.fltk.org/bugs.php           - info for reporting bugs
+    - https://www.fltk.org/software.php       - download source code
+    - https://github.com/fltk/fltk/releases   - source code and documentation
+
+    Note that we don't provide pre-compiled (binary) distributions. Consult
+    the package manager of your (Linux, Unix, macOS) operating system.
 
 
 GENERAL QUESTIONS
 
-    To join the FLTK mailing list, go the following web page:
+    To join the FLTK mailing list, go to the following web page:
 
         https://groups.google.com/forum/#!forum/fltkgeneral
 
-    You can find detailed instructions how you can register for the mailing
-    list (even w/o a Google mail address) at the bottom of this page:
+    You can find detailed instructions on how you can register for the
+    mailing list (even w/o a Google account) at the bottom of this page:
 
         https://www.fltk.org/newsgroups.php
 
+    Since July 2024 we offer GitHub Discussions on our GitHub project page.
+    Use the 'Q&A' section for general questions on building and using FLTK.
+
+        https://github.com/fltk/fltk/discussions/categories/q-a
+
 
 REPORTING BUGS
 
@@ -182,21 +142,25 @@ REPORTING BUGS
 
         https://groups.google.com/forum/#!forum/fltkgeneral
 
-    See paragraph GENERAL QUESTIONS above for more info.
+    or on GitHub Discussions (Q&A) as noted above:
+
+        https://github.com/fltk/fltk/discussions/categories/q-a
+
+
+    See also paragraph GENERAL QUESTIONS above for more info.
 
     If you are sure you found a bug, please see the following page for
-    further information:
+    further information on how to report a bug:
 
         https://www.fltk.org/bugs.php
 
 
 TRADEMARKS
 
-    Microsoft and Windows are registered trademarks of Microsoft
-    Corporation. UNIX is a registered trademark of the X/Open
-    Group, Inc.  OpenGL is a registered trademark of Silicon
-    Graphics, Inc.  macOS is a registered trademark of Apple
-    Computers, Inc.
+    Microsoft and Windows are registered trademarks of Microsoft Corporation.
+    UNIX is a registered trademark of the X/Open Group, Inc.
+    OpenGL is a registered trademark of Silicon Graphics, Inc.
+    macOS is a registered trademark of Apple Computers, Inc.
 
 
 COPYRIGHT