Fixed some typos and links and added a section about document structure

and some more to development.dox.


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

6 files changed, 170 insertions, 78 deletions

diff --git a/FL/Fl_Color_Chooser.H b/FL/Fl_Color_Chooser.H
index 34a12c436..66d0f16f0 100644
--- a/FL/Fl_Color_Chooser.H
+++ b/FL/Fl_Color_Chooser.H
@@ -120,7 +120,7 @@ public:
   /**
     Returns the current hue.
     0 <= hue < 6. Zero is red, one is yellow, two is green, etc.
-    <em>This value is convienent for the internal calculations - some other
+    <em>This value is convenient for the internal calculations - some other
     systems consider hue to run from zero to one, or from 0 to 360.</em>
    */
   double hue() const {return hue_;}
diff --git a/documentation/development.dox b/documentation/development.dox
index c869a1040..2bc512c01 100644
--- a/documentation/development.dox
+++ b/documentation/development.dox
@@ -116,92 +116,177 @@ Gizmo.cxx:
 
 <H3>Example comment:</H3>
 
+You can use HTML comment statements to embed comments in doxygen comment blocks.
+These comments will not be visible in the generated document.
+
+    The following text is a developer comment.
+    <!-- *** This *** is *** invisible *** -->
+    This will be visible again.
+
 \code
-The following text is a comment within a doxygen comment block and
-will not appear in the generated document:
-<!-- Editor's note:
-   ** Caution: the following text contains utf-8 encoded characters.
--->
-This will be visible again.
+    The following text is a developer comment.
+    <!-- *** This *** is *** invisible *** -->
+    This will be visible again.
 \endcode
 
-The following text is a comment within a doxygen comment block and
-will not appear in the generated document:
-<!-- Editor's note:
-   ** Caution: the following text contains utf-8 encoded characters.
--->
-This will be visible again.
+
+<H3>Different Headlines:</H3>
 
 \code
-<H1>Headline in big text</H1>
-<H2>Headline in big text</H2>
-<H3>Headline in big text</H3>
-<H4>Headline in big text</H4>
+    <H1>Headline in big text (H1)</H1>
+    <H2>Headline in big text (H2)</H2>
+    <H3>Headline in big text (H3)</H3>
+    <H4>Headline in big text (H4)</H4>
 \endcode
 
-<H1>Headline in big text</H1>
-<H2>Headline in big text</H2>
-<H3>Headline in big text</H3>
-<H4>Headline in big text</H4>
+    <H1>Headline in big text (H1)</H1>
+    <H2>Headline in big text (H2)</H2>
+    <H3>Headline in big text (H3)</H3>
+    <H4>Headline in big text (H4)</H4>
+
+
+\section development_non-ascii Non-ASCII characters
 
+	if you came here from below: back to \ref development_links
 
-<P>Assuming that the following source code was written on MS Windows, 
-this example will output the correct label on OS X and X11 as well.
-Without the conversion call, the label on OS X would read 
-<tt>Fahrvergn¸gen</tt> with a deformed umlaut u ("cedille",
-html "&cedil;").
 \code
-  btn = new Fl_Button(10, 10, 300, 25);
-  btn->copy_label(fl_latin1_to_local("Fahrvergnügen"));
+    Doxygen understands many HTML quoting characters like
+    &quot;, &uuml;, &ccedil;, &Ccedil;, but not all HTML quoting characters.
 \endcode
 
-\note	If your application uses characters that are not part of both
-	encodings, or it will be used in areas that commonly use different
-	code pages, you might consider upgrading to FLTK 2 which supports
-	UTF-8 encoding. 
+This will appear in the document:
 
-\todo	This is an example todo entry, please ignore !
+    Doxygen understands many HTML quoting characters like
+    &quot;, &uuml;, &ccedil;, &Ccedil;, but not all HTML quoting characters.
 
-\code
+For further informations about quoting see 
+    \b http://www.stack.nl/~dimitri/doxygen/htmlcmds.html
 
-<!-- Editor's note:
-   ** Caution: the following text contains utf-8 encoded characters.
-   ** be careful when using non-utf-8-aware editors !
--->
+<H3>Example with UTF-8 encoded text</H3>
 
