[pygccxml-commit] SF.net SVN: pygccxml: [1223] pyplusplus_dev/docs/documentation/how_to

[<rom...@us...>]

Revision: 1223
          http://pygccxml.svn.sourceforge.net/pygccxml/?rev=1223&view=rev
Author:   roman_yakovenko
Date:     2008-01-26 12:26:03 -0800 (Sat, 26 Jan 2008)

Log Message:
-----------
updating docs

Modified Paths:
--------------
    pyplusplus_dev/docs/documentation/how_to/how_to.rest
    pyplusplus_dev/docs/documentation/how_to/www_configuration.py

Added Paths:
-----------
    pyplusplus_dev/docs/documentation/how_to/absolute_relative_paths.rest
    pyplusplus_dev/docs/documentation/how_to/file_name_too_long.rest

Added: pyplusplus_dev/docs/documentation/how_to/absolute_relative_paths.rest
===================================================================
--- pyplusplus_dev/docs/documentation/how_to/absolute_relative_paths.rest	                        (rev 0)
+++ pyplusplus_dev/docs/documentation/how_to/absolute_relative_paths.rest	2008-01-26 20:26:03 UTC (rev 1223)
@@ -0,0 +1,41 @@
+=========================
+Absolute\\relative paths
+=========================
+
+**Absolute\\relative paths**
+
+Consider next fileers, the average number of characters per line is
+less than 2.  Please cs layout:
+::
+
+  boost/
+    date_time/
+      ptime.hpp
+      time_duration.hpp
+      date_time.hpp
+
+``date_time.hpp`` is the main header file, which should be parsed.
+
+`Py++`_ does not handle relative paths, as input, well. It tries, but there are uses
+cases it fails. In these cases it generates empty module - nothing is exposed:
+
+.. code-block:: Python
+
+   mb = module_builder( [ 'date_time/date_time.hpp' ], ... )
+   mb.split_module( ... )
+
+I recommend you to use absolute paths instead of relative ones:
+
+.. code-block:: Python
+
+   import os
+   mb = module_builder( [ os.path.abspath('date_time/date_time.hpp') ], ... )
+   mb.split_module( ... )
+
+and `Py++`_ will expose all declarations found in the ``date_time.hpp`` file and
+other files from the same directory.
+
+.. _`Py++` : ./../../pyplusplus.html
+.. _`Boost.Python`: http://www.boost.org/libs/python/doc/index.html
+.. _`Python`: http://www.python.org
+.. _`GCC-XML`: http://www.gccxml.org

Added: pyplusplus_dev/docs/documentation/how_to/file_name_too_long.rest
===================================================================
--- pyplusplus_dev/docs/documentation/how_to/file_name_too_long.rest	                        (rev 0)
+++ pyplusplus_dev/docs/documentation/how_to/file_name_too_long.rest	2008-01-26 20:26:03 UTC (rev 1223)
@@ -0,0 +1,48 @@
+===============================
+Generated file name is too long
+===============================
+
+**Generated file name is too long**
+
+There are use cases, when `Py++`_ generated file name is too long. In some cases
+the code generation process even fails because of this.
+
+This is just a symptom of the problem. This happens when you expose template
+instantiated classes and you did not specify the class alias. `Py++`_ uses a class
+alias as a basis for the file name.
+
+Let me explain.
+
+.. code-block:: C++
+
+  template < class T>
+  struct holder{ ... };
+
+As you know, a class name in `Python`_ has few `constraints`_ and `Py++`_ is aware
+of them. "holder< int >" is illegal class name, so `Py++`_ will generate another
+one - "holder_less_int_grate\_". Pretty ugly and even long, but at least it is
+legal one.
+
+.. _`constraints` : http://www.python.org/doc/current/ref/identifiers.html
+
+It is pretty simple to change the alias of the class, or any other declaration:
+
+.. code-block:: Python
+
+  from pyplusplus import module_builder
+
+  mb = module_builder_t( ... )
+  holder = mb.class_( 'holder< int >' )
+  holder.alias = 'IntHolder'
+  #next line has same effect as the previous one:
+  holder.rename( 'IntHolder' )
+
+Another solution to the problem, is to use different strategy to split the generated
+code to files. You can read more about splitting files `here`_.
+
+.. _`here` : ./../split_module.html
+
+.. _`Py++` : ./../pyplusplus.html
+.. _`Boost.Python`: http://www.boost.org/libs/python/doc/index.html
+.. _`Python`: http://www.python.org
+.. _`GCC-XML`: http://www.gccxml.org

