Update README files for Unix and Wayland platforms

README.Unix.txt: reorganize distributions, add packages to
  prerequisites, and more.

README.Wayland.txt: update title style, minor changes

2 files changed, 222 insertions, 195 deletions

diff --git a/README.Unix.txt b/README.Unix.txt
index 8f0026319..ffea36a0b 100644
--- a/README.Unix.txt
+++ b/README.Unix.txt
@@ -1,46 +1,45 @@
-README.Unix.txt - 2010-11-14 - Building FLTK on Unix
------------------------------------------------------
+README.Unix.txt - Building FLTK on Unix/Linux Systems
+------------------------------------------------------
 
 
-
- CONTENTS
+ Contents
 ==========
 
-  1   INTRODUCTION
-  2   PREREQUISITES
-    2.1   Ubuntu 10
-    2.2   Linux Mint 9
-    2.3   Fedora 13
-    2.4   * http://www2.mandriva.com/
-    2.5   * http://www.opensuse.org/en/
-    2.6   * http://www.debian.org/
-    2.7   * Mandrake?
-    2.8   SunOS / Solaris
-    2.9   * SGI?
-    2.10  HP-UX
-    2.11  AIX
-    2.12  NetBSD
-  3   HOW TO BUILD FLTK USING GCC
-    3.1   Prerequisites
-    3.2   Downloading and Unpacking
-    3.3   Configuring FLTK
+  1   Introduction
+
+  2   Prerequisites
+    2.1   Debian, Ubuntu, Linux Mint, and more ...
+    2.2   Fedora
+    2.3   NetBSD
+    2.4   OpenSuSE [*]
+    2.5   SunOS / Solaris
+    2.6   SGI [*]
+    2.7   HP-UX
+    2.8   AIX
+
+  3   How to Build FLTK Using GCC
+    3.1   Downloading and Unpacking
+    3.2   Configuration and Build Systems
+    3.3   Configuring FLTK with autoconf and configure
     3.4   Building FLTK
     3.5   Testing FLTK
     3.6   Installing FLTK
     3.7   Creating new Projects
-  4   CREATING A NEW PROJECT IN CODE::BLOCKS
-  5   DOCUMENT HISTORY
 
-* TODO: we still need to write these chapters
+  4   Creating a new Project in Code::Blocks
+
+
+[*] TODO: we still need to write these chapters
 
 
 
- 1  INTRODUCTION
+ 1  Introduction
 =================
 
 FLTK currently supports the following development environments on most Unix
-platforms:
+and Linux platforms:
 
+    - CMake + the build system of your choice (see README.CMake.txt)
     - gcc command line tools
     - Code::Blocks
     - ...
@@ -48,22 +47,32 @@ platforms:
 The Symbol font and the Zapf Dingbats font do not work on X11. This is correct
 behavior for UTF-8 platforms.
 
+IMPORTANT:
+
+Please be aware that the following instructions may be outdated because we
+can't follow the development of current and future Unix/Linux distributions.
+If you find bugs or want to suggest enhancements please let us know.
+See https://www.fltk.org/bugs.php for how to do this.
+
 
 
- 2  PREREQUISITES
+ 2  Prerequisites
 ==================
 
 
- 2.1  Ubuntu 10
-----------------
+ 2.1  Debian, Ubuntu, Linux Mint, and more ...
+-----------------------------------------------
 
-Ubuntu Linux can be downloaded here:
+All Linux distributions based on Debian are similar and use the `apt`
+package manager.
 
-  http://www.ubuntu.com/
+  - Ubuntu Linux can be downloaded from https://ubuntu.com/
+  - Debian Linux can be downloaded from https://www.debian.org/
+  - Linux Mint   can be downloaded from https://www.linuxmint.com/
 
-If you have not done so yet, download and install Ubuntu.
+If you have not done so yet, download and install the distribution of your choice.
 
-Open a shell and install some software:
+Open a shell and install some development software:
 
   sudo apt-get install g++
   sudo apt-get install gdb
@@ -71,109 +80,134 @@ Open a shell and install some software:
   sudo apt-get install autoconf
   sudo apt-get install libx11-dev
   sudo apt-get install libglu1-mesa-dev
+  sudo apt-get install libxft-dev
+  sudo apt-get install libxcursor-dev
 