-<P>Assuming that the following source code was written on MS Windows, 
-this example will output the correct label on OS X and X11 as well.
-Without the conversion call, the label on OS X would read 
-<tt>Fahrvergn¸gen</tt> with a deformed umlaut u ("cedille",
-html "&cedil;").
 \code
-  btn = new Fl_Button(10, 10, 300, 25);
-  btn->copy_label(fl_latin1_to_local("Fahrvergnügen"));
-\endcode
 
-\note	If your application uses characters that are not part of both
-	encodings, or it will be used in areas that commonly use different
-	code pages, you might consider upgrading to FLTK 2 which supports
-	UTF-8 encoding. 
+    <P>Assuming that the following source code was written on MS Windows, 
+    this example will output the correct label on OS X and X11 as well.
+    Without the conversion call, the label on OS X would read 
+    <tt>Fahrvergn¸gen</tt> with a deformed umlaut u ("cedille",
+    html "&cedil;").
+    \#code
+      btn = new Fl_Button(10, 10, 300, 25);
+      btn->copy_label(fl_latin1_to_local("Fahrvergnügen"));
+    \#endcode
 
-\todo	This is an example todo entry, please ignore !
+    \note   If your application uses characters that are not part of both
+	    encodings, or it will be used in areas that commonly use different
+	    code pages, you might consider upgrading to FLTK 2 which supports
+	    UTF-8 encoding. 
 
-\endcode
+    \todo   This is an example todo entry, please ignore !
 
+\endcode
 
-<H2>Creating Links</H2>
+This will appear in the document:
+
+    <P>Assuming that the following source code was written on MS Windows, 
+    this example will output the correct label on OS X and X11 as well.
+    Without the conversion call, the label on OS X would read 
+    <tt>Fahrvergn¸gen</tt> with a deformed umlaut u ("cedille",
+    html "&cedil;").
+    \#code
+      btn = new Fl_Button(10, 10, 300, 25);
+      btn->copy_label(fl_latin1_to_local("Fahrvergnügen"));
+    \#endcode
+
+    \note   If your application uses characters that are not part of both
+	    encodings, or it will be used in areas that commonly use different
+	    code pages, you might consider upgrading to FLTK 2 which supports
+	    UTF-8 encoding. 
+
+    \todo   This is an example todo entry, please ignore !
+
+\section development_structure Document Structure
+
+  \li	\b \\page	creates a named page
+  \li	\b \\section	creates a named section within that page
+  \li	\b \\subsection	creates a named subsection within that page
+
+The page, section, and subsection titles are formatted in blue color and
+a size like \b "<H1>", \b "<H2>", and \b "<H3>", respectively.
+
+By <b>FLTK documentation convention</b>, a file like this one with a doxygen
+documentation chapter has the name <b>"<chapter>.dox".</b>
+The \b \\page statement at the top of the page is 
+<b>"\page <chapter> This is the title"</b>.
+Sections within a documentation page must be called \b "<chapter>_<section>",
+where \b "<chapter>" is the name part of the file, and \b "<section>" is a
+unique section name within the page that can be referenced in links.
+
+These doxygen page and section commands work only in special documentation
+chapters, not within normal source or header documentation blocks. However,
+links to documentation sections \b should work.
+
+\todo	Verify, that links in (from) source documentation to documentation
+	pages and sections or subsections work.
+
+This page has
+  \code
+	\page development I - Developer Information
+  \endcode
+at its top.
+
+This section is
+  \code
+	\section development_structure Document structure
+  \endcode
+
+The following section is
+  \code
+	\section development_links Creating Links
+  \endcode
+
+\section development_links Creating Links
+
+Links to other documents and external links can be embedded with
+  \li	normal HTML links
+  \li	HTML links without markup - doxygen creates "http://..."
+  	links automatically
+  \li	links to other doxygen chapters with the \\ref statments
+  \li	links to named sections within the same or other doxygen chapters,
+  	if they are defined there with a \\section statement
 
 \code