Modified: pyplusplus_dev/docs/documentation/how_to/how_to.rest
===================================================================
--- pyplusplus_dev/docs/documentation/how_to/how_to.rest	2008-01-26 20:25:11 UTC (rev 1222)
+++ pyplusplus_dev/docs/documentation/how_to/how_to.rest	2008-01-26 20:26:03 UTC (rev 1223)
@@ -16,6 +16,14 @@
 
 .. _`Fatal error C1204:Compiler limit: internal structure overflow` : ./fatal_error_c1204.html
 
+`Absolute\\relative paths`_
+
+.. _`Absolute\\relative paths` : ./absolute_relative_paths.html
+
+`Generated file name is too long`_
+
+.. _`Generated file name is too long` : ./file_name_too_long.html
+
 -------------------------------------------------------
 How to expose function, which has hand-written wrapper?
 -------------------------------------------------------
@@ -72,89 +80,8 @@
 
 That's all.
 
--------------------------------------
-Py++ generated file name is too long!
--------------------------------------
-There are use cases, when `Py++`_ generated file name is too long. In some cases
-the code generation process even fails because of this. What can you do in order
-to eliminate the problem?
 
-First of all the problem arises when you expose template instantiated classes
-and you did not set the class alias.
 
-Let me explain:
-
-.. code-block:: C++
-
-  template < class T>
-  struct holder{ ... };
-
-
-Lets say that you want to export ``holder< int >`` class. Class name in `Python`_
-has few `constraints`_. `Py++`_ is aware of the `constraints`_ and if you didn't
-set an alias to the class, `Py++`_ will do it for you. In this case,
-"holder_less_int_grate\_" is the generated alias. Obviously it is much longer
-and not readable.
-
-.. _`constraints` : http://www.python.org/doc/current/ref/identifiers.html
-
-There are few pretty good reasons for this behavior:
-
-* when you just start to work on `Python`_ bindings concentrate your attention
-  on really important things
-
-* if you forgot to set the class alias your users still can use the class
-  functionality, however the class name will be a little bit ugly.
-
-
-In this case the generate alias for ``holder`` instantiation is relatively short.
-Imagine how long it could be for ``std::map`` instantiation.
-
-`Py++`_ uses class alias for the file name. So if you want to force `Py++`_ to
-generate files with short name, you have to set class alias:
-
-.. code-block:: Python
-
-  from pyplusplus import module_builder
-
-  mb = module_builder_t( ... )
-  holder = mb.class_( 'holder< int >' )
-  holder.alias = 'IntHolder'
-  #next line has same effect as the previous one:
-  holder.rename( 'IntHolder' )
-
-The nice thing about this approach is that now `Python`_ users have "normal"
-class name and you have short file name.
-
--------------------
-Full\relative paths
--------------------
-
-Consider next file layout:
-::
-
-  boost/
-    date_time/
-      ptime.hpp
-      time_duration.hpp
-      date_time.hpp //main header, which include all other header files
-
-Py++ currently does not handle relative paths as input very well, so it is
-recommended that you use ``os.path.abspath()`` to transform the header file to
-be processed into an absolute path:
-
-.. code-block:: Python
-
-   #Next code will expose nothing
-   mb = module_builder( [ 'date_time/date_time.hpp' ], ... )
-   mb.split_module( ... )
-
-   #while this one will work as expected
-   import os
-   mb = module_builder( [ os.path.abspath('date_time/date_time.hpp') ], ... )
-   mb.split_module( ... )
-
-
 .. _`Py++` : ./../pyplusplus.html
 .. _`Boost.Python`: http://www.boost.org/libs/python/doc/index.html
 .. _`Python`: http://www.python.org

Modified: pyplusplus_dev/docs/documentation/how_to/www_configuration.py
===================================================================
--- pyplusplus_dev/docs/documentation/how_to/www_configuration.py	2008-01-26 20:25:11 UTC (rev 1222)
+++ pyplusplus_dev/docs/documentation/how_to/www_configuration.py	2008-01-26 20:26:03 UTC (rev 1223)
@@ -6,6 +6,8 @@
           , 'templates' : 'deal with templates'
           , 'best_practices' : 'best practices'
           , 'exception_translation' : 'exception translation'
-          , 'fatal_error_c1204' : 'fatal error C1204: compiler limit: internal structure overflow'
+          , 'fatal_error_c1204' : 'fatal error: C1204'
+          , 'absolute_relative_paths' : 'absolute\\relative paths'
+          , 'file_name_too_long' : 'file name is too long'
 }
 


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.