-These two are optional, but highly recommended:
+These packages are optional but recommended:
 
   sudo apt-get install libasound2-dev
-  sudo apt-get install libxft-dev
+  sudo apt-get install freeglut3-dev
+  sudo apt-get install libcairo2-dev
+  sudo apt-get install libfontconfig1-dev
+  sudo apt-get install libglew-dev
+  sudo apt-get install libjpeg-dev
+  sudo apt-get install libpng-dev
+  sudo apt-get install libpango1.0-dev
+  sudo apt-get install libxinerama-dev
+
+If you want to build FLTK for Wayland (the supposed successor of X) you need
+some more packages. Please refer to README.Wayland.txt for more information.
 
 If you are planning to use the Code::Blocks IDE, also install this
 
   sudo apt-get install codeblocks
 
-I like to use git to install the latest FLTK-X.Y.release:
+To install the latest FLTK development (master branch, currently 1.4.x):
 
-  git clone --branch branch-X.Y https://github.com/fltk/fltk
+  git clone https://github.com/fltk/fltk.git
+  cd fltk
+  ...
 
-To update to the latest version, just go into the fltk directory and type
+To update to the latest version, just `cd` into the fltk directory and type
 
   git pull
 
 
- 2.2  Linux Mint 9
--------------------
+ 2.2  Fedora
+-------------
 
-Linux Mint 9 can be downloaded here:
+Fedora Linux can be downloaded from https://getfedora.org/
 
-  http://www.linuxmint.com/
+If you have not done so yet, download and install Fedora.
 
-If you have not done so yet, download and install Linux Mint.
+Open a terminal window and install some software. In Fedora, the default user
+has no permission to call "sudo", so we will change user a few times:
 
-Open a shell and install some software:
+  su root
+  yum groupinstall "Development Tools"
+  yum groupinstall "X Software Development"
+  yum groupinstall "C Development Tools and Libraries"
 
-  sudo apt-get install g++
-  sudo apt-get install gdb
-  sudo apt-get install git
-  sudo apt-get install autoconf
-  sudo apt-get install libx11-dev
-  sudo apt-get install libglu1-mesa-dev
+If you are planning to use the Code::Blocks IDE, also install this
 
-These two are optional, but highly recommended:
+  yum install codeblocks.i686  (for 64 bit machines)
 
-  sudo apt-get install libasound2-dev
-  sudo apt-get install libxft-dev
+Don't forget to leave root status (Ctrl-D) before loading FLTK. To install FLTK
+for every user, you either have to set root user again, or use "visudo" to add
+yourself to the "sudo" list.
 
-If you are planning to use the Code::Blocks IDE, also install this
+To install the latest FLTK development (master branch, currently 1.4.x):
 
-  sudo apt-get install codeblocks
+  git clone https://github.com/fltk/fltk.git
+  cd fltk
+  ...
 
-I like to use git to install the latest FLTK-X.Y.release:
+To update to the latest version, just `cd` into the fltk directory and type
 
-  git clone --branch branch-X.Y https://github.com/fltk/fltk
+  git pull
 
-To update to the latest version, just go into the fltk directory and type
 
-  git pull
+ 2.3   NetBSD
+--------------
 
-FIXME: no FL_SYMBOL font (-*-symbol-*),  font 15 (Zapf-Dingbats)
+NetBSD can be downloaded from https://www.netbsd.org/
 
+If you have not done so yet, download and install NetBSD. Ensure that the
+optional distribution sets "comp" (Compiler, header files, development tools)
+and x*** (X Window System) are installed.
 
- 2.3  Fedora 13
--------------------
+Now install and configure pkgsrc. The current version can be downloaded here:
 
-Fedora 13 Linux can be downloaded here:
+  http://www.pkgsrc.org/
 
-  http://fedoraproject.org/
+To use the current stable version of FLTK, simply install it from pkgsrc:
 
-If you have not done so yet, download and install Fedora.
+  cd /usr/pkgsrc/x11/fltk13
+  bmake install
 
-Open a terminal window and install some software. In Fedora, the default user
-has no permission to call "sudo", so we will change user a few times:
+For the latest development snapshot, first install the git client from pkgsrc:
 