-see chapter \ref unicode creates a link to the named chapter unicode
-that has been created with a \subpage statement.
-	
-see <a href="drawing.html#character_encoding">chapter 5</a> creates
-a link to a named html anchor "character_encoding" within the same file.
+    see chapter \ref unicode creates a link to the named chapter unicode
+    that has been created with a \subpage statement.
+
+    see <a href="drawing.html#character_encoding">chapter 5</a> creates
+    a link to a named html anchor "character_encoding" within the same file.
+
+    For further informations about quoting see
+    http://www.stack.nl/~dimitri/doxygen/htmlcmds.html
+
+    Bold link text: you can see the <b>\e old online documentation</b>
+    of FLTK 1.3 at \b http://www.fltk.org/doc-1.3/toc.html
+    
+    see section \ref development_non-ascii
 \endcode
-see chapter \ref unicode creates a link to the named chapter unicode
-that has been created with a \subpage statement.
-	
-see <a href="drawing.html#character_encoding">chapter 5</a> creates
-a link to a named html anchor "character_encoding" within the same file.
 
+appears as:
+
+    see chapter \ref unicode creates a link to the named chapter unicode
+    that has been created with a \\subpage statement.
+
+    see <a href="drawing.html#character_encoding">chapter 5</a> creates
+    a link to a named html anchor "character_encoding" within the same file.
+
+    For further informations about quoting see
+    http://www.stack.nl/~dimitri/doxygen/htmlcmds.html
+
+    Bold link text: you can see the <b>\e old online documentation</b>
+    of FLTK 1.3 at \b http://www.fltk.org/doc-1.3/toc.html
+    
+    see section \ref development_non-ascii
+
+  \subsection development_subsection_01 Subsection Number 1
+
+    Text in Subsection Number 1.
 */
diff --git a/documentation/fluid.dox b/documentation/fluid.dox
index b29156713..17b25297d 100644
--- a/documentation/fluid.dox
+++ b/documentation/fluid.dox
@@ -10,23 +10,23 @@
 <LI><A HREF="#what_is_fluid">What is FLUID</A></LI>
 <LI><A HREF="#fluid_under_linux">Running FLUID Under UNIX</A></LI>
 <LI><A HREF="#fluid_under_windows">Running FLUID Under Microsoft Windows</A></LI>
-<LI><A HREF="#compiling_fl_files">Compiling <TT>.fl</TT> files</A></LI>
+<LI><A HREF="#compiling_fl_files">Compiling <TT>.fl</TT> Files</A></LI>
 <LI><A HREF="#tutorial">A Short Tutorial</A></LI>
 <LI><A HREF="#references">FLUID Reference</A></LI>
 <LI><A HREF="#I18N">Internationalization with FLUID</A></LI>
-<LI><A HREF="#limitations">Know limitations</A></LI>
+<LI><A HREF="#limitations">Known Limitations</A></LI>
 </UL></P>
 
 <H2><A NAME="what_is_fluid">What is FLUID?</A></H2>
 
 <P>The Fast Light User Interface Designer, or FLUID, is a
 graphical editor that is used to produce FLTK source code. FLUID
-edits and saves its state in <TT>.fl</TT> files.  These files
+edits and saves its state in <TT>.fl</TT> files. These files
 are text, and you can (with care) edit them in a text editor,
 perhaps to get some special effects.</P>
 
 <P>FLUID can "compile" the <TT>.fl</TT> file into a
-<TT>.cxx</TT> and a <TT>.h</TT> file.  The <TT>.cxx</TT> file
+<TT>.cxx</TT> and a <TT>.h</TT> file. The <TT>.cxx</TT> file
 defines all the objects from the <TT>.fl</TT> file and the
 <TT>.h</TT> file declares all the global ones. FLUID also
 supports localization (<A HREF="#I18N">Internationalization</A>)
@@ -162,7 +162,7 @@ The CubeView class is a subclass of Fl_Gl_Window. It has methods for
 setting the zoom, the <i>x</i> and <i>y</i> pan, and the rotation angle
 about the <i>x</i> and <i>y</i>axes.
 <p>You can safely skip this section as long as you realize the CubeView
-is a sublass of <tt>Fl_Gl_Window</tt> and will respond to calls from
+is a sublass of Fl_Gl_Window and will respond to calls from
 CubeViewUI, generated by FLUID.
 <h4><a name="def">The CubeView Class Definition</a></h4>
 Here is the CubeView class definition, as given by its header file
@@ -405,16 +405,17 @@ shortly.
 defined the CubeView class and we would like to show it within the
 CubeViewUI.
 
