Re: uSTL documentation patch

Re: uSTL documentation patch

[John Dallaway]

Hi Uwe

> the following patches add SGML documentation to uSTL library
> package. I'm not a native speaker - so any correcting patches
> are welcome ;O).

I added cout.flush() to the hello world example and added a
documentation reference in ustl.cdl. Checked-in.

Thank you

John Dallaway

uSTL documentation patch

[uwe.kindler]

[-- Attachment #1: Type: text/plain, Size: 149 bytes --]

Hi,

the following patches add SGML documentation to uSTL library package. I'm not a native speaker - so any correcting patches are welcome ;O).

Uwe

[-- Attachment #2: ustl_doc.patch --]
[-- Type: application/octet-stream, Size: 10492 bytes --]

diff -ruN ecos_web_cvs/ecos/packages/language/cxx/ustl/current/ChangeLog ecos/ecos/packages/language/cxx/ustl/current/ChangeLog
--- ecos_web_cvs/ecos/packages/language/cxx/ustl/current/ChangeLog	2009-08-24 09:07:18.368427800 +0200
+++ ecos/ecos/packages/language/cxx/ustl/current/ChangeLog	2009-08-24 11:06:04.707942000 +0200
@@ -1,3 +1,9 @@
+2009-08-24  Uwe Kindler <uwe_kindler@web.de>
+
+	* doc/ustl.sgml Moved documentation from README file into
+	ustl.sgml documentation file.
+	* tests/stdtest.h Removed unused code
+
 2009-08-21  Sergei Gavrikov  <sergei.gavrikov@gmail.com>
 
 	* src/bktrace.cpp: prevent inclusion of host header <execinfo.h>
diff -ruN ecos_web_cvs/ecos/packages/language/cxx/ustl/current/README ecos/ecos/packages/language/cxx/ustl/current/README
--- ecos_web_cvs/ecos/packages/language/cxx/ustl/current/README	2009-08-24 09:07:18.649674200 +0200
+++ ecos/ecos/packages/language/cxx/ustl/current/README	1970-01-01 01:00:00.000000000 +0100
@@ -1,51 +0,0 @@
-Welcome to uSTL Library 1.3
-===========================
-
-The eCos uSTL library is a port of Mike Sharov's uSTL implementation. 
-It has the particular feature of generating small object code sizes 
-- an important requirement for embedded eCos based applications.
-The latest version can be found at:
-
-   http://ustl.sourceforge.net/
-   http://sourceforge.net/projects/ustl/
-   
-The library provides a subset of the full C++ STL standard library.
-uSTL is a partial implementation of the STL specification intended to 
-reduce code size of the derivative programs. This allows the 
-eCos application to use well known standard C++ STL library 
-containers, streams, iterators, algorithms and functors.
-
-For changes, see the HISTORY file.
-
-
-eCos port specific changes/enhancements
----------------------------------------
-
-By default eCos is build without exceptions and without  RTTI support 
-(compiler switches -fno-exceptions -fno-rtti). Normally the  uSTL 
-library relies on C++ exceptions to propagate errors and exceptions. 
-To build the library for eCos all occurrences of try, cath and throw 
-are replaced by macros USLT_TRY, USLT_CATCH_ALL, and USLT_THROW. Thus
-the eCos uSTL port compiles without exceptions and without RTTI support.
-
-The macro USLT_THROW calls an eCos specific exception handling function
-that prints exception information to the diagnostic channel.
-
-All features of the uSTL library are available except for memory mapped
-files or memory mapped streams.
-
-If you use cout for printing to the console you should know that the
-data is only sent if you finish all output with endl and then call
-cout.flush().
-
-example:
-
-cout << "Console output" << endl;
-cout.flush();
-
-
-Legal Stuff
------------
-
-The uSTL library is subject of copyright under MIT license. For
-the license text see LICENSE file.
diff -ruN ecos_web_cvs/ecos/packages/language/cxx/ustl/current/doc/ustl.sgml ecos/ecos/packages/language/cxx/ustl/current/doc/ustl.sgml
--- ecos_web_cvs/ecos/packages/language/cxx/ustl/current/doc/ustl.sgml	1970-01-01 01:00:00.000000000 +0100
+++ ecos/ecos/packages/language/cxx/ustl/current/doc/ustl.sgml	2009-08-23 12:59:06.000000000 +0200
@@ -0,0 +1,152 @@
+<!-- {{{ Banner                         -->
+
+<!-- =============================================================== -->
+<!--                                                                 -->
+<!--     ustl.sgml                                                  -->
+<!--                                                                 -->
+<!--     eCos uSTL library port                                         -->
+<!--                                                                 -->
+<!-- =============================================================== -->
+<!-- ####ECOSDOCCOPYRIGHTBEGIN####                                       -->
+<!-- ===============================================================     -->
+<!-- Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc. -->
+<!-- This material may be distributed only subject to the terms          -->
+<!-- and conditions set forth in the Open Publication License, v1.0      -->
+<!-- or later (the latest version is presently available at              -->
+<!-- http://www.opencontent.org/openpub/)                                -->
+<!-- Distribution of the work or derivative of the work in any           -->
+<!-- standard (paper) book form is prohibited unless prior               -->
+<!-- permission obtained from the copyright holder                       -->
+<!-- ===============================================================     -->
+<!-- ####ECOSDOCCOPYRIGHTEND####                                         -->
+<!-- =============================================================== -->
+<!-- #####DESCRIPTIONBEGIN####                                       -->
+<!--                                                                 -->
+<!-- ####DESCRIPTIONEND####                                          -->
+<!-- =============================================================== -->
+
+<!-- }}} -->
+
+<PART id="ustl">
+<TITLE>The uSTL library port</TITLE>
+<CHAPTER id="ustl-overview">
+<TITLE>uSTL library overview</TITLE>
+<PARA>
+The eCos uSTL library is a port of Mike Sharov's uSTL implementation
+ - a size-optimized STL. It has the particular feature of generating small 
+object code sizes - an important requirement for embedded eCos based 
+applications. The latest version can be found at 
+<ulink url="http://sourceforge.net/projects/ustl">http://sourceforge.net/projects/ustl</ulink>.
+</PARA>
+
+<PARA>
+The library provides a subset of the full C++ 
+<ulink url="http://en.wikipedia.org/wiki/Standard_Template_Library">
+STL standard library</ulink>.
+uSTL is a partial implementation of the STL specification intended to 
+reduce code size of the derivative programs. This allows eCos applications
+to use well known standard C++ STL library containers, streams, 
+iterators, algorithms and functors.
+</PARA>
+
+<PARA>
+For changes, see the <filename>HISTORY</filename> file. A detailed introduction 
+of the uSTL library is available on Mike Sharov's 
+<ulink url="http://ustl.sourceforge.net/">uSTL web page</ulink>. 
+Additional information on all the classes is available in the header 
+files and in the <ulink url="http://ustl.sourceforge.net/html/index.html">
+Doxygen reference</ulink>.
+</PARA>
+<SECT1 id="ustl-ecos-changes">
+<TITLE>eCos specific changes/enhancements</TITLE>
+
+<PARA>
+All features of the uSTL library are available except for memory mapped
+files or memory mapped streams.
+</PARA>
+
+<PARA>
+By default an eCos image is build without exceptions and without RTTI support 
+(compiler switches -fno-exceptions -fno-rtti). Normally the uSTL 
+library relies on C++ exceptions to propagate errors and exceptions.
+To build uSTL for eCos all occurrences of <FUNCTION>try</FUNCTION>, 
+<FUNCTION>catch</FUNCTION> and <FUNCTION>throw</FUNCTION> 
+are replaced by macros <varname>USTL_TRY</varname>, 
+<varname>USTL_CATCH_ALL</varname>, and 
+<varname>USTL_THROW</varname>. Thus the eCos uSTL port compiles without 
+exceptions and without RTTI support but also works if RTTI and exceptions 
+are enabled.
+</PARA>
+
+<PARA>
+To handle and propagate uSTL exceptions when RTTI und C++ exceptions are 
+not available the eCos uSTL port was extended by some simple exception 
+handling functions. An application can use the function 
+<FUNCTION>ustl::set_app_exception_handler()</FUNCTION> to register an
+exception handler that is called by the <varname>USTL_THROW</varname> 
+macro as soon as an exception is thrown by any uSTL function.
+</PARA>
+
+<PROGRAMLISTING>
+void ustl::set_app_exception_handler(app_exception_handler_t func);
+</PROGRAMLISTING>
+
+<PARA>
+If an exception handler is registered by an application then it replaces the 
+default eCos uSTL exception handler. The default exception handler simply 
+prints the error message of an exception to the diagnostic channel by calling 
+<FUNCTION>void ustl::diag_print_exception().</FUNCTION> This function
+can be called also from an application exception handler like it is done 
+in all test cases.
+</PARA>
+
+<PROGRAMLISTING>
+void ustl::set_app_exception_handler(app_exception_handler_t func);
+</PROGRAMLISTING>
+</SECT1>
+
+<SECT1 id="using-ustl-library">
+<TITLE>Using uSTL in eCos applications</TITLE>
+<PARA>
+To build an eCos library with uSTL support, you can start from the 
+<EMPHASIS>default</EMPHASIS> template and then add the uSTL package 
+CYGPKG_USTL. If you need file streams support of if you would like
+to build all uSTL tests then you need to add the File I/O package 
+CYGPKG_IO_FILEIO.
+</PARA>
+
+<PARA>
+To use uSTL in your eCos application simply include the file 
+<filename>&lt;ustl.h&gt;</filename>. All uSTL classes are in the
+<varname>ustl</varname> namespace.
+</PARA>
+
+<PROGRAMLISTING>
+#include &lt;ustl.h&gt;
+using namespace ustl;
+
+int main (int argc, char* argv[])
+{
+    cout &lt;&lt;"Hello world!\n";
+    return EXIT_SUCCESS;
+}
+</PROGRAMLISTING>
+
+<NOTE>
+<PARA>
+If you use <varname>cout</varname> for printing to the console, 
+then data will get send only if you finish the output with 
+<varname>endl</varname> or '\n' and then call 
+<function>cout.flush()</function> like it is done in the example above.
+</PARA>
+</NOTE>
+
+<PARA>
+The uSTL library is subject of copyright under MIT license. For
+the license text see <filename>LICENSE</filename> file.
+</PARA>
+
+</SECT1>
+</CHAPTER>
+</PART>
+
diff -ruN ecos_web_cvs/ecos/packages/language/cxx/ustl/current/tests/stdtest.h ecos/ecos/packages/language/cxx/ustl/current/tests/stdtest.h
--- ecos_web_cvs/ecos/packages/language/cxx/ustl/current/tests/stdtest.h	2009-08-20 19:00:31.000000000 +0200
+++ ecos/ecos/packages/language/cxx/ustl/current/tests/stdtest.h	2009-08-24 11:03:48.177565800 +0200
@@ -31,22 +31,6 @@
     exit (sig);
 }
 
-/*
-/// Called by the framework on unrecoverable exception handling errors.
-static void Terminate (void)
-{
-    CYG_TEST_FAIL_FINISH("Unrecoverable exception handling error detected.");
-    raise (SIGABRT);
-    exit (EXIT_FAILURE);
-}
-
-/// Called when an exception violates a throw specification.
-static void OnUnexpected (void)
-{
-    CYG_TEST_FAIL("Fatal internal error: unexpected exception caught.\n");
-    Terminate();
-}
-*/
 /// Installs OnSignal as handler for signals.
 static void InstallCleanupHandlers (void)
 {

[-- Attachment #3: ecos_doc.patch --]
[-- Type: application/octet-stream, Size: 897 bytes --]

diff -ruN ecos_web_cvs/ecos/doc/ChangeLog ecos/ecos/doc/ChangeLog
--- ecos_web_cvs/ecos/doc/ChangeLog	2008-12-10 10:55:08.000000000 +0100
+++ ecos/ecos/doc/ChangeLog	2009-08-24 11:11:14.080962000 +0200
@@ -1,3 +1,7 @@
+2009-08-24  Uwe Kindler <uwe_kindler@web.de>
+
+	* sgml/doclist: add uSTL documentation
+	
 2008-12-10  John Dallaway  <jld@ecoscentric.com>
 
 	* sgml/doclist: reference all documentation files.
diff -ruN ecos_web_cvs/ecos/doc/sgml/doclist ecos/ecos/doc/sgml/doclist
--- ecos_web_cvs/ecos/doc/sgml/doclist	2008-12-10 10:55:08.000000000 +0100
+++ ecos/ecos/doc/sgml/doclist	2009-08-24 11:12:31.361375800 +0200
@@ -2,6 +2,7 @@
 hal/common/current/doc/hal.sgml
 hal/common/current/doc/porting.sgml
 language/c/libc/common/current/doc/libc.sgml
+language/cxx/ustl/current/doc/ustl.sgml
 io/common/current/doc/io.sgml
 io/fileio/current/doc/fileio.sgml
 io/pci/current/doc/pci.sgml