now renaming restoring dir src_doc src.

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

1 files changed, 462 insertions, 0 deletions

diff --git a/documentation/src/development.dox b/documentation/src/development.dox
new file mode 100644
index 000000000..616619c88
--- /dev/null
+++ b/documentation/src/development.dox
@@ -0,0 +1,462 @@
+/**
+
+ \page development I - Developer Information
+
+This chapter describes FLTK development and documentation.
+
+\note	documentation with doxygen will be described here.
+
+
+<H2>Example</H2>
+
+\note
+
+In the following code example(s) "*" will be replaced by "#"
+as a temporary solution.
+
+\code
+
+
+/## \file
+   Fl_Clock, Fl_Clock_Output widgets . #/
+
+
+/##
+  \class Fl_Clock_Output
+  \brief This widget can be used to display a program-supplied time.
+  
+  The time shown on the clock is not updated. To display the current time,
+  use Fl_Clock instead.
+
+  \image html clock.gif 
+  \image latex clock.eps "" width=10cm 
+  \image html round_clock.gif
+  \image latex clock.eps "" width=10cm 
+  \image html round_clock.eps "" width=10cm #/
+
+  /##
+    Returns the displayed time.
+    Returns the time in seconds since the UNIX epoch (January 1, 1970).
+    \see value(ulong)
+   #/
+  ulong value() const {return value_;}
+
+/##
+  Set the displayed time.
+  Set the time in seconds since the UNIX epoch (January 1, 1970).
+  \param[in] v seconds since epoch
+  \see value()
+ #/
+void Fl_Clock_Output::value(ulong v) {
+ [...]
+}
+
+/##
+  Create an Fl_Clock widget using the given position, size, and label string.
+  The default boxtype is \c FL_NO_BOX.
+  \param[in] X, Y, W, H position and size of the widget
+  \param[in] L widget label, default is no label
+ #/
+Fl_Clock::Fl_Clock(int X, int Y, int W, int H, const char #L)
+  : Fl_Clock_Output(X, Y, W, H, L) {}
+
+/##
+  Create an Fl_Clock widget using the given boxtype, position, size, and
+  label string.
+  \param[in] t boxtype
+  \param[in] X, Y, W, H position and size of the widget
+  \param[in] L widget label, default is no label
+ #/
+Fl_Clock::Fl_Clock(uchar t, int X, int Y, int W, int H, const char #L)
+  : Fl_Clock_Output(X, Y, W, H, L) {
+  type(t);
+  box(t==FL_ROUND_CLOCK ? FL_NO_BOX : FL_UP_BOX);
+}
+
+
+\endcode
+
+
+\note
+
+From Duncan: (will be removed later, just for now as a reminder)
+
+5. I've just added comments for the fl_color_chooser() functions, and
+   in order to keep them and the general Function Reference information
+   for them together, I created a new doxygen group, and used \\ingroup
+   in the three comment blocks. This creates a new Modules page (which
+   may not be what we want) with links to it from the File Members and
+   Fl_Color_Chooser.H pages. It needs a bit more experimentation on my
+   part unless someone already knows how this should be handled. (Maybe
+   we can add it to a functions.dox file that defines a functions group
+   and do that for all of the function documentation?)
+
+\b Update: the trick is not to create duplicate entries in a new group, but
+   to move the function information into the doxygen comments for the
+   class, and use the navigation links provided. Simply using \\relatesalso
+   as the first doxygen command in the function's comment puts it in the
+   appropriate place. There is no need to have \\defgroup and \\ingroup as
+   well, and indeed they don't work. So, to summarize:
+\code
+Gizmo.H
+  /## \class Gizmo
+      A gizmo that does everything
+    #/
+  class Gizmo {
+    etc
+  };
+  extern int popup_gizmo(...);
+
+Gizmo.cxx:
+  /## \relatesalso Gizmo
+      Pops up a gizmo dialog with a Gizmo in it
+    #/
+  int popup_gizmo(...);
+\endcode
+
+<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 developer comment.
+    <!-- *** This *** is *** invisible *** -->
+    This will be visible again.
+\endcode
+
+
+<H3>Different Headlines:</H3>
+
+\code
+    <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)</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
+
+\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
+
+    \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 !
+
+\endcode
+
+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 the current section
+  \li	\b \\subsubsection creates a named subsubsection within the current subsection
+
+All these statements take a "name" as their first argument, and a title
+as their second argument. The title can contain spaces.
+
+The page, section, and subsection titles are formatted in blue color and
+a size like \b "<H1>", \b "<H2>", and \b "<H3>", and \b "<H4>", 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. The
+same for subsections and subsubsections.
+
+These doxygen page and section commands work only in special documentation
+chapters, not within normal source or header documentation blocks. However,
+links \b from normal (e.g. class) documentation \b to documentation sections
+\b do \b 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.
+
+    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
+
+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
+
+\section development_old-links Changing Old Links
+
+Old HTML links and anchors in text documentation pages should be changed
+as follows:
+
+\code
+<H2><A name="event_xxx">Fl::event_*() methods</A></H2>
+
+becomes:
+
+<A NAME="event_xxx"></A> <!-- For old HTML links only ! -->
+\section events_event_xxx Fl::event_*() methods
+\endcode
+
+The additional HTML "<A NAME=...>" statement is temporary needed, until
+all links (references) are modified, then:
+
+\code
+<H2><A name="event_xxx">Fl::event_*() methods</A></H2>
+
+becomes:
+
+\section events_event_xxx Fl::event_*() methods
+\endcode
+
+The "\section" statement can also be a "\subsection" or "\subsubsection"
+statement.
+
+The references (in this example from index.dox) are changed as follows:
+
+\code
+
+ \subpage events
+
+    <B>
+      <UL>
+	<LI><A HREF="events.html#event_xxx">Fl::event_*() methods</A></LI>
+	<LI><A HREF="events.html#propagation">Event Propagation</A></LI>
+      </UL>
+    </B>
+
+becomes:
+
+ \subpage events
+
+    <b>
+	\li \ref events_event_xxx
+	\li \ref events_propagation
+    </b>
+
+\endcode
+
+
+\section development_paragraphs Paragraph Layout
+
+There is no real need to use HTML \<P\> and \</P\> tags within the text
+to tell doxygen to start or stop a paragraph. In most cases, when doxygen
+encounters a blank line or some, but not all, \b \\commands in the text it
+knows that it as reached the start or end of a paragraph. Doxygen also
+offers the \b \\par command for special paragraph handling. It can be used
+to provide a paragraph title and also to indent a paragraph. Unfortunately
+\b \\par won't do what you expect if you want to have doxygen links and
+sometimes html tags don't work either.
+
+  <!-- use verbatim rather than code to avoid links to code reference -->
+  \verbatim
+    \par Normal Paragraph with title
+
+    This paragraph will have a title, but because there is a blank line
+    between the \par and the text, it will have the normal layout.
+
+    \par Indented Paragraph with title
+    This paragraph will also have a title, but because there is no blank
+    line between the \par and the text, it will be indented.
+
+    \par
+    It is also possible to have an indented paragraph without title.
+    This is how you indent subsequent paragraphs.
+
+    \par No link to Fl_Widget::draw()
+    Note that the paragraph title is treated as plain text.
+    Doxygen type links will not work.
+    HTML characters and tags may or may not work.
+
+    Fl_Widget::draw() links and &quot;html&quot; tags work<br>
+    \par
+    Use a single line ending with <br> for complicated paragraph titles.
+  \endverbatim
+
+The above code produces the following paragraphs:
+
+    \par Normal Paragraph with title
+
+    This paragraph will have a title, but because there is a blank line
+    between the \\par and the text, it will have the normal layout.
+
+    \par Indented Paragraph with title
+    This paragraph will also have a title, but because there is no blank
+    line between the \\par and the text, it will be indented.
+
+    \par
+    It is also possible to have an indented paragraph without title.
+    This is how you indent subsequent paragraphs.
+
+    \par No link to Fl_Widget::draw()
+    Note that the paragraph title is treated as plain text.
+    Doxygen type links will not work.
+    HTML characters and tags may or may not work.
+
+    Fl_Widget::draw() links and &quot;html&quot; tags work<br>
+    \par
+    Use a single line ending with \<br\> for complicated paragraph titles.
+
+
+\section development_html_footer Hack for missing "tiny.gif" file
+
+  \todo
+	*HACK* : include image file for footer. Doxygen does not include
+  	the file "tiny.gif" from "html_footer" in its output html dir.
+	Find out, how this can be done, or avoid using an image in
+	the HTML footer.
+
+  \image html tiny.gif
+  \image latex tiny.eps "" width=2cm	
+
+\section development_navigation_test 5 Navigation Proposals
+
+\htmlonly
+<hr>
+\link migration_1_3 [ Previous ] \endlink
+<b>    [ <a href="index.html">Index</a> ]    </b>
+<b> Next: </b> \ref license
+
+<hr>
+<b>[ <a href="index.html">Index</a> ]    </b>
+<b>   Previous: </b> \ref migration_1_3
+<b>   Next: </b> \ref license
+
+<hr>
+<b>[ <a href="index.html">Index</a> ]    </b><br>
+<b>   Previous: </b> \ref migration_1_3 <br>
+<b>   Next: </b> \ref license
+
+<hr>
+<b>[ <a href="index.html">Index</a> ]    </b>
+   Previous:  \ref migration_1_3
+   Next:  \ref license
+
+<hr>
+\link migration_1_3 [ Previous ] \endlink
+<b>    [ <a href="index.html">Top</a> ]    </b>
+\link license [ Next ] \endlink
+
+<hr>
+<br>
+<br>
+
+\section development_proposed_nav Proposed (final) Navigation Elements
+
+See below.
+
+<hr>
+<a class="el" href="index.html">[Index]</a> &nbsp;&nbsp;
+<a class="el" href="migration_1_3.html">[Previous]</a>&nbsp;
+     \ref migration_1_3 &nbsp;&nbsp;
+<a class="el" href="license.html">[Next]</a>&nbsp;
+     \ref license
+
+\endhtmlonly
+*/