-  su root
-  yum groupinstall "Development Tools"
-  yum groupinstall "X Software Development"
-  yum groupinstall "C Development Tools and Libraries"
+  cd /usr/pkgsrc/devel/git
+  bmake install
 
-If you are planning to use the Code::Blocks IDE, also install this
+Now fetch the latest FLTK source code:
 
-  yum install codeblocks.i686  (for 64 bit machines)
+  git clone https://github.com/fltk/fltk.git
 
-Don't forget to leave root status (Ctrl-D) before loading FLTK. To install FLTK
-for every user, you either have to set root user again, or use "visudo" to add
-yourself to the "sudo" list.
+To update to the latest version, just `cd` into the fltk directory and type
 
-I like to use git to install the latest FLTK-X.Y.release:
+  git pull
 
-  git clone --branch branch-X.Y https://github.com/fltk/fltk
+If you have installed JPEG and PNG libraries from pkgsrc, configure your
+environment as follows so that the FLTK configure script can find them:
 
-To update to the latest version, just go into the fltk directory and type
+  export CPPFLAGS="-I/usr/pkg/include"
+  export LDFLAGS="-L/usr/pkg/lib"
 
-  git pull
+To install GNU autoconf from pkgsrc:
 
-FIXME: no FL_SYMBOL font (-*-symbol-*),  font 15 (Zapf-Dingbats)
+  cd /usr/pkgsrc/devel/autoconf
+  bmake install
+
+
+ 2.4  OpenSuSE
+---------------
+
+We still need to write this chapter.
+
+OpenSUSE can be downloaded from https://www.opensuse.org/
 
 
- 2.8  SunOS / Solaris
+ 2.5  SunOS / Solaris
 ----------------------
 
 SunOS is a commercial operating system from Sun Microsystems (in 2009 the
 company was sold to Oracle). SunOS is also called Solaris since version 5.
 There was an open source derivative called OpenSolaris (based on Solaris 10)
 that was cancelled by Oracle. The successor in spirit is called OpenIndiana
-and can be downloaded from here:
+and can be downloaded from:
 
-  http://www.openindiana.org/
+  https://www.openindiana.org/
 
 For FLTK you need at least SunOS 5.7 (aka Solaris 7). This version supports
 64 bit machines and POSIX threads. For machines with 64 bit SPARC processors
@@ -197,8 +231,14 @@ To build a 64 bit FLTK library, add the following flags:
   export CXXFLAGS="-xarch=v9"
 
 
- 2.10  HP-UX
--------------
+ 2.6  SGI
+----------
+
+We still need to write this chapter.
+
+
+ 2.7  HP-UX
+------------
 
 HP-UX is a commercial operating system from HP, no free or open source
 derivatives are available.
@@ -210,8 +250,8 @@ Consider using pkgsrc with this operating system. See the NetBSD section if
 you want to do so.
 
 
- 2.11  AIX
------------
+ 2.8  AIX
+----------
 
 AIX is a commercial operating system from IBM, no free or open source
 derivatives are available.
@@ -222,66 +262,22 @@ Consider using pkgsrc with this operating system. See the NetBSD section if
 you want to do so.
 
 
- 2.12  NetBSD
---------------
-
-NetBSD can be downloaded here:
-
-  http://www.netbsd.org/
-
-If you have not done so yet, download and install NetBSD. Ensure that the
-optional distribution sets "comp" (Compiler, header files, development tools)
-and x*** (X Window System) are installed.
-
-Now install and configure pkgsrc. The current version can be downloaded here:
-
-  http://www.pkgsrc.org/
-
-To use the current stable version of FLTK, simply install it from pkgsrc:
-
-  cd /usr/pkgsrc/x11/fltk13
-  bmake install
-
-For the latest development snapshot, first install the git client from pkgsrc:
-
-  cd /usr/pkgsrc/devel/git
-  bmake install
-
-Now fetch the latest FLTK X.Y.release source code:
-
-  git clone --branch branch-X.Y https://github.com/fltk/fltk
-
-To update to the latest version, just go into the fltk directory and type
 
