Improve and clarify documentation

11 files changed, 50 insertions, 45 deletions

diff --git a/FL/Fl.H b/FL/Fl.H
index 84ac2c59d..769dcadc6 100644
--- a/FL/Fl.H
+++ b/FL/Fl.H
@@ -736,20 +736,20 @@ public:
 
   The legal event state bits are:
 
-    | Device   | State Bit      | Key or Button           | Since |
-    |----------|----------------|-------------------------|-------|
-    | Keyboard | FL_SHIFT       | Shift                   |       |
-    | Keyboard | FL_CAPS_LOCK   | Caps Lock               |       |
-    | Keyboard | FL_CTRL        | Ctrl                    |       |
-    | Keyboard | FL_ALT         | Alt                     |       |
-    | Keyboard | FL_NUM_LOCK    | Num Lock                |       |
-    | Keyboard | FL_META        | Meta, e.g. "Windows"    |       |
-    | Keyboard | FL_SCROLL_LOCK | Scroll Lock             |       |
-    | Mouse    | FL_BUTTON1     | left button             |       |
-    | Mouse    | FL_BUTTON2     | middle button           |       |
-    | Mouse    | FL_BUTTON3     | right button            |       |
-    | Mouse    | FL_BUTTON4     | side button 1 (back)    | 1.4.0 |
-    | Mouse    | FL_BUTTON5     | side button 2 (forward) | 1.4.0 |
+    | Device   | State Bit      | Key or Button           | Since  |
+    |----------|----------------|-------------------------|--------|
+    | Keyboard | FL_SHIFT       | Shift                   |        |
+    | Keyboard | FL_CAPS_LOCK   | Caps Lock               |        |
+    | Keyboard | FL_CTRL        | Ctrl                    |        |
+    | Keyboard | FL_ALT         | Alt                     |        |
+    | Keyboard | FL_NUM_LOCK    | Num Lock                |        |
+    | Keyboard | FL_META        | Meta, e.g. "Windows"    |        |
+    | Keyboard | FL_SCROLL_LOCK | Scroll Lock             |        |
+    | Mouse    | FL_BUTTON1     | left button             |        |
+    | Mouse    | FL_BUTTON2     | middle button           |        |
+    | Mouse    | FL_BUTTON3     | right button            |        |
+    | Mouse    | FL_BUTTON4     | side button 1 (back)    | 1.3.10 |
+    | Mouse    | FL_BUTTON5     | side button 2 (forward) | 1.3.10 |
   */
   static int event_state()      {return e_state;}
 
diff --git a/FL/Fl_Browser_.H b/FL/Fl_Browser_.H
index 37ae59c5e..5db510ffd 100644
--- a/FL/Fl_Browser_.H
+++ b/FL/Fl_Browser_.H
@@ -246,11 +246,11 @@ public:
     \see position(), hposition()
   */
   int vposition() const { return position_; }
-  FL_DEPRECATED("in 1.4.0 - use vposition() instead",
+  FL_DEPRECATED("since 1.4.0 - use vposition() instead",
   int position() const) { return vposition(); }
 
   void vposition(int pos); // scroll to here
-  FL_DEPRECATED("in 1.4.0 - use vposition(pos) instead",
+  FL_DEPRECATED("since 1.4.0 - use vposition(pos) instead",
   void position(int pos)) { return vposition(pos); }
   void position(int x, int y) { Fl_Group::position(x, y); }
 
diff --git a/FL/Fl_Flex.H b/FL/Fl_Flex.H
index 20b4f50f5..ef46daca3 100644
--- a/FL/Fl_Flex.H
+++ b/FL/Fl_Flex.H
@@ -2,7 +2,7 @@
 // Fl_Flex widget header file for the Fast Light Tool Kit (FLTK).
 //
 // Copyright 2020 by Karsten Pedersen
-// Copyright 2022-2023 by Bill Spitzak and others.
+// Copyright 2022-2024 by Bill Spitzak and others.
 //
 // This library is free software. Distribution and use rights are outlined in
 // the file "COPYING" which should have been included with this file.  If this
@@ -70,10 +70,10 @@
   is undefined, i.e. widgets may overlap and/or shrink to zero size.
 
   \b Hint: In many cases Fl_Flex can be used as a drop-in replacement
-  for Fl_Pack. This is the recommended single row/column container since
-  FLTK 1.4.0. Its resizing behavior is much more predictable (as expected)
-  than that of Fl_Pack which "resizes itself to shrink-wrap itself around
-  all of the children".
+  for Fl_Pack. This is the recommended single row/column container
+  since FLTK 1.4.0. Its resizing behavior is much more predictable
+  than that of Fl_Pack which <i>"resizes itself to shrink-wrap itself
+  around all of the children"</i>.
 
   Fl_Flex containers can be nested so you can create flexible layouts with
   multiple columns and rows. However, if your UI design is more complex you
@@ -106,7 +106,7 @@
     window.size_range(300, 30);
     window.show(argc, argv);
     return Fl::run();
-}
+  }
   \endcode
 
   \since 1.4.0
