Locate and position the current Audacity source code, and clear a variety of old junk out of the way into junk-branches

dox2-src/CrossPlatform.dox2

@@ -0,0 +1,161 @@
+/**********************************************************************
+
+  Audacity: A Digital Audio Editor
+
+  CrossPlatform.dox2
+
+  James Crook
+
+  Documents Cross Platform coding issues.
+
+********************************************************************//*
+
+JKC: The examples in this file need to be extracted into a separate file so
+that we can get the comments to show correctly in the output files.
+
+
+/*****************************************************************//*! 
+\page CrossPlatform Cross Platform Coding Tips
+\brief Guidelines for making the code compile and work on all supported platforms.
+
+\section PragmaOnce \#pragma once
+
+The following is not supported under gcc 2.x:
+
+\code
+// WRONG
+#pragma once
+\endcode
+
+Instead use the traditional:
+
+\code
+#ifndef __AUDACITY_HEADER_FILE_NAME__
+#define __AUDACITY_HEADER_FILE_NAME__
+
+// your header file contents goes here.
+
+#endif
+\endcode
+
+\section UnicodeStrings Unicode strings
+
+Audacity code is translated, and it may be built in Unicode versions.  
+For this reason all strings should be wrapped like this:
+
+\code
+   // for strings which are not translated
+   mMyFirstString = wxT("some untranslated string");
+   // for strings which should be translated
+   mMySecondString = _("some translatable string");
+\endcode
+
+In some cases you need to give hints to a translator about how a 
+string should be translated.  Do so as follows:
+
+\dontinclude examples.hh
+
+\skip i18n-hint
+\until "R"
+
+Very long strings can be wrapped across multiple lines, as follows:
+
+\code
+   // For untranslated strings:
+   wxT("This is a long untranslated string ")
+   wxT("which spans several lines ")
+   wxT("and works in Unicode builds too")
+
+   // For translated strings:
+   _("This is a long translated string "
+   wxT("which spans several lines ")
+   wxT("and works in Unicode builds too"))
+\endcode
+
+Notice that in the translated example, all bar the first substring
+are contained within a \p wxT().
+
+\section ConstructorsAsArguments Constructors as Arguments
+
+Don't write code like this:
+
+\code
+   // WRONG
+   // Now call OnSampleRateChange to update the values.
+   OnSampleRateChange( wxCommandEvent() );
+\endcode
+
+Whilst it is fine under MSVC it will cause a problem under gcc as the 
+constructor is a temporary object which will be optimised away.  
+
+Instead use:
+
+\code
+   // Now call OnSampleRateChange to update the values.
+   wxCommandEvent e;
+   OnSampleRateChange( e );
+\endcode
+
+\section HeaderFiles Header Files
+
+Windows systems are not case sensitive, whilst Linux systems are.
+You therefore need to take care in capitalisation, e.g:
+
+\code
+#include "AttachableScrollBar.h"
+\endcode
+
+\section ClassNamesInClasses Class Names in Classes
+
+Microsoft Visual C++ allows you to write code like this in a header file:
+
+\code
+// WRONG
+class MyClass 
+{
+public:
+   int MyClass::SomeFunction();
+   //... other stuff
+\endcode
+
+For portability, the \p 'MyClass::' prefix should be left out. 
+
+\section wxStringInFormat Using wxString in Format
+
+Don't write code like this:
+
+\code
+   wxString Message( wxT("Hello" )); 
+   // WRONG
+   wxString Temp = wxString::Format(wxT("Your said %s in your message"), Message );
+\endcode
+
+Although MSVC won't complain even in Unicode mode, it generates a warning under gcc.
+Instead you need:
+
+\code
+   wxString Message( wxT("Hello" )); 
+   wxString Temp = wxString::Format(wxT("Your said %s in your message"), Message.c_str() );
+\endcode
+   
+   
+\section ForwardEnums Forward Declared Enums
+
+Microsoft Visual C++ allows you to write code like this in a header file:
+
+\code
+// WRONG
+enum MyEnum;
+\endcode
+
+That is, you can forward declare an enum just as you can forward 
+declare a class.  This is not portable.  The alternative is to include
+a header file containing the full enum definition.
+
+\code
+#include "MyEnum.h"
+\endcode
+
+
+
+*//*****************************************************************/