-  git pull
-
-If you have installed JPEG and PNG libraries from pkgsrc, configure your
-environment as follows so that the FLTK configure script can find them:
-
-  export CPPFLAGS="-I/usr/pkg/include"
-  export LDFLAGS="-L/usr/pkg/lib"
-
-To install GNU autoconf from pkgsrc:
-
-  cd /usr/pkgsrc/devel/autoconf
-  bmake install
-
-
- 3  HOW TO BUILD FLTK USING GCC
+ 3  How to Build FLTK Using GCC
 ================================
 
 
  3.1  Downloading and Unpacking
 --------------------------------
 
-Download FLTK from here:
+The FLTK source code and documentation can be downloaded from:
 
   https://www.fltk.org/software.php
 
-If you are familiar with "git" and like to stay current with your
-version, you will find the git access parameters at the bottom of that
-page. Unpack FLTK into a convenient location. I like to have everything in my
-dev directory:
+If you are familiar with "git" and like to stay current with your version,
+you will find the git access parameters at the bottom of that page.
+Unpack FLTK into a convenient location. I like to have everything in my
+dev directory. Change the following instructions to fit your preferences.
 
   cd
   mkdir dev
@@ -290,16 +286,45 @@ dev directory:
   tar xvfz fltk-1.3.xxxx.tar.gz
   cd fltk-1.3.xxxx
 
+Note: current development version is 1.4.0 (1.4.x).
+
+
+ 3.2  Configuration and Build Systems
+--------------------------------------
 
- 3.2  Configuring FLTK
------------------------
+The following paragraphs describe the "classic" build system with autoconf,
+configure, and make that has been used to build FLTK up to version 1.3.x
+and can still be used with FLTK 1.4.x.
+
+However, the FLTK team recommend using CMake which is the preferred build
+system since FLTK 1.4.0 used for all platforms (including Windows). CMake
+is used instead of autoconf and configure to create the build system of your
+choice, for instance Makefiles, Ninja build files, Visual Studio projects, etc.
+
+Please see README.CMake.txt for how to build FLTK and your application
+programs using CMake. You can stop reading here if you do this.
+
+You can, of course, build FLTK with CMake and your own application(s) with
+your existing and well-known build system.
+
+If you like the "classic" build system more, continue reading the following
+chapters ...
+
+
+ 3.3  Configuring FLTK with autoconf and configure
+---------------------------------------------------
 
 If you got FLTK via git then you need one extra step. Otherwise skip
-over this part. Stay in your FLTK source-code directory and type the
-following:
+over this part. Stay in your FLTK source-code directory and type:
 
   autoconf
 
+or
+
+  make configure
+
+Both commands create the configure script for you.
+
 Now configure your FLTK installation:
 
   ./configure
@@ -311,15 +336,15 @@ and build FLTK with the default configuration.
 
 ADVANCED: type "./configure --help" to get a complete list of optional
 configuration parameters. These should be pretty self-explanatory. Some
-more details can be found in README.
+more details can be found in README.txt.
 :END_ADVANCED
 
 The configuration script will check your machine for the required resources
-which you should have installed as described in the Prerequisites chapter.
-Review the Configuration Summary, maybe take some notes.
+which you should have installed as described in the "Prerequisites" chapter.
+Review the "Configuration Summary", maybe take some notes.
 
 
- 3.3  Building FLTK
+ 3.4  Building FLTK
 --------------------
 
 Now this is easy. Stay in your FLTK source-code directory and type:
@@ -328,13 +353,11 @@ Now this is easy. Stay in your FLTK source-code directory and type:
 
 The entire FLTK toolkit including many test programs will be built for you. No
 warnings should appear. If some do, please let the FLTK developer team know via
-the mailing list or the bug reporting template at www.fltk.org .
-
-Actually, as of Apr 13 2016, one or two warnings will show, mostly about
-deprecated declarations. Please ignore them.
+the mailing list "fltk.general" or view the bug reporting guidelines at
+https://www.fltk.org/bugs.php
 
 
- 3.4  Testing FLTK
+ 3.5  Testing FLTK
 -------------------
 
 After a successful build, you can test FLTK's capabilities:
@@ -342,7 +365,7 @@ After a successful build, you can test FLTK's capabilities:
   test/demo
 
 
- 3.5  Installing FLTK
+ 3.6  Installing FLTK
 ----------------------
 
 If you did not change any of the configuration settings, FLTK will be installed