diff --git a/FL/Fl_Input_.H b/FL/Fl_Input_.H
index e7087e418..2e87b115d 100644
--- a/FL/Fl_Input_.H
+++ b/FL/Fl_Input_.H
@@ -304,7 +304,7 @@ public:
     \see insert_position(int, int)
   */
   int insert_position() const { return position_; }
-  FL_DEPRECATED("in 1.4.0 - use insert_position() instead",
+  FL_DEPRECATED("since 1.4.0 - use insert_position() instead",
   int position() const ) { return insert_position(); }
 
   /** Gets the current selection mark.
@@ -313,7 +313,7 @@ public:
 
   /* Sets the index for the cursor and mark. */
   int insert_position(int p, int m);
-  FL_DEPRECATED("in 1.4.0 - use insert_position(p, m) or Fl_Widget::position(x, y) instead",
+  FL_DEPRECATED("since 1.4.0 - use insert_position(p, m) or Fl_Widget::position(x, y) instead",
   int position(int p, int m)) { return insert_position(p, m); }
 
   /** Sets the cursor position and mark.
@@ -323,7 +323,7 @@ public:
     \see insert_position(int, int), insert_position(), mark(int)
   */
   int insert_position(int p) { return insert_position(p, p); }
-  FL_DEPRECATED("in 1.4.0 - use insert_position(p) instead",
+  FL_DEPRECATED("since 1.4.0 - use insert_position(p) instead",
   int position(int p)) { return insert_position(p); }
 
   /** Sets the current selection mark.
diff --git a/FL/Fl_Preferences.H b/FL/Fl_Preferences.H
index 591f1d230..6c6407a57 100644
--- a/FL/Fl_Preferences.H
+++ b/FL/Fl_Preferences.H
@@ -203,7 +203,7 @@ public:
   Fl_Preferences( ID id );
   virtual ~Fl_Preferences();
 
-  FL_DEPRECATED("in 1.4.0 - use Fl_Preferences(path, vendor, application, flags) instead",
+  FL_DEPRECATED("since 1.4.0 - use Fl_Preferences(path, vendor, application, flags) instead",
                 Fl_Preferences( const char *path, const char *vendor, const char *application ) );
 
   Root filename( char *buffer, size_t buffer_size);
diff --git a/FL/Fl_Text_Buffer.H b/FL/Fl_Text_Buffer.H
index 6d59e9adf..f548f1e4e 100644
--- a/FL/Fl_Text_Buffer.H
+++ b/FL/Fl_Text_Buffer.H
@@ -167,7 +167,7 @@ public:
 
   // Returns true if selected() and the positions of this selection.
   int selected(int *startpos, int *endpos) const;
-  FL_DEPRECATED("in 1.4.0 - use selected(startpos, endpos) instead",
+  FL_DEPRECATED("since 1.4.0 - use selected(startpos, endpos) instead",
   int position(int *startpos, int *endpos) const) { return selected(startpos, endpos); }
 
 protected:
diff --git a/FL/Fl_Tile.H b/FL/Fl_Tile.H
index 64a3ba530..189e0f6da 100644
--- a/FL/Fl_Tile.H
+++ b/FL/Fl_Tile.H
@@ -32,7 +32,7 @@ public:
   void resize(int X, int Y, int W, int H) FL_OVERRIDE;
   virtual void move_intersection(int oldx, int oldy, int newx, int newy);
   virtual void drag_intersection(int oldx, int oldy, int newx, int newy);
-  FL_DEPRECATED("in 1.4.0 - use move_intersection(p) instead",
+  FL_DEPRECATED("since 1.4.0 - use move_intersection(p) instead",
   void position(int oldx, int oldy, int newx, int newy)) { move_intersection(oldx, oldy, newx, newy); }
   void position(int x, int y) { Fl_Group::position(x, y); }
   void size_range(int index, int minw, int minh, int maxw=0x7FFFFFFF, int maxh=0x7FFFFFFF);
diff --git a/documentation/src/basics.dox b/documentation/src/basics.dox
index e875108ab..8e6a350fd 100644
--- a/documentation/src/basics.dox
+++ b/documentation/src/basics.dox
@@ -395,7 +395,7 @@ fltk-config --use-forms --use-gl --use-images --compile filename.cpp
 
 Before version 1.4.0 \p fltk-config accepted only a single source file
 and no additional compiler options or libraries.
-As of FLTK 1.4.0 it is possible to use additional compiler flags, more than
+Since FLTK 1.4.0 it is possible to use additional compiler flags, more than
 one source file, and additional link libraries.
 
 This is intended to be used for quick prototyping and not for production code
diff --git a/documentation/src/common.dox b/documentation/src/common.dox
index 56679a680..dc8843eee 100644
--- a/documentation/src/common.dox
+++ b/documentation/src/common.dox
@@ -428,9 +428,9 @@ The following standard label types are included:
     the widget's align() flag. FL_MULTI_LABEL was designed to be used with
     Fl_Menu_Item's to support icons or small images, typically left of the
     menu text.\n
-    As of this writing (FLTK 1.4.0, Sep 2017) Fl_Menu_Items support only
-    one label part (text \b or image), but using Fl_Multi_Label as the
-    label can extend this to more than one part.
+    As of this writing (FLTK 1.4.0) Fl_Menu_Items support only one label
+    part (text \b or image), but using Fl_Multi_Label as the label can extend
+    this to more than one part.
 
   \see class Fl_Multi_Label, Fl_Widget::align()
 
diff --git a/src/Fl.cxx b/src/Fl.cxx
index dc35d5195..e65cad949 100644
--- a/src/Fl.cxx
+++ b/src/Fl.cxx
@@ -2025,8 +2025,8 @@ void Fl::clear_widget_pointer(Fl_Widget const *w)
          { ..off..  }
  \endcode
 
- \note Options can be managed with the \c fltk-options program, new in
- FLTK 1.4.0. In 1.3.x, options can be set in FLUID.
+ \note Since FLTK 1.4.0 options can be managed with the \c fltk-options program.
+   In FLTK 1.3.x options can be set in FLUID.
 
  \param opt which option
  \return true or false
diff --git a/src/Fl_Device.cxx b/src/Fl_Device.cxx
index 86b5e8cdd..c723186f2 100644
--- a/src/Fl_Device.cxx
+++ b/src/Fl_Device.cxx
@@ -72,17 +72,22 @@
 */
 
 /** Make this surface the current drawing surface.
- This surface will receive all future graphics requests.
- \p Starting from FLTK 1.4.0, the preferred API to change the current drawing surface
- is Fl_Surface_Device::push_current( ) / Fl_Surface_Device::pop_current().
- \note It's recommended to use this function only as follows :
- \li The current drawing surface is the display;
- \li make current another surface, e.g., an Fl_Printer or an Fl_Image_Surface object,  calling set_current() on this object;
- \li draw to that surface;
- \li make the display current again with Fl_Display_Device::display_device()->set_current();  . Don't do any other call to set_current() before this one.
-
- Other scenarios of drawing surface changes should be performed via Fl_Surface_Device::push_current( ) / Fl_Surface_Device::pop_current().
- */
+  This surface will receive all future graphics requests.
+
+  Since FLTK 1.4.0 the preferred API to change the current drawing surface
+  is Fl_Surface_Device::push_current( ) / Fl_Surface_Device::pop_current().
+
+  \note It is recommended to use this function only as follows :
+    - The current drawing surface is the display;
+    - make current another surface, e.g., an Fl_Printer or an Fl_Image_Surface object,
+      calling set_current() on this object;
+    - draw to that surface;
+    - make the display current again with Fl_Display_Device::display_device()->set_current();\n
+      don't do any other call to set_current() before this one.
+
+  Other scenarios of drawing surface changes should be performed via
+  Fl_Surface_Device::push_current() and Fl_Surface_Device::pop_current().
+*/
 void Fl_Surface_Device::set_current(void)
 {
   if (surface_) surface_->end_current();