Major documentation update including: now html doc API is sorted, navigation problems/side effects fixed, html tags replaced by proper doxygen commands, parameters command switched from a to p. Includes a pdf update.

git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@6716 ea41ed52-d2ee-0310-a9c1-e6b18d33e121

9 files changed, 58 insertions, 58 deletions

diff --git a/FL/Fl.H b/FL/Fl.H
index 476e775fb..e0cd2bf88 100644
--- a/FL/Fl.H
+++ b/FL/Fl.H
@@ -503,7 +503,7 @@ public:
   */
   static int event_original_key(){return e_original_keysym;}
   /** 
-    Returns true if the given \a key was held
+    Returns true if the given \p key was held
     down (or pressed) <I>during</I> the last event.  This is constant until
     the next event is read from the server.
     
@@ -542,7 +542,7 @@ public:
   */
   static int event_key(int key);
   /** 
-    Returns true if the given \a key is held down <I>now</I>.  
+    Returns true if the given \p key is held down <I>now</I>.  
     Under X this requires a round-trip to the server and is <I>much</I>
     slower than Fl::event_key(int). \see event_key(int)
   */
@@ -591,7 +591,7 @@ public:
    @{ */
   // cut/paste:
   /**
-    Copies the data pointed to by \a stuff to the selection (0) or
+    Copies the data pointed to by \p stuff to the selection (0) or
     primary (1) clipboard. The selection clipboard is used for
     middle-mouse pastes and for drag-and-drop selections. The primary
     clipboard is used for traditional copy/cut/paste operations.
@@ -676,7 +676,7 @@ public:
     guarantee that each face has a different name.  The return value points
     to a static buffer that is overwritten each call.
     
-    The integer pointed to by \a attributes (if the pointer is not
+    The integer pointed to by \p attributes (if the pointer is not
     zero) is set to zero, FL_BOLD or FL_ITALIC or 
     FL_BOLD | FL_ITALIC.  To locate a "family" of fonts, search
     forward and back for a set with non-zero attributes, these faces along
@@ -684,7 +684,7 @@ public:
   */
   static const char* get_font_name(Fl_Font, int* attributes = 0);
   /**
-    Return an array of sizes in \a sizep.  The return value is the
+    Return an array of sizes in \p sizep.  The return value is the
     length of this array.  The sizes are sorted from smallest to largest
     and indicate what sizes can be given to fl_font() that will
     be matched exactly (fl_font() will pick the closest size for
@@ -900,7 +900,7 @@ public:
       FL::cairo_make_current(Fl_Window*). This will create a cairo context
       but only for this Window. 
       Still in custom cairo application it is possible to handle 
-      completely this process automatically by setting \a alink to true.
+      completely this process automatically by setting \p alink to true.
       In this last case, you don't need anymore to call Fl::cairo_make_current().
       You can use Fl::cairo_cc() to get the current cairo context anytime.
      \note Only available when configure has the --enable-cairo option
@@ -916,8 +916,8 @@ public:
   static bool cairo_autolink_context() {return cairo_state_.autolink();}
   /** Gets the current cairo context linked with a fltk window. */
   static cairo_t * cairo_cc() { return cairo_state_.cc(); }
-  /** Sets the current cairo context to \a c.
-      Set \a own to true if you want fltk to handle this cc deletion.
+  /** Sets the current cairo context to \p c.
+      Set \p own to true if you want fltk to handle this cc deletion.
      \note Only available when configure has the --enable-cairo option
 */
   static void cairo_cc(cairo_t * c, bool own=false){ cairo_state_.cc(c, own); } 
diff --git a/FL/Fl_Cairo.H b/FL/Fl_Cairo.H
index 32491e684..aeed1fdeb 100644
--- a/FL/Fl_Cairo.H
+++ b/FL/Fl_Cairo.H
@@ -67,7 +67,7 @@ public:
     // access attributes
     cairo_t* cc() const {return cc_;}		 ///< Gets the current cairo context
     bool autolink() const {return autolink_;}	 ///< Gets the autolink option. See Fl::cairo_autolink_context(bool)
-    /** Sets the current cairo context, \a own indicates cc deletion is handle externally by user */
+    /** Sets the current cairo context, \p own indicates cc deletion is handle externally by user */
     void cc(cairo_t* c, bool own=true)  {	 
 	if (cc_ && own_cc_) cairo_destroy(cc_); 
 	cc_=c;
@@ -75,9 +75,9 @@ public:
 	own_cc_=own;
     }
     void  autolink(bool b);                     ///< Sets the autolink option, only available with --enable-cairoext
-    void  window(void* w)  {window_=w;}		///< Sets the window \a w to keep track on
+    void  window(void* w)  {window_=w;}		///< Sets the window \p w to keep track on
     void* window() const {return window_;}	///< Gets the last window attached to a cc
-    void  gc(void* c)  {gc_=c;}		        ///< Sets the gc \a c to keep track on
+    void  gc(void* c)  {gc_=c;}		        ///< Sets the gc \p c to keep track on
     void* gc() const {return gc_;}		///< Gets the last gc attached to a cc
 
 private:
diff --git a/FL/Fl_Cairo_Window.H b/FL/Fl_Cairo_Window.H
index 31ff318b2..f59025955 100644
--- a/FL/Fl_Cairo_Window.H
+++ b/FL/Fl_Cairo_Window.H
@@ -74,7 +74,7 @@ public:
   typedef void (*cairo_draw_cb) (Fl_Cairo_Window* self, cairo_t* def);
   /** 
     You must provide a draw callback which will implement your cairo rendering.
-    This method will permit you to set your cairo callback to \a cb.
+    This method will permit you to set your cairo callback to \p cb.
   */
   void set_draw_cb(cairo_draw_cb  cb){draw_cb_=cb;}
 private:
diff --git a/FL/Fl_Counter.H b/FL/Fl_Counter.H
index f881a0279..3e96c6537 100644
--- a/FL/Fl_Counter.H
+++ b/FL/Fl_Counter.H
@@ -102,17 +102,17 @@ public:
 
   /** Gets the text font */
   Fl_Font textfont() const {return textfont_;}
-  /** Sets the text font to \a s */
+  /** Sets the text font to \p s */
   void textfont(Fl_Font s) {textfont_ = s;}
 
   /** Gets the font size */
   Fl_Fontsize textsize() const {return textsize_;}
-  /** Sets the font size to \a s */
+  /** Sets the font size to \p s */
   void textsize(Fl_Fontsize s) {textsize_ = s;}
 
   /** Gets the font color */
   Fl_Color textcolor() const {return (Fl_Color)textcolor_;}
-  /** Sets the font color to \a s */
+  /** Sets the font color to \p s */
   void textcolor(unsigned s) {textcolor_ = s;}
 
 };
