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
2008-09-20 22:46:24 +00:00 · 2008-09-20 22:46:24 +00:00 · b804e1f3ab
commit b804e1f3ab
parent fd407c7775
6 changed files with 186 additions and 94 deletions
--- 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_;}
--- 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>


-<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;").
+\section development_non-ascii Non-ASCII characters
+
+	if you came here from below: back to \ref development_links
+
 \code
+    Doxygen understands many HTML quoting characters like
+    &quot;, &uuml;, &ccedil;, &Ccedil;, but not all HTML quoting characters.
+\endcode
+
+This will appear in the document:
+
+    Doxygen understands many HTML quoting characters like
+    &quot;, &uuml;, &ccedil;, &Ccedil;, but not all HTML quoting characters.
+
+For further informations about quoting see 
+    \b http://www.stack.nl/~dimitri/doxygen/htmlcmds.html
+
+<H3>Example with UTF-8 encoded text</H3>
+
+\code
+
+    <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
+    \#endcode

-\note	If your application uses characters that are not part of both
+    \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 !
+    \todo   This is an example todo entry, please ignore !

-\code
-
-<!-- Editor's note:
-   ** Caution: the following text contains utf-8 encoded characters.
-   ** be careful when using non-utf-8-aware editors !
-->
-
-<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
+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 !
+    \todo   This is an example todo entry, please ignore !

-\endcode
+\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

-<H2>Creating Links</H2>
+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 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 <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.
 */
--- a/documentation/fluid.dox
+++ b/documentation/fluid.dox
@ -10,11 +10,11 @@
 <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>
@ -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
--- 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++;
--- 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.
--- 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.
 */