diff -r 000000000000 -r 42188c7ea2d9 Orb/Doxygen/doc/trouble.doc
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Orb/Doxygen/doc/trouble.doc	Thu Jan 21 17:29:01 2010 +0000
@@ -0,0 +1,142 @@
+/******************************************************************************
+ *
+ * 
+ *
+ * Copyright (C) 1997-2008 by Dimitri van Heesch.
+ *
+ * Permission to use, copy, modify, and distribute this software and its
+ * documentation under the terms of the GNU General Public License is hereby 
+ * granted. No representations are made about the suitability of this software 
+ * for any purpose. It is provided "as is" without express or implied warranty.
+ * See the GNU General Public License for more details.
+ *
+ * Documents produced by Doxygen are derivative works derived from the
+ * input used in their production; they are not affected by this license.
+ *
+ */
+/*! \page trouble Troubleshooting
+
+<h2>Known problems:</h2>
+<ul>
+<li>If you have problems building doxygen from sources, please 
+    read \ref unix_problems "this section" first.
+<li>Doxygen is <em>not</em> a real compiler, it is only a lexical scanner.
+    This means that it can and will not detect errors in your source code.
+<li>Since it is impossible to test all possible code fragments, it is
+    very well possible, that some valid piece of C/C++ code is not handled
+    properly. If you find such a piece, please send it to me, so I can
+    improve doxygen's parsing capabilities. Try to make the piece of code 
+    you send as small as possible, to help me narrow down the search.
+<li>Doxygen does not work properly if there are multiple classes, structs
+    or unions with the same name in your code. It should not crash however,
+    rather it should ignore all of the classes with the same name except one.
+<li>Some commands do not work inside the arguments of other commands.
+    Inside a HTML link (i.e \<a href="..."\>...\<a\>) for instance 
+    other commands (including other HTML commands) do not work!
+    The sectioning commands are an important exception. 
+<li>Redundant braces can confuse doxygen in some cases. 
+    For example:
+\verbatim
+  void f (int);
+\endverbatim
+    is properly parsed as a function declaration, but
+\verbatim
+  const int (a);
+\endverbatim
+  is also seen as a function declaration with name 
+  <code>int</code>, because only the syntax is analysed,
+  not the semantics. If the redundant braces can be detected, as in
+\verbatim
+  int *(a[20]);
+\endverbatim
+  then doxygen will remove the braces and correctly parse the result.
+<li>Not all names in code fragments that are included in the documentation
+    are replaced by links (for instance when using \c SOURCE_BROWSER = \c YES)
+    and links to overloaded members may point to the wrong member.
+    This also holds for the "Referenced by" list that is generated for
+    each function.
+
+    For a part this is because the code parser isn't smart enough at the
+    moment. I'll try to improve this in the future. But even with these
+    improvements not everything can be properly linked to the corresponding
+    documentation, because of possible ambiguities or lack of
+    information about the context in which the code fragment is found.  
+<li>It is not possible to insert a non-member function f in a class A 
+    using the \\relates or \\relatesalso command, if class A already
+    has a member with name f and the same argument list.
+<li>There is only very limited support for member specialization at the
+    moment. It only works if there is a specialized template class as
+    well.
+<li>Not all special commands are properly translated to RTF.
+<li>Version 1.8.6 of dot (and maybe earlier versions too) do not 
+    generate proper map files, causing the graphs that doxygen generates
+    not to be properly clickable.
+<li>PHP only: Doxygen requires that all PHP statements (i.e. code) is 
+    wrapped in a functions/methods, otherwise you may run into parse problems.
+</ul>
+
+
+<h2>How to help</h2>
+The development of Doxygen highly depends on your input! 
+
+If you are trying Doxygen let me know what you think of it (do you
+miss certain features?). Even if you decide not to use it, please let me
+know why. 
+
+\anchor bug_reports
+<h2>How to report a bug</h2>
+
+Bugs are tracked in GNOME's <a href="http://bugzilla.gnome.org">bugzilla</a> database.
+Before submitting a 
+<a href="http://bugzilla.gnome.org/enter_bug.cgi?product=doxygen">new bug</a>,
+first <a href="http://bugzilla.gnome.org/query.cgi?format=advanced&product=doxygen">search</a>
+through the database if the same bug has already been submitted by others (the doxygen
+product will be preselected).
+If you believe you have found a new bug, 
+please <a href="http://bugzilla.gnome.org/enter_bug.cgi?product=doxygen">report it</a>.
+
+If you are unsure whether or not something is a bug, please ask help
+on the <a href="http://sourceforge.net/mail/?group_id=5971">users mailing list</a> 
+first (subscription is required).
+
+If you send only a (vague) description of a bug, you are usually not very 
+helpful and it will cost me much more time to figure out what you mean. 
+In the worst-case your bug report may even be completely ignored by me, so
+always try to include the following information in your bug report: 
+- The version of doxygen you are using (for instance 1.5.3, use 
+  <code>doxygen --version</code> if you are not sure).
+- The name and version number of your operating system (for instance 
+  SuSE Linux 6.4)
+- It is usually a good idea to send along the configuation file as well, 
+  but please use doxygen with the <code>-s</code> flag while generating it
+  to keep it small (use <code>doxygen -s -u [configName]</code> to strip
+  the comments from an existing config file). 
+- The easiest (and often the only) way for me to fix bugs is if you can 
+  attach a small example demonstrating the problem you have to the bug report, so I can
+  reproduce it on my machine. Please make sure the example is valid
+  source code (could potentially compile) and that the problem is really 
+  captured by the example (I often get examples that do not trigger the 
+  actual bug!). If you intend to send more than one file please zip or tar
+  the files together into a single file for easier processing.
+  Note that when reporting a new bug you'll get a chance to attach a file to it 
+  only \e after submitting the initial bug description.
+
+You can (and are encouraged to) add a patch for a bug. If you do so
+please use PATCH as a keyword in the bug entry form.
+
+If you have ideas how to fix existing bugs and limitations please discuss them on 
+the <a href="http://sourceforge.net/mail/?group_id=5971">developers mailing list</a> 
+(subscription required). Patches can also be sent directly to dimitri@stack.nl if 
+you prefer not to send them via the bug tracker or mailing list.
+
+For patches please use
+"diff -uN" or include the files you modified. If you send more than
+one file please tar or zip everything, so I only have to save and download
+one file.
+
+\htmlonly
+Return to the <a href="index.html">index</a>.
+\endhtmlonly
+
+*/
+