diff --git a/FL/Fl_File_Input.H b/FL/Fl_File_Input.H
index 48b1faca7..e85847557 100644
--- a/FL/Fl_File_Input.H
+++ b/FL/Fl_File_Input.H
@@ -83,7 +83,7 @@ public:
     \todo Better docs for Fl_File_Input::errorcolor() - is it even used?
   */
   Fl_Color	errorcolor() const { return errorcolor_; }
-  /** Sets the current error color to \a c */
+  /** Sets the current error color to \p c */
   void		errorcolor(Fl_Color c) { errorcolor_ = c; }
 
   int	value(const char *str);
diff --git a/FL/Fl_Group.H b/FL/Fl_Group.H
index 1037897e2..c3898db03 100644
--- a/FL/Fl_Group.H
+++ b/FL/Fl_Group.H
@@ -105,12 +105,12 @@ public:
   void insert(Fl_Widget&, int i);
   /**
     This does insert(w, find(before)).  This will append the
-    widget if \a before is not in the group.
+    widget if \p before is not in the group.
   */
   void insert(Fl_Widget& o, Fl_Widget* before) {insert(o,find(before));}
   void remove(Fl_Widget&);
   /**
-    Removes the widget \a o from the group.
+    Removes the widget \p o from the group.
     \sa void remove(Fl_Widget&)
   */
   void remove(Fl_Widget* o) {remove(*o);}