-<p>The CubeView class inherits the <tt>Fl_Gl_Window</tt> class, which
-is created in the same way as a <tt>Fl_Box</tt> widget. Use
+<p>The CubeView class inherits the Fl_Gl_Window class, which
+is created in the same way as a Fl_Box widget. Use
 <b>New->Other->Box</b> to add a square box to the main window.
 This will be no ordinary box, however.
 
 <p>The Box properties window will appear. The key to letting CubeViewUI
 display CubeView is to enter CubeView in the "Class:" text
-entry box. This tells FLUID that it is not an <tt>Fl_Box</tt>, but a
-similar widget with the same constructor. In the "Extra
-Code:" field enter <tt>\#include "CubeView.h"</tt>
+entry box. This tells FLUID that it is not an Fl_Box, but a
+similar widget with the same constructor. 
+
+In the "Extra Code:" field enter <tt>\#include "CubeView.h"</tt>
 
 <p>This <tt>\#include</tt> is important, as we have just included
 CubeView as a member of CubeViewUI, so any public CubeView methods are
diff --git a/src/Fl_Menu_.cxx b/src/Fl_Menu_.cxx
index 3701ea1d0..851cf001b 100644
--- a/src/Fl_Menu_.cxx
+++ b/src/Fl_Menu_.cxx
@@ -226,7 +226,7 @@ void Fl_Menu_::copy(const Fl_Menu_Item* m, void* ud) {
   memcpy(newMenu, m, n*sizeof(Fl_Menu_Item));
   menu(newMenu);
   alloc = 1; // make destructor free array, but not strings
-  // for convienence, provide way to change all the user data pointers:
+  // for convenience, provide way to change all the user data pointers:
   if (ud) for (; n--;) {
     if (newMenu->callback_) newMenu->user_data_ = ud;
     newMenu++;
diff --git a/src/Fl_Text_Buffer.cxx b/src/Fl_Text_Buffer.cxx
index 7bb18a948..d78860055 100644
--- a/src/Fl_Text_Buffer.cxx
+++ b/src/Fl_Text_Buffer.cxx
@@ -213,7 +213,13 @@ void Fl_Text_Buffer::text(const char *t) {
 /**
    Return a copy of the text between "start" and "end" character positions
    from text buffer "buf".  Positions start at 0, and the range does not
-   include the character pointed to by "end"
+   include the character pointed to by "end".
+
+ - - -
+ 
+   Return a copy of the text between \a start and \a end character positions
+   from text buffer \a buf. Positions start at 0, and the range does not
+   include the character pointed to by \a end.
    When you are done with the text, free it using the free() function.
 */
 char * Fl_Text_Buffer::text_range(int start, int end) {
@@ -1327,7 +1333,7 @@ int Fl_Text_Buffer::findchars_backward(int startPos, const char *searchChars,
    The primary routine for integrating new text into a text buffer with
    substitution of another character for ascii nuls.  This substitutes null
    characters in the string in preparation for being copied or replaced
-   into the buffer, and if neccessary, adjusts the buffer as well, in the
+   into the buffer, and if necessary, adjusts the buffer as well, in the
    event that the string contains the character it is currently using for
    substitution.  Returns 0, if substitution is no longer possible
    because all non-printable characters are already in use.
diff --git a/src/Fl_Widget.cxx b/src/Fl_Widget.cxx
index e03a44312..24f3a02ff 100644
--- a/src/Fl_Widget.cxx
+++ b/src/Fl_Widget.cxx
@@ -37,7 +37,7 @@
 ////////////////////////////////////////////////////////////////
 // for compatibility with Forms, all widgets without callbacks are
 // inserted into a "queue" when they are activated, and the forms
-// compatibility interaction functions (fl_do_events, etc) will
+// compatibility interaction functions (fl_do_events, etc.) will
 // read one widget at a time from this queue and return it:
 
 const int QUEUE_SIZE = 20;
@@ -136,7 +136,7 @@ extern void fl_throw_focus(Fl_Widget*); // in Fl_x.cxx
 /**
    Destroys the widget, taking care of throwing focus before if any.
    Destruction does not remove from any parent group!  And groups when
-   destroyed destroy all their children.  This is convienent and fast.
+   destroyed destroy all their children.  This is convenient and fast.
    However, it is only legal to destroy a "root" such as an Fl_Window,
    and automatic destructors may be called.
 */