@@ -360,8 +383,17 @@ It is possible to install FLTK without superuser privileges by changing the
 installation path to a location within the user account by adding the
 "--prefix=PREFIX" parameters to the "./configure" command.
 
+Note: installing FLTK is optional. You can build your own software by using
+the FLTK build tree directly. This is recommended if you link your application
+statically (which is recommended as well). This is particularly important if you
+consider using different FLTK versions on a development system to avoid mixing
+FLTK versions when building (a well-known problem) or running FLTK applications
+with installed shared libraries of a different FLTK version. OTOH, if you build
+shared FLTK libraries you may want to install FLTK, particularly on a production
+system.
 
- 3.6  Creating new Projects
+
+ 3.7  Creating new Projects
 ----------------------------
 
 FLTK provides a neat script named "fltk-config" that can provide all the flags
@@ -372,30 +404,34 @@ source file is:
 
   fltk-config --compile myProgram.cxx
 
+`fltk-config --compile` can not be used to build a program from multiple source
+files but you can use it in a Makefile to get the required compiler and linker
+flags.
+
 "fltk-config" and "fluid" will be installed in "/usr/local/bin/" by default. I
 recommend that you add it to the command search path.
 
 
 
- 4  CREATING A NEW PROJECT IN CODE::BLOCKS
+ 4  Creating a new Project in Code::Blocks
 ===========================================
 
 Code::Blocks is a free and popular C++ IDE in the Linux world. It also runs on
-OS X and Windows. Configured correctly, it can also cross-compile between
+macOS and Windows. Configured correctly, it can also cross-compile between
 these platforms. This chapter focuses on creating a new FLTK project for Linux,
 assuming that FLTK 1.3 was previously built and installed in its default
 location from the command line.
 
-If not done yet, install Code::Blocks as described in the Prerequisites chapter
-above, or download it from their web site. This description is based on
-version 10.05:
+If not done yet, install Code::Blocks as described in the "Prerequisites"
+chapter above, or download it from their web site. This description is based
+on version 10.05:
 
-  http://www.codeblocks.org/
+  https://www.codeblocks.org/
 
 Start Code::Blocks. Select File > New > Project. In the "New from template"
 dialog box, click on "FLTK project" and follow the instructions.
 
-The default project supports basic fltk. If you would like to add support for
+The default project supports basic FLTK. If you would like to add support for
 images, OpenGL, GLUT, or Forms, add the corresponding flags --use-images,
 --use-gl, --use-glut, and --use-forms respectively.
 
@@ -408,8 +444,8 @@ The linker flags are located in the "Linker Settings" tab under "Other Linker
 Options". Add the flags to `fltk-config --ldstaticflags` in front of the
 second "`".
 
-CodeBlocks can be set up to use fluid to manage modules.
-The following info is from mingodad@gmail.com posted on fltk.general 06/17/2013:
+Code:Blocks can be set up to use fluid to manage modules.
+The following info is from an FLTK user posted on fltk.general 06/17/2013:
 
 """
     I have these settings in codeblocks on linux:
@@ -437,14 +473,3 @@ The following info is from mingodad@gmail.com posted on fltk.general 06/17/2013:
     and it opens with fluid. When I press "run" or "build" codeblocks
     calls fluid to generate the c++ files and compiles if needed.
 """
-
-
-
- 5  DOCUMENT HISTORY
-=====================
-
-Oct 30 2010 - matt: added Code::Blocks chapter
-Oct 28 2010 - matt: restructured entire document and verified instructions
-Nov 14 2010 - duncan: added install-desktop
-Jun 17 2013 - erco: added mingodad's CodeBlocks/Fluid recommendations
-Apr 13 2021 - giri: Replace svn instructions by git instructions
diff --git a/README.Wayland.txt b/README.Wayland.txt
index 1f065ea72..20ceab874 100644
--- a/README.Wayland.txt
+++ b/README.Wayland.txt
@@ -1,28 +1,28 @@
-README.Wayland.txt - Wayland platform support for FLTK
+README.Wayland.txt - Wayland Platform Support for FLTK
 ------------------------------------------------------
 
 
-CONTENTS
+Contents
 ========
 
- 1   INTRODUCTION
+ 1   Introduction
 
- 2   WAYLAND SUPPORT FOR FLTK
+ 2   Wayland Support for FLTK
    2.1    Configuration
    2.2    Known Limitations
 