@@ -163,7 +163,7 @@ public:
     Controls whether the group widget clips the drawing of
     child widgets to its bounding box.
     
-    Set \a c to 1 if you want to clip the child widgets to the
+    Set \p c to 1 if you want to clip the child widgets to the
     bounding box.
 
     The default is to not clip (0) the drawing of child widgets.
diff --git a/FL/Fl_Widget.H b/FL/Fl_Widget.H
index c7140657c..af8b3000e 100644
--- a/FL/Fl_Widget.H
+++ b/FL/Fl_Widget.H
@@ -815,8 +815,8 @@ public:
 
   /** Calls the widget callback.
       Causes a widget to invoke its callback function with arbitrary arguments.
-      \param[in] o call the callback with \a o as the widget argument
-      \param[in] arg call the callback with \a arg as the user data argument
+      \param[in] o call the callback with \p o as the widget argument
+      \param[in] arg call the callback with \p arg as the user data argument
       \see callback()
    */
   void do_callback(Fl_Widget* o,long arg) {do_callback(o,(void*)arg);}
@@ -834,14 +834,14 @@ public:
 
   /** Checks if w is a child of this widget.
       \param[in] w potential child widget
-      \return Returns 1 if \a w is a child of this widget, or is
-      equal to this widget. Returns 0 if \a w is NULL.
+      \return Returns 1 if \p w is a child of this widget, or is
+      equal to this widget. Returns 0 if \p w is NULL.
    */
   int contains(const Fl_Widget *w) const ;
 
   /** Checks if this widget is a child of w.
-      Returns 1 if this widget is a child of \a w, or is
-      equal to \a w. Returns 0 if \a w is NULL.
+      Returns 1 if this widget is a child of \p w, or is
+      equal to \p w. Returns 0 if \p w is NULL.
       \param[in] w the possible parent widget.
       \see contains()
    */
