Improve and clarify documentation

FL/Fl.H

@@ -736,20 +736,20 @@ public:
 
   The legal event state bits are:
 
-    | Device   | State Bit      | Key or Button           | Since |
+    | Device   | State Bit      | Key or Button           | Since  |
-    |----------|----------------|-------------------------|-------|
+    |----------|----------------|-------------------------|--------|
-    | Keyboard | FL_SHIFT       | Shift                   |       |
+    | Keyboard | FL_SHIFT       | Shift                   |        |
-    | Keyboard | FL_CAPS_LOCK   | Caps Lock               |       |
+    | Keyboard | FL_CAPS_LOCK   | Caps Lock               |        |
-    | Keyboard | FL_CTRL        | Ctrl                    |       |
+    | Keyboard | FL_CTRL        | Ctrl                    |        |
-    | Keyboard | FL_ALT         | Alt                     |       |
+    | Keyboard | FL_ALT         | Alt                     |        |
-    | Keyboard | FL_NUM_LOCK    | Num Lock                |       |
+    | Keyboard | FL_NUM_LOCK    | Num Lock                |        |
-    | Keyboard | FL_META        | Meta, e.g. "Windows"    |       |
+    | Keyboard | FL_META        | Meta, e.g. "Windows"    |        |
-    | Keyboard | FL_SCROLL_LOCK | Scroll Lock             |       |
+    | Keyboard | FL_SCROLL_LOCK | Scroll Lock             |        |
-    | Mouse    | FL_BUTTON1     | left button             |       |
+    | Mouse    | FL_BUTTON1     | left button             |        |
-    | Mouse    | FL_BUTTON2     | middle button           |       |
+    | Mouse    | FL_BUTTON2     | middle button           |        |
-    | Mouse    | FL_BUTTON3     | right button            |       |
+    | Mouse    | FL_BUTTON3     | right button            |        |
-    | Mouse    | FL_BUTTON4     | side button 1 (back)    | 1.4.0 |
+    | Mouse    | FL_BUTTON4     | side button 1 (back)    | 1.3.10 |
-    | Mouse    | FL_BUTTON5     | side button 2 (forward) | 1.4.0 |
+    | Mouse    | FL_BUTTON5     | side button 2 (forward) | 1.3.10 |
   */
   static int event_state()      {return e_state;}
 

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); }
 

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
+  for Fl_Pack. This is the recommended single row/column container
-  FLTK 1.4.0. Its resizing behavior is much more predictable (as expected)
+  since FLTK 1.4.0. Its resizing behavior is much more predictable
-  than that of Fl_Pack which "resizes itself to shrink-wrap itself around
+  than that of Fl_Pack which <i>"resizes itself to shrink-wrap itself
-  all of the children".
+  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

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.

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);

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:

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);

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

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
+    As of this writing (FLTK 1.4.0) Fl_Menu_Items support only one label
-    one label part (text \b or image), but using Fl_Multi_Label as the
+    part (text \b or image), but using Fl_Multi_Label as the label can extend
-    label can extend this to more than one part.
+    this to more than one part.
 
   \see class Fl_Multi_Label, Fl_Widget::align()
 

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
+ \note Since FLTK 1.4.0 options can be managed with the \c fltk-options program.
- FLTK 1.4.0. In 1.3.x, options can be set in FLUID.
+   In FLTK 1.3.x options can be set in FLUID.
 
  \param opt which option
  \return true or false

src/Fl_Device.cxx

@@ -72,17 +72,22 @@
 */
 
 /** Make this surface the current drawing surface.
- This surface will receive all future graphics requests.
+  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().
+  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();