- 3   PREPARING PLATFORM-SPECIFIC CODE FOR THE WAYLAND PLATFORM
-   3.1    Handling X11-specific source code
-   3.2    Handling X11- and Wayland-specific source code in the same app
-   3.3    Forcing an app to always use the X11 mechanism
+ 3   Preparing Platform Specific Code for the Wayland Platform
+   3.1    Handling X11 specific Source Code
+   3.2    Handling X11 and Wayland Specific Source Code in the Same App
+   3.3    Forcing an FLTK App to Always Use the X11 Backend
 
- 4   PLATFORM SPECIFIC NOTES
+ 4   Platform Specific Notes
    4.1    Debian and Derivatives (like Ubuntu)
    4.2    Fedora
    4.3    FreeBSD
 
 
-1 INTRODUCTION
+1 Introduction
 ==============
 
 Version 1.4 of the FLTK library introduces support of the public FLTK API on
@@ -35,12 +35,12 @@ The code has also been tested under FreeBSD and the sway wayland compositor.
 CJK text-input methods, as well as dead and compose keys are supported.
 
 
-2 WAYLAND SUPPORT FOR FLTK
+2 Wayland Support for FLTK
 ==========================
 
-On Linux and FreeBSD systems, and provided a Wayland compositor is available at run-time,
-it is possible to have your FLTK application do all its windowing through the
-Wayland protocol, all its graphics with Cairo or EGL, and all text-drawing with
+On Linux and FreeBSD systems, and provided a Wayland compositor is available at
+run-time, it is possible to have your FLTK application do all its windowing through
+the Wayland protocol, all its graphics with Cairo or EGL, and all text-drawing with
 Pango. If no Wayland compositor is available at run-time, FLTK falls back to
 using X11 or OpenGL for its windowing. Cairo and Pango remain used for graphics
 and text, respectively.
@@ -111,14 +111,14 @@ tested in that situation.
 so feedback on this subject would be helpful.
 
 
-3 PREPARING PLATFORM-SPECIFIC CODE FOR THE WAYLAND PLATFORM
+3 Preparing Platform Specific Code for the Wayland Platform
 ===========================================================
 
 While platform-independent source code prepared for FLTK 1.3 is expected
 to be compatible with no change with FLTK 1.4 and the Wayland platform,
 platform-specific code may require some attention.
 
-3.1 Handling X11-specific source code
+3.1 Handling X11 specific Source Code
 -------------------------------------
 
 If an FLTK 1.4 application contains X11-specific code, execution of this code
@@ -127,8 +127,8 @@ To ensure that X11-specific code gets called only when an X11 connection is acti
 check that function fl_x11_display() returns non-NULL before using any X11-specific
 function or variable.
 
-3.2 Handling X11- and Wayland-specific source code in the same app
-------------------------------------------------------------------
+3.2 Handling X11 and Wayland Specific Source Code in the Same App
+-----------------------------------------------------------------
 
 The recommended way to prepare and use platform-specific code that would contain
 both X11-specific and Wayland-specific parts is as follows :
@@ -155,16 +155,16 @@ function or variable, and that fl_wl_display() returns non-NULL before using any
 Wayland-specific function or variable. Make sure that fl_open_display() was called
 directly or indirectly before using any such symbol.
 
-3.3 Forcing an FLTK app to always use the X11 backend
+3.3 Forcing an FLTK App to Always Use the X11 Backend
 -----------------------------------------------------
 
-Alternatively, it's possible to force an FLTK app to use X11 in all
+Alternatively, it is possible to force an FLTK app to use X11 in all
 situations by calling function fl_disable_wayland() early in main(), that is,
 before fl_open_display() runs. FLTK source code and also platform-specific
 code conceived for FLTK 1.3 should run under 1.4 with that single change only.
 
 
-4 PLATFORM SPECIFIC NOTES
+4 Platform Specific Notes
 =========================
 
 The following are notes about building FLTK for the Wayland platform
@@ -202,6 +202,8 @@ These packages allow to run FLTK apps under the KDE/Plasma-Wayland desktop:
 - kde-plasma-desktop
 - plasma-workspace-wayland
 
+Package installation command: sudo apt-get install <package-name ...>
+
 
 4.2 Fedora
 ----------