diff --git a/FL/filename.H b/FL/filename.H
index 965b68d95..76f94e75a 100644
--- a/FL/filename.H
+++ b/FL/filename.H
@@ -34,7 +34,7 @@
     @{ */
 
 #  define FL_PATH_MAX 256 /**< all path buffers should use this length */
-/** Gets the file name from a path. \return a pointer to the char after the last slash, or to \a filename if there is none. */
+/** Gets the file name from a path. \return a pointer to the char after the last slash, or to \p filename if there is none. */
 FL_EXPORT const char *fl_filename_name(const char * filename);
 FL_EXPORT const char *fl_filename_ext(const char *);
 FL_EXPORT char *fl_filename_setext(char *to, int tolen, const char *ext);
diff --git a/FL/fl_draw.H b/FL/fl_draw.H
index b4cbe2117..aa73ecfa1 100644
--- a/FL/fl_draw.H
+++ b/FL/fl_draw.H
@@ -175,9 +175,9 @@ FL_EXPORT void fl_transformed_vertex(double x, double y);
   You may call this outside a draw context if necessary to call fl_width(),
   but on X this will open the display.
 
-  The font is identified by a \a face and a \a size.
+  The font is identified by a \p face and a \p size.
   The size of the font is measured in pixels and not "points".
-  Lines should be spaced \a size pixels apart or more.
+  Lines should be spaced \p size pixels apart or more.
 */
 
 // Fonts:
@@ -185,14 +185,14 @@ FL_EXPORT void fl_font(Fl_Font face, Fl_Fontsize size);
 extern FL_EXPORT Fl_Font fl_font_; ///< current font index
 
 /**
-  Returns the \a face set by the most recent call to fl_font().
+  Returns the \p face set by the most recent call to fl_font().
   This can be used to save/restore the font.
 */
 inline Fl_Font fl_font() {return fl_font_;}
 /** current font size */
 extern FL_EXPORT Fl_Fontsize fl_size_;
 /**
-  Returns the \a size set by the most recent call to fl_font().
+  Returns the \p size set by the most recent call to fl_font().
   This can be used to save/restore the font.
 */
 inline Fl_Fontsize fl_size() {return fl_size_;}
@@ -200,15 +200,15 @@ inline Fl_Fontsize fl_size() {return fl_size_;}
 // information you can get about the current font:
 /**
   Returns the recommended minimum line spacing for the current font.
-  You can also use the value of \a size passed to fl_font()
+  You can also use the value of \p size passed to fl_font()
 */
 FL_EXPORT int   fl_height();	// using "size" should work ok
 /**
   Dummy passthru function called only in Fl_Text_Display that simply returns
-  the font height as given by the \a size parameter in the same call!
+  the font height as given by the \p size parameter in the same call!
 
   \todo Is fl_height(int, int size) required for Fl_Text_Dispay?
-        Why not use \a size parameter directly?
+        Why not use \p size parameter directly?
 */
 inline int fl_height(int, int size) {return size;}
 /**
@@ -218,7 +218,7 @@ inline int fl_height(int, int size) {return size;}
 FL_EXPORT int   fl_descent();
 /** Return the typographical width of a nul-terminated string */
 FL_EXPORT double fl_width(const char* txt);
-/** Return the typographical width of a sequence of \a n characters */
+/** Return the typographical width of a sequence of \p n characters */
 FL_EXPORT double fl_width(const char* txt, int n);
 /** Return the typographical width of a single character :
     \note if a valid fl_gc is NOT found then it uses the first window gc,
@@ -233,7 +233,7 @@ fl_rect(x+dx, y+dy, wo, ho). Note the dx, dy values hold the offset of the first
 "colored in" pixel of the string, from the draw origin.
 */
 FL_EXPORT void fl_text_extents(const char*, int& dx, int& dy, int& w, int& h); // NO fltk symbol expansion will be performed
-/** Determine the minimum pixel dimensions of a sequence of \a n characters.
+/** Determine the minimum pixel dimensions of a sequence of \p n characters.
 \see fl_text_extents(const char*, int& dx, int& dy, int& w, int& h)
 */
 FL_EXPORT void fl_text_extents(const char*, int n, int& dx, int& dy, int& w, int& h);
@@ -276,7 +276,7 @@ FL_EXPORT const char *fl_local_to_mac_roman(const char *t, int n=-1);
   Draws a nul-terminated string starting at the given location.
 
   Text is aligned to the left and to the baseline of the font.
-  To align to the bottom, subtract fl_descent() from \a y.
+  To align to the bottom, subtract fl_descent() from \p y.
   To align to the top, subtract fl_descent() and add fl_height().
   This version of fl_draw provides direct access to the text drawing
   function of the underlying OS. It does not apply any special handling
@@ -284,11 +284,11 @@ FL_EXPORT const char *fl_local_to_mac_roman(const char *t, int n=-1);
 */
 FL_EXPORT void fl_draw(const char* str, int x, int y);
 /**
-  Draws an array of \a n characters starting at the given location.
+  Draws an array of \p n characters starting at the given location.
 */
 FL_EXPORT void fl_draw(const char* str, int n, int x, int y);
 /**
-  Draws an array of \a n characters right to left starting at given location.
+  Draws an array of \p n characters right to left starting at given location.
 */
 FL_EXPORT void fl_rtl_draw(const char*, int n, int x, int y);
 FL_EXPORT void fl_measure(const char* str, int& x, int& y,
@@ -311,8 +311,8 @@ FL_EXPORT void fl_draw_box(Fl_Boxtype, int x, int y, int w, int h, Fl_Color);
   signature of image generation callback function.
   \param[in]  data  user data passed to function
   \param[in]  x,y,w position and width of scan line in image
-  \param[out] buf   buffer for generated image data. You must copy \a w
-                    pixels from scanline \a y, starting at pixel \a x
+  \param[out] buf   buffer for generated image data. You must copy \p w
+                    pixels from scanline \p y, starting at pixel \p x
 		    to this buffer.
   */
 typedef void (*Fl_Draw_Image_Cb)(void* data,int x,int y,int w,uchar* buf);
@@ -327,8 +327,8 @@ typedef void (*Fl_Draw_Image_Cb)(void* data,int x,int y,int w,uchar* buf);
                  any value greater than or equal to 3, or it can be
 		 negative to flip the image horizontally
   \param[in] L   delta to add to the pointer between lines (if 0 is
-                 passed it uses \a W * \a D), and may be larger than
-		 \a W * \a D to crop data, or negative to flip the
+                 passed it uses \p W * \p D), and may be larger than
+		 \p W * \p D to crop data, or negative to flip the
 		 image vertically
 
   It is highly recommended that you put the following code before the
@@ -341,7 +341,7 @@ typedef void (*Fl_Draw_Image_Cb)(void* data,int x,int y,int w,uchar* buf);
   <tt>abs(D)</tt> is less than 3, or by calling fl_draw_image_mono().
   Only one 8-bit sample is used for each pixel, and on screens with
   different numbers of bits for red, green, and blue only gray colors
-  are used. Setting \a D greater than 1 will let you display one channel
+  are used. Setting \p D greater than 1 will let you display one channel
   of a color image.
 
   \par Note:
@@ -370,25 +370,25 @@ FL_EXPORT void fl_draw_image_mono(const uchar* buf, int X,int Y,int W,int H, int
   \param[in] D
   \see fl_draw_image(const uchar* buf, int X,int Y,int W,int H, int D, int L)
 
-  The callback function \a cb is called with the <tt>void*</tt> \a data
+  The callback function \p cb is called with the <tt>void*</tt> \p data
   user data pointer to allow access to a structure of information about
-  the image, and the \a x, \a y, and \a w of the scan line desired from
-  the image. 0,0 is the upper-left corner of the image, not \a X, \a Y.
+  the image, and the \p x, \p y, and \p w of the scan line desired from
+  the image. 0,0 is the upper-left corner of the image, not \p X, \p Y.
   A pointer to a buffer to put the data into is passed. You must copy
-  \a w pixels from scanline \a y, starting at pixel \a x, to this buffer.
+  \p w pixels from scanline \p y, starting at pixel \p x, to this buffer.
 
-  Due to cropping, less than the whole image may be requested. So \a x
-  may be greater than zero, the first \a y may be greater than zero,
-  and \a w may be less than \a W. The buffer is long enough to store
-  the entire \a W * \a D pixels, this is for convenience with some
+  Due to cropping, less than the whole image may be requested. So \p x
+  may be greater than zero, the first \p y may be greater than zero,
+  and \p w may be less than \p W. The buffer is long enough to store
+  the entire \p W * \p D pixels, this is for convenience with some
   decompression schemes where you must decompress the entire line at
-  once: decompress it into the buffer, and then if \a x is not zero,
-  copy the data over so the \a x'th pixel is at the start of the buffer.
+  once: decompress it into the buffer, and then if \p x is not zero,
+  copy the data over so the \p x'th pixel is at the start of the buffer.
 
-  You can assume the \a y's will be consecutive, except the first one
+  You can assume the \p y's will be consecutive, except the first one
   may be greater than zero.
 
-  If \a D is 4 or more, you must fill in the unused bytes with zero.
+  If \p D is 4 or more, you must fill in the unused bytes with zero.
   */
 FL_EXPORT void fl_draw_image(Fl_Draw_Image_Cb cb, void* data, int X,int Y,int W,int H, int D=3);
 
@@ -414,12 +414,12 @@ FL_EXPORT char fl_can_do_alpha_blending();
   \param[in] alpha alpha value for image (0 fr none)
   \returns pointer to pixel buffer, or NULL if allocation failed.
 
-  The \a p argument points to a buffer that can hold the image and must
-  be at least \a W*H*3 bytes when reading RGB images, or \a W*H*4 bytes
+  The \p p argument points to a buffer that can hold the image and must
+  be at least \p W*H*3 bytes when reading RGB images, or \p W*H*4 bytes
   when reading RGBA images. If NULL, fl_read_image() will create an
   array of the proper suze which can be freed using <tt>delete[]</tt>.
 
-  The \a alpha parameter controls whether an alpha channel is created
+  The \p alpha parameter controls whether an alpha channel is created
   and the value that is placed in the alpha channel. If 0, no alpha
   channel is generated.
   */