pygccxml-development

[pygccxml-development] pyplusplus status

[Roman Y. <rom...@gm...>]

Hi. I just want to describe what have been done and what I think should be done
before next version will be ready to be released.

Done:
1. pyplusplus now preserves the order of generated code. I mean if you
run pyplusplus
    twice, than second run will not change any file. If you see a
different behaviour, please
    report a bug.

2. Usability of pyplusplus has been improved. Now by default it will
print only very important
    messages:
    1. gccxml command line ( printed text will start with "INFO" word )
    2. declarations, that user asked to export, but for some reason,
pyplusplus can
        not export them ( ( printed text will start with "WARNING" word )
    3. a list of updated(created) files ( printed text will start with
"INFO" word )

    It is possible to configure pyplusplus to print much more information:

    import logger
    from pyplusplus import module_builder
    module_builder.set_logger_level( logging.DEBUG )

3. pyplusplus is able to generate code for indexing suite v2.
    You need explicitly to enable it:
    mb = module_builder.module_builder_t( ..., indexing_suite_version=2 )

    The documentation for this feature is in progress

What still should be done?

1. Georgiy Dernovoy contributed code, that extracts doxygen
documentation from source
    files. I will add code to pyplusplus that will generate documentation.

2. I should find solution for long standing problem: the number of
include directives
    in generated source files.

3. I am going to work a little on file_writers package. The main
missing future here is
   to add user code to generated source file.

4. Documentation.

For items (2) and (3), I'd like to know your opinion:
    1. What code pyplusplus should generate?
    2. How do you prefer to configure the feature? ( user interface )

I don't want to set release day,  but from now I will try to keep
source code in
"release ready" mode. If you can try source code from "Subversion" and
report bugs
it will be grate.

-- 
Roman Yakovenko
C++ Python language binding
http://www.language-binding.net/

Re: [pygccxml-development] pyplusplus status

[Allen B. <al...@vr...>]

Roman:

As promised, here is a short list of the things I have found while using 
pyplusplus recently.

- 90% of users should never have to delve beyond the "easy API" (never 
need to know about creators). The current API is close to this, but 
there are still some times when IMHO users have to suddenly delve very 
deep into the internal code.

- template support: I would like to see an API that allows users to more 
easily wrap templates.  I have had to manually create some code that 
does this but I am sure something better could be done.  You can see 
what I have done at: 
https://realityforge.vrsource.org/viewvc/pyopensg/trunk/src/gen_bindings.py?view=markup  
Look for the TemplateBuilder helper class.

- Merging header files.  I have found it very helpful to specify a 
single temporary header file to the module builder that just includes 
all of the headers for the API I want to wrap.  This can result in 
significant speed increases when calling gccxml because the header files 
for a library often include much code in common.  It would be nice if 
the module builder had a flag in it's constructor (like: 
combine_headers) that would make pypp do this automatically.

- finalize():  I would really, really, really appreciate a true 
finalize() method being defined for all decls.  There are a lot of times 
where I know I want the class to be final so I don't want a wrapper or 
anything else extra.

- mdecl returns: See the thread "mdecl and methods that return values" 
from 5/30/2006.  This is a capability that I still very much need.
 
- Documentation
   - Summary: Make a simple, complete, tutorial document like the one 
for Pyste.  Just show how to do the things in the "easy API" that 90% of 
people want to do (see above)
   - simple, complete documentation of user API and what can be done
   - documentation for all paramemters of builder methods.
      - what does compilation_mode, start_with_declarations, etc do in 
__init__
      - Same with build_code_creator
      - what do the params do and how could/should they be used
   - How do I do this...  documentation of standard things a user wants 
to do
      - Pyste documentation is very good about this.
- Wrap method: Add API for just wrapping an existing method with a new 
defined method.  (right now this can be cone but you have to exclude the 
current method and then call add_code with a 'def'. It is just too 
complex for a new user and makes the wrapper gen script look complicated.)

- Add an API to ask if has decl and/or number of found decls

- Add ability to add user code to namespace or global *without* having 
to use code creators directly

- Cache parsing and preparing query optimizer.  If the input has not 
changed (the headers are the same) why do I have to wait for all the 
processing of the declarations and query optimization each time.  Can't 
we cache all of that?

- This is a small nitpick, but unless you are making a lot of money from 
Google AdSense, could you remove the Google ads in the table of contents 
on the website.  They are just annoying and make the documentation 
harder to read.

- Better job of not including platform specific files.  For example I 
have a binding right now that is adding 
/usr/include/c++/4.0.2/ext/mt_allocator.h as an include in all the 
files.  Needless to say this doesn't compile on windows. :(

- Performance improvements:  improving performance is always good.  The 
time waiting for all the code_creators to be created is especially long.


Comments?

-Allen

Roman Yakovenko wrote:

>Hi. I just want to describe what have been done and what I think should be done
>before next version will be ready to be released.
>
>Done:
>1. pyplusplus now preserves the order of generated code. I mean if you
>run pyplusplus
>    twice, than second run will not change any file. If you see a
>different behaviour, please
>    report a bug.
>
>2. Usability of pyplusplus has been improved. Now by default it will
>print only very important
>    messages:
>    1. gccxml command line ( printed text will start with "INFO" word )
>    2. declarations, that user asked to export, but for some reason,
>pyplusplus can
>        not export them ( ( printed text will start with "WARNING" word )
>    3. a list of updated(created) files ( printed text will start with
>"INFO" word )
>
>    It is possible to configure pyplusplus to print much more information:
>
>    import logger
>    from pyplusplus import module_builder
>    module_builder.set_logger_level( logging.DEBUG )
>
>3. pyplusplus is able to generate code for indexing suite v2.
>    You need explicitly to enable it:
>    mb = module_builder.module_builder_t( ..., indexing_suite_version=2 )
>
>    The documentation for this feature is in progress
>
>What still should be done?
>
>1. Georgiy Dernovoy contributed code, that extracts doxygen
>documentation from source
>    files. I will add code to pyplusplus that will generate documentation.
>
>2. I should find solution for long standing problem: the number of
>include directives
>    in generated source files.
>
>3. I am going to work a little on file_writers package. The main
>missing future here is
>   to add user code to generated source file.
>
>4. Documentation.
>
>For items (2) and (3), I'd like to know your opinion:
>    1. What code pyplusplus should generate?
>    2. How do you prefer to configure the feature? ( user interface )
>
>I don't want to set release day,  but from now I will try to keep
>source code in
>"release ready" mode. If you can try source code from "Subversion" and
>report bugs
>it will be grate.
>
>  
>

Re: [pygccxml-development] pyplusplus status

[Roman Y. <rom...@gm...>]

On 7/12/06, Allen Bierbaum <al...@vr...> wrote:
> - 90% of users should never have to delve beyond the "easy API" (never
> need to know about creators). The current API is close to this, but
> there are still some times when IMHO users have to suddenly delve very
> deep into the internal code.

I would like to see use case, where you have to do this.

> - template support: I would like to see an API that allows users to more
> easily wrap templates.  I have had to manually create some code that
> does this but I am sure something better could be done.  You can see
> what I have done at:
> https://realityforge.vrsource.org/viewvc/pyopensg/trunk/src/gen_bindings.py?view=markup
> Look for the TemplateBuilder helper class.

My main objection to this is that users will not use it. Think about
it. You can create/generate/generate on fly header file/string and to
include it to the list of header files
passed to module_builder_t.__init__. You don't have to learn  new API.

There is "contrib" package, I think your class could be added to it.
If you agree,
you can create new directory - "templates" and to add the functionality to it.
( You have commit permissions. )

> - Merging header files.  I have found it very helpful to specify a
> single temporary header file to the module builder that just includes
> all of the headers for the API I want to wrap.  This can result in
> significant speed increases when calling gccxml because the header files
> for a library often include much code in common.  It would be nice if
> the module builder had a flag in it's constructor (like:
> combine_headers) that would make pypp do this automatically.

This is already implemented:
http://www.language-binding.net/pygccxml/apidocs/pygccxml.parser.project_reader.project_reader_t-class.html#read_files

mb = module_builder_t( ...
     , compilation_mode=pygccxml.parser.COMPILATION_MODE.ALL_AT_ONCE
     , ... )

> - finalize():  I would really, really, really appreciate a true
> finalize() method being defined for all decls.  There are a lot of times
> where I know I want the class to be final so I don't want a wrapper or
> anything else extra.

I will try to find time to work on this feature for next release, not this one.

> - mdecl returns: See the thread "mdecl and methods that return values"
> from 5/30/2006.  This is a capability that I still very much need.

Please, read my last mail in that thread. If you have good definition
I will implement it.

> - Documentation
>    - Summary: Make a simple, complete, tutorial document like the one
> for Pyste.  Just show how to do the things in the "easy API" that 90% of
> people want to do (see above)

>    - simple, complete documentation of user API and what can be done
>    - documentation for all paramemters of builder methods.
>       - what does compilation_mode, start_with_declarations, etc do in
> __init__
>       - Same with build_code_creator
>       - what do the params do and how could/should they be used
>    - How do I do this...  documentation of standard things a user wants
> to do

HowTo is a good idea.

>       - Pyste documentation is very good about this.

:-). I am not good in writing documentation. It takes me a lot of time to do it.
I remember, in the beginning, we made a deal: I write code and you
write documentation, right :-) ? So, if you want to contribute, we may
spend some time on IRC channel,
you will ask questions, I will answer them. And after this you will
convert our conversation
to some form of documentation. Otherwise, I will have to completely
freeze development for
few month and the only thing I will do is writing documentation.

> - Wrap method: Add API for just wrapping an existing method with a new
> defined method.  (right now this can be cone but you have to exclude the
> current method and then call add_code with a 'def'. It is just too
> complex for a new user and makes the wrapper gen script look complicated.)

http://www.language-binding.net/pyplusplus/peps/call_wrapper_policies.html

When I implement this PEP, it will be pretty easy to do what you want.
Until then I don't want to introduce something, that I will not support later.

> - Add an API to ask if has decl and/or number of found decls

decls = mv.decls( ..., allow_empty=True )
len( decls )

> - Add ability to add user code to namespace or global *without* having
> to use code creators directly

I want to solve this problem, to this release. Can you write what you
want/need/expect
here? In other words I need use cases and how you see they should be solved.

> - Cache parsing and preparing query optimizer.  If the input has not
> changed (the headers are the same) why do I have to wait for all the
> processing of the declarations and query optimization each time.  Can't
> we cache all of that?

Yes, but you can guess what the priority of this. Also I think that
solution for this
problem will be completely in the user code.

> - This is a small nitpick, but unless you are making a lot of money from
> Google AdSense, could you remove the Google ads in the table of contents
> on the website.  They are just annoying and make the documentation
> harder to read.

I am not, the AdSence is there to return the money I pay for running web site.
I hate the idea to ask for donations. User experience is importer.
I will do something about it.

> - Better job of not including platform specific files.  For example I
> have a binding right now that is adding
> /usr/include/c++/4.0.2/ext/mt_allocator.h as an include in all the
> files.  Needless to say this doesn't compile on windows. :(

This is another issue I have to solve. Your thoughts are welcome.

> - Performance improvements:  improving performance is always good.  The
> time waiting for all the code_creators to be created is especially long.

Do you mind to run your code under profiler? Thus we will have clear
picture of where
is a bottleneck. I don't have big use case. All my scripts run in a
minute or two and most of
the time is spent in xml parsing.

-- 
Roman Yakovenko
C++ Python language binding
http://www.language-binding.net/

Re: [pygccxml-development] pyplusplus status

[Allen B. <al...@vr...>]

Roman Yakovenko wrote:

> On 7/12/06, Allen Bierbaum <al...@vr...> wrote:
>
>> - 90% of users should never have to delve beyond the "easy API" (never
>> need to know about creators). The current API is close to this, but
>> there are still some times when IMHO users have to suddenly delve very
>> deep into the internal code.
>
>
> I would like to see use case, where you have to do this.

I will try to post the use cases as I run across them.  Unfortunately 
most of my binding generation scripts would be classified more as "power 
user" then newbie so I don't use the "easy API".

What this comment really comes down to is that I don't think the current 
API fullfills the goals set out at: 
https://realityforge.vrsource.org/view/PyOpenSG/PyppApiDiscussion

The big ones I find missing are:

    * Do not require the user to know anything outside of the high-level
      API to accomplish most tasks.
    * Provide access to all the power of pypluplus and pygccxml *if* the
      user wants it

Please don't take offense to this Roman, but you understand the APIs of 
pygccxml and pyplusplus so well and in so much detail that I think your 
take on what is an "easy API" may be much more in depth then what I 
would consider an "easy API".  For example, take a look at the Pyste 
tutorial again.  Pyste's API is very domain specific and very simple.  
This makes it easy to approach by new users.  The main problem (and what 
pyplusplus solves extremely well) is that Pyste is very limited once you 
go beyond that simple API.  But having the simple API is still important 
for allowing new users to pick it up and use the tool.

Am I the only one that feels this way when using the API?

>
>> - template support: I would like to see an API that allows users to more
>> easily wrap templates.  I have had to manually create some code that
>> does this but I am sure something better could be done.  You can see
>> what I have done at:
>> https://realityforge.vrsource.org/viewvc/pyopensg/trunk/src/gen_bindings.py?view=markup 
>>
>> Look for the TemplateBuilder helper class.
>
>
> My main objection to this is that users will not use it. Think about
> it. You can create/generate/generate on fly header file/string and to
> include it to the list of header files
> passed to module_builder_t.__init__. You don't have to learn  new API.

And my main reason for saying this is needed is that doing it manually 
is too hard for most users.  It is *much* easier to do this with Pyste.  
You just say Template("class") and then instantiate templates.  Very 
straight forward in Pyste's domain specific lanaguage.  Unfortunately I 
think the domain specific language of pyplusplus is still python and 
this is not good IMHO.

>
> There is "contrib" package, I think your class could be added to it.
> If you agree,
> you can create new directory - "templates" and to add the 
> functionality to it.
> ( You have commit permissions. )
>
>> - Merging header files.  I have found it very helpful to specify a
>> single temporary header file to the module builder that just includes
>> all of the headers for the API I want to wrap.  This can result in
>> significant speed increases when calling gccxml because the header files
>> for a library often include much code in common.  It would be nice if
>> the module builder had a flag in it's constructor (like:
>> combine_headers) that would make pypp do this automatically.
>
>
> This is already implemented:
> http://www.language-binding.net/pygccxml/apidocs/pygccxml.parser.project_reader.project_reader_t-class.html#read_files 
>
>
> mb = module_builder_t( ...
>     , compilation_mode=pygccxml.parser.COMPILATION_MODE.ALL_AT_ONCE
>     , ... )

Does this behave *exactly* the same way.  Does it only create one entry 
in the cache?

>
>> - finalize():  I would really, really, really appreciate a true
>> finalize() method being defined for all decls.  There are a lot of times
>> where I know I want the class to be final so I don't want a wrapper or
>> anything else extra.
>
>
> I will try to find time to work on this feature for next release, not 
> this one.
>
>> - mdecl returns: See the thread "mdecl and methods that return values"
>> from 5/30/2006.  This is a capability that I still very much need.
>
>
> Please, read my last mail in that thread. If you have good definition
> I will implement it.

I would recommend just treating it like you would a .decls() call.  ie. 
if the users looks up declarations of differing types and then calls a 
method on those decls that only makes sense for one type, then python 
will display an error about the type problems.

>
>> - Documentation
>>    - Summary: Make a simple, complete, tutorial document like the one
>> for Pyste.  Just show how to do the things in the "easy API" that 90% of
>> people want to do (see above)
>
>
>>    - simple, complete documentation of user API and what can be done
>>    - documentation for all paramemters of builder methods.
>>       - what does compilation_mode, start_with_declarations, etc do in
>> __init__
>>       - Same with build_code_creator
>>       - what do the params do and how could/should they be used
>>    - How do I do this...  documentation of standard things a user wants
>> to do
>
>
> HowTo is a good idea.
>
>>       - Pyste documentation is very good about this.
>
>
> :-). I am not good in writing documentation. It takes me a lot of time 
> to do it.
> I remember, in the beginning, we made a deal: I write code and you
> write documentation, right :-) ? So, if you want to contribute, we may
> spend some time on IRC channel,
> you will ask questions, I will answer them. And after this you will
> convert our conversation
> to some form of documentation. Otherwise, I will have to completely
> freeze development for
> few month and the only thing I will do is writing documentation.

Would it be useful to make the tutorial and howto a "live" document so 
everyone can contribute, add questions, make changes?  If so, what about 
using a wiki so everyone can contribute and fix up the descrptions.

>
>> - Wrap method: Add API for just wrapping an existing method with a new
>> defined method.  (right now this can be cone but you have to exclude the
>> current method and then call add_code with a 'def'. It is just too
>> complex for a new user and makes the wrapper gen script look 
>> complicated.)
>
>
> http://www.language-binding.net/pyplusplus/peps/call_wrapper_policies.html 
>
>
> When I implement this PEP, it will be pretty easy to do what you want.
> Until then I don't want to introduce something, that I will not 
> support later.

I don't see how this pep fixes the problem, but then again I don't fully 
understand what the pep will do.  I will just trust you that this will 
help out.

>
>> - Add an API to ask if has decl and/or number of found decls
>
>
> decls = mv.decls( ..., allow_empty=True )
> len( decls )

How about something shorter that is a little easier to use in 
conditionals.  Maybe something like count(). so you could do something like:

def processClass(cls):
   if cls.count("method"):
      # do something

I have run into a few cases where something like this could be pretty 
useful and keep the script more understandable.

>
>> - Add ability to add user code to namespace or global *without* having
>> to use code creators directly
>
>
> I want to solve this problem, to this release. Can you write what you
> want/need/expect
> here? In other words I need use cases and how you see they should be 
> solved.


I will have to think about this and get back to you.

>
>> - Cache parsing and preparing query optimizer.  If the input has not
>> changed (the headers are the same) why do I have to wait for all the
>> processing of the declarations and query optimization each time.  Can't
>> we cache all of that?
>
>
> Yes, but you can guess what the priority of this. Also I think that
> solution for this
> problem will be completely in the user code.
>
>> - This is a small nitpick, but unless you are making a lot of money from
>> Google AdSense, could you remove the Google ads in the table of contents
>> on the website.  They are just annoying and make the documentation
>> harder to read.
>
>
> I am not, the AdSence is there to return the money I pay for running 
> web site.
> I hate the idea to ask for donations. User experience is importer.
> I will do something about it.

That would be very helpful. I do not care about the ads on the left bar 
or even if you added ones at the other sides of the pages.  But putting 
ads in the middle of the table of contents or text body is a little 
annoying.

>
>> - Better job of not including platform specific files.  For example I
>> have a binding right now that is adding
>> /usr/include/c++/4.0.2/ext/mt_allocator.h as an include in all the
>> files.  Needless to say this doesn't compile on windows. :(
>
>
> This is another issue I have to solve. Your thoughts are welcome.

I don't really have any ideas because I don't know what is causing it.  
For now, I have just worked around it by over-riding the included 
headers using replace_included_headers() to set the included header(s) 
to be the same list that was originally passed to the module builder.  
It seems to me that this list should always work and will always include 
any headers that are actually needed by the wrapped code.

>
>> - Performance improvements:  improving performance is always good.  The
>> time waiting for all the code_creators to be created is especially long.
>
>
> Do you mind to run your code under profiler? Thus we will have clear
> picture of where
> is a bottleneck. I don't have big use case. All my scripts run in a
> minute or two and most of
> the time is spent in xml parsing.
>
Yes, I can provide you with a profile run once I get back to working on 
my big project.

-Allen

Re: [pygccxml-development] pyplusplus status

[Roman Y. <rom...@gm...>]

On 7/18/06, Allen Bierbaum <al...@vr...> wrote:
> What this comment really comes down to is that I don't think the current
> API fullfills the goals set out at:
> https://realityforge.vrsource.org/view/PyOpenSG/PyppApiDiscussion
>
> The big ones I find missing are:
>
>     * Do not require the user to know anything outside of the high-level
>       API to accomplish most tasks.

This will never happen :-(. py++ knows to export only limited subset of C++.

> Please don't take offense to this Roman, but you understand the APIs of
> pygccxml and pyplusplus so well and in so much detail that I think your
> take on what is an "easy API" may be much more in depth then what I
> would consider an "easy API".
> ...
> But having the simple API is still important
> for allowing new users to pick it up and use the tool.

With the power comes complexity. Also I would like to see your
definition to "simple"
and "power" API. My definition is next:

simple - API defined by decl_wrappers package and module_builder
package. Basically,
this is get\set properties + "query" api.

power - modifying directly code creators tree. This is really the
"dark" area of the project,
but I have an idea how to simplify it and of course I will write a
documentation that will
explain it.

> Am I the only one that feels this way when using the API?

I definitely would like to get the answer to this question with
suggestions from other users.

> You just say Template("class") and then instantiate templates.  Very
> straight forward in Pyste's domain specific lanaguage.

Please contribute your code with small example and documentation( and license )
to py++ :-). I already added new directory for this in "contrib" one.

> > mb = module_builder_t( ...
> >     , compilation_mode=pygccxml.parser.COMPILATION_MODE.ALL_AT_ONCE
> >     , ... )
>
> Does this behave *exactly* the same way.  Does it only create one entry
> in the cache?

Almost. pygccxml will create temporal file. I never checked how it
will behave with a
cache. Can you check this, and if the behaviour is not as you expect,
I will try to fix it.

> I would recommend just treating it like you would a .decls() call.  ie.
> if the users looks up declarations of differing types and then calls a
> method on those decls that only makes sense for one type, then python
> will display an error about the type problems.

I prefer to continue to discuss this problem within the original thread.

> Would it be useful to make the tutorial and howto a "live" document so
> everyone can contribute, add questions, make changes?  If so, what about
> using a wiki so everyone can contribute and fix up the descrptions.

I think, this will be useful, but not now. There is only few peoples
who contribute
to the project.

I started to work on FAQs:
http://svn.sourceforge.net/viewcvs.cgi/pygccxml/pyplusplus_dev/docs/faqs/faqs.rest?view=markup

If you have something specifiec in mind, or want to add documentation
here and there,
please do it.

> I don't see how this pep fixes the problem, but then again I don't fully
> understand what the pep will do.  I will just trust you that this will
> help out.

This is pretty simple: this paper deals with method transformations.
For example:
     void get_size( int& h, int&w )
You will be able to define the transformation of get_size to
    boost::python::tuple get_size()

The function wrapper, you are talking about, it is just an "user
defined" transformation.

> def processClass(cls):
>    if cls.count("method"):
>       # do something
>
> I have run into a few cases where something like this could be pretty
> useful and keep the script more understandable.

I will see what I can do.

-- 
Roman Yakovenko
C++ Python language binding
http://www.language-binding.net/

Re: [pygccxml-development] pyplusplus status

[Allen B. <al...@vr...>]

Roman Yakovenko wrote:

> On 7/18/06, Allen Bierbaum <al...@vr...> wrote:
>
>> What this comment really comes down to is that I don't think the current
>> API fullfills the goals set out at:
>> https://realityforge.vrsource.org/view/PyOpenSG/PyppApiDiscussion
>>
>> The big ones I find missing are:
>>
>>     * Do not require the user to know anything outside of the high-level
>>       API to accomplish most tasks.
>
>
> This will never happen :-(. py++ knows to export only limited subset 
> of C++.

I think the keywords here are "most tasks".   I think we are already 
close to being able to do most tasks with the higher-level API. I just 
don't think the high-level API allows people to do everything as easily 
as they could with Pyste or the experimental API that Matthias is using.

>
>> Please don't take offense to this Roman, but you understand the APIs of
>> pygccxml and pyplusplus so well and in so much detail that I think your
>> take on what is an "easy API" may be much more in depth then what I
>> would consider an "easy API".
>> ...
>> But having the simple API is still important
>> for allowing new users to pick it up and use the tool.
>
>
> With the power comes complexity. Also I would like to see your
> definition to "simple"
> and "power" API. My definition is next:
>
> simple - API defined by decl_wrappers package and module_builder
> package. Basically,
> this is get\set properties + "query" api.

I would also say the simple API would require limited to no use of 
pygccxml directly.  This may be one of the areas that gets me the most 
because I don't always know where to look in pygccxml to do what I want.

If the query api was more completely documented in a tutorial form (so 
newbies don't have to delve deeply into the reference docs), then I 
think we would be on much better footing here.

>
> power - modifying directly code creators tree. This is really the
> "dark" area of the project,
> but I have an idea how to simplify it and of course I will write a
> documentation that will
> explain it.

I would also add using anything in pygccxml that requires understanding 
of how pygccxml is implemented and using any of pygccxml that is not 
documented in a tutorial.  Basically, if the user has to read the code 
to understand or find what they need to do, then that is not part of the 
simple interface.

>
>> Am I the only one that feels this way when using the API?
>
>
> I definitely would like to get the answer to this question with
> suggestions from other users.
>
>> You just say Template("class") and then instantiate templates.  Very
>> straight forward in Pyste's domain specific lanaguage.
>
>
> Please contribute your code with small example and documentation( and 
> license )
> to py++ :-). I already added new directory for this in "contrib" one.

I think my code as it stands is too complex.  I will try to revisit it 
once I get back to using it (probably late this week or early next week).

>
>> > mb = module_builder_t( ...
>> >     , compilation_mode=pygccxml.parser.COMPILATION_MODE.ALL_AT_ONCE
>> >     , ... )
>>
>> Does this behave *exactly* the same way.  Does it only create one entry
>> in the cache?
>
>
> Almost. pygccxml will create temporal file. I never checked how it
> will behave with a
> cache. Can you check this, and if the behaviour is not as you expect,
> I will try to fix it.
>
>> I would recommend just treating it like you would a .decls() call.  ie.
>> if the users looks up declarations of differing types and then calls a
>> method on those decls that only makes sense for one type, then python
>> will display an error about the type problems.
>
>
> I prefer to continue to discuss this problem within the original thread.

Ok.

>
>> Would it be useful to make the tutorial and howto a "live" document so
>> everyone can contribute, add questions, make changes?  If so, what about
>> using a wiki so everyone can contribute and fix up the descrptions.
>
>
> I think, this will be useful, but not now. There is only few peoples
> who contribute
> to the project.
>
> I started to work on FAQs:
> http://svn.sourceforge.net/viewcvs.cgi/pygccxml/pyplusplus_dev/docs/faqs/faqs.rest?view=markup 
>
>
> If you have something specifiec in mind, or want to add documentation
> here and there,
> please do it.
>
>> I don't see how this pep fixes the problem, but then again I don't fully
>> understand what the pep will do.  I will just trust you that this will
>> help out.
>
>
> This is pretty simple: this paper deals with method transformations.
> For example:
>     void get_size( int& h, int&w )
> You will be able to define the transformation of get_size to
>    boost::python::tuple get_size()
>
> The function wrapper, you are talking about, it is just an "user
> defined" transformation.

What I want is not only transformations, but defining completely new 
functions to replace existing functions.

>
>> def processClass(cls):
>>    if cls.count("method"):
>>       # do something
>>
>> I have run into a few cases where something like this could be pretty
>> useful and keep the script more understandable.
>
>
> I will see what I can do.
>
Thanks,
Allen

Re: [pygccxml-development] pyplusplus status

[Allen B. <al...@vr...>]

Roman Yakovenko wrote:

> On 7/18/06, Allen Bierbaum <al...@vr...> wrote:
>
>> I think the keywords here are "most tasks".   I think we are already
>> close to being able to do most tasks with the higher-level API. I just
>> don't think the high-level API allows people to do everything as easily
>> as they could with Pyste or the experimental API that Matthias is using.
>
>
> I will study Matthias API and write here my thoughts.

Don't forget to review the Pyste API.  I hate to say it, but it is a 
reality of software that anything that is easy to do in the original 
tool (Pyste) but hard to do in the new tool (pyplusplus) will hurt 
adoption of the the new software package.  Pyplusplus not only has to be 
able to do more it has to be able to still do everything Pyste does and 
do it just as easily.

>
>> I would also say the simple API would require limited to no use of
>> pygccxml directly.  This may be one of the areas that gets me the most
>> because I don't always know where to look in pygccxml to do what I want.
>
>
> I thought that pygccxml is pretty simple project. In 99% of use case you
> have to understand only declarations package. I will try to improve
> documentation
> for the package. Please say what information you are missing?

You are probably right that the big thing I am missing is complete 
documentation.  For example a table with all the type traits, how to 
call them, and what they return. Similarly with the api for 
lookup/search, documentation of all the methods, all the params, and all 
the matchers.  (once again, just a table that lists everything in one 
place with a short description would be helpful).  I know from 
experience what source files to look in, but new users don't know this.  
This could be helped a lot by just having a complete tutorial with pages 
that have these tables.

>
>> If the query api was more completely documented in a tutorial form (so
>> newbies don't have to delve deeply into the reference docs), then I
>> think we would be on much better footing here.
>
>
> What is wrong with this
> http://language-binding.net/pygccxml/query_interface.html
> tutorial. If you understand how to use "member_function(s)" , you
> understand all others.
>
Yes, but you have to know what all the "others" are and that they take 
the same parameters.  Once again, I am not saying we are too far from 
this, but there is still a disconnect for a new user.

I keep using the term "tutorial", but maybe the more appropriate term 
would be "user's guide".  What I think is needed is something similar to 
the Pyste documenation and the Boost.Python Tutorial.  Something that 
shows the user-level API that can be used to accomplish most tasks.  It 
should have reference to where to go for lower-level detail, but it 
should stand on it's own as a useful resource.

>> >
>> > power - modifying directly code creators tree. This is really the
>> > "dark" area of the project,
>> > but I have an idea how to simplify it and of course I will write a
>> > documentation that will
>> > explain it.
>>
>> I would also add using anything in pygccxml that requires understanding
>> of how pygccxml is implemented and using any of pygccxml that is not
>> documented in a tutorial.  Basically, if the user has to read the code
>> to understand or find what they need to do, then that is not part of the
>> simple interface.
>
>
> I don't agree with you. I think, the project does not have enough 
> documentation.
> If I will describe every public function in terms of: precondition,
> post condition,
> arguments and return value, then you will almost never will have to
> look to source code.
>
But even then you are talking about reference documentation.  There 
needs to be some starting point that lets the user know the capability 
exists.  Then this can be used as a launching point to looking for the 
detailed documentation. 

I could be totally wrong here though.  I would love for you to prove me 
wrong.  I don't care how we get there or who's ideas work, just as long 
as new users can pick up, understand, and use pyplusplus easily.

-Allen

Re: [pygccxml-development] pyplusplus status

[Roman Y. <rom...@gm...>]

On 7/19/06, Allen Bierbaum <al...@vr...> wrote:
> Don't forget to review the Pyste API.  I hate to say it, but it is a
> reality of software that anything that is easy to do in the original
> tool (Pyste) but hard to do in the new tool (pyplusplus) will hurt
> adoption of the the new software package.  Pyplusplus not only has to be
> able to do more it has to be able to still do everything Pyste does and
> do it just as easily.

I did it. py++ is missing next functionality:

1. py++ is missing template functionality:
    http://boost.org/libs/python/pyste/doc/templates.html

    If you or Matthias will contribute the code, py++ will also have
this functionality.

2. Wrappers
    http://boost.org/libs/python/pyste/doc/wrappers.html

    py++ provides this functionality, but user have to understand code creators.
    This will be fixed in next 2 weeks. With one line of code you will
be able to
    add code to:
    1. declaration section of the module ( before BOOST_PYTHON_MODULE )
    2. registration section ( within BOOST_PYTHON_MODULE )
    3. declaration section within source file, that exposes some class

    If I will get positive comments about new functionality, I will
extend it to free
    functions.


> You are probably right that the big thing I am missing is complete
> documentation.  For example a table with all the type traits, how to
> call them, and what they return.

What is wrong with this documentation
http://language-binding.net/pygccxml/apidocs/pygccxml.declarations.type_traits-module.html
?

> Similarly with the api for
> lookup/search, documentation of all the methods, all the params,

It is a huge effort for me really. Now, when you understand how this
lookup/search/query api works, can you add documentaton to source
file?
Thanks.

> and all the matchers.

What is wrong with this documentation:
http://language-binding.net/pygccxml/apidocs/index.html
?

More over in most cases you don't have to use matchers at all. Query API
will does it for you.

>(once again, just a table that lists everything in one
> place with a short description would be helpful).  I know from
> experience what source files to look in, but new users don't know this.

I agree with you.

> This could be helped a lot by just having a complete tutorial with pages
> that have these tables.

I am going to build documentation, similar to Pyste. It will describe
functionality
of py++ and how I expect it should be used.



> >
> >> If the query api was more completely documented in a tutorial form (so
> >> newbies don't have to delve deeply into the reference docs), then I
> >> think we would be on much better footing here.
> >
> >
> > What is wrong with this
> > http://language-binding.net/pygccxml/query_interface.html
> > tutorial. If you understand how to use "member_function(s)" , you
> > understand all others.
> >
> Yes, but you have to know what all the "others" are and that they take
> the same parameters.  Once again, I am not saying we are too far from
> this, but there is still a disconnect for a new user.

I will add "others" to the documentation. Thanks for the tip.

> > I don't agree with you. I think, the project does not have enough
> > documentation.
> > If I will describe every public function in terms of: precondition,
> > post condition,
> > arguments and return value, then you will almost never will have to
> > look to source code.
> >
> But even then you are talking about reference documentation.  There
> needs to be some starting point that lets the user know the capability
> exists.  Then this can be used as a launching point to looking for the
> detailed documentation.

What is wrong with this tutorial
http://www.language-binding.net/pyplusplus/tutorials/module_builder/module_builder.html
?

> I could be totally wrong here though.  I would love for you to prove me
> wrong.  I don't care how we get there or who's ideas work, just as long
> as new users can pick up, understand, and use pyplusplus easily.

No, you are right. I need to concentrate my attention on documentation.


-- 
Roman Yakovenko
C++ Python language binding
http://www.language-binding.net/

Re: [pygccxml-development] pyplusplus status

[Roman Y. <rom...@gm...>]

Good evening. I took a look on pypp_api and how it is used in the script.

1. pypp_api has feature, that it will take some time to implement it in py++
    - argument policies.

2. ModuleBuilder has next functionality:
    1. add code to the beginning/end of the body
    2. add code to the beginning/end of the declaration section.

    As I already said, this functionality will be implemented pretty soon.

3. Templates, exception translation registration, cdef, staticmethod and similar
    functionality.

    I think, that this functionality does not belong to module builder class.
    In my opinion all functionality like this should be implemented by free
    functions.

Did I miss something?

P.S.

 By the way exception translation registration functionality contains a bug
  - if exception class is template instantiated it will generate code
that will not
  compile.

-- 
Roman Yakovenko
C++ Python language binding
http://www.language-binding.net/

Re: [pygccxml-development] pyplusplus status

[Allen B. <al...@vr...>]

Roman Yakovenko wrote:

>On 7/19/06, Allen Bierbaum <al...@vr...> wrote:
>  
>
>>Don't forget to review the Pyste API.  I hate to say it, but it is a
>>reality of software that anything that is easy to do in the original
>>tool (Pyste) but hard to do in the new tool (pyplusplus) will hurt
>>adoption of the the new software package.  Pyplusplus not only has to be
>>able to do more it has to be able to still do everything Pyste does and
>>do it just as easily.
>>    
>>
>
>I did it. py++ is missing next functionality:
>
>1. py++ is missing template functionality:
>    http://boost.org/libs/python/pyste/doc/templates.html
>
>    If you or Matthias will contribute the code, py++ will also have
>this functionality.
>  
>
The way I handle template now and in the experimental API will require 
some changes to how module builder is created.  Specifically, module 
builder will not be able to parse immediately as a side-effect of 
__init__.  It will need to wait until later like the experimental API 
does to give the user time to call template related methods on the 
module builder.  Then when the module builder finally does start parsing 
it will have the information it needs to create the template code 
dynamically.

>2. Wrappers
>    http://boost.org/libs/python/pyste/doc/wrappers.html
>
>    py++ provides this functionality, but user have to understand code creators.
>    This will be fixed in next 2 weeks. With one line of code you will
>be able to
>    add code to:
>    1. declaration section of the module ( before BOOST_PYTHON_MODULE )
>    2. registration section ( within BOOST_PYTHON_MODULE )
>    3. declaration section within source file, that exposes some class
>
>    If I will get positive comments about new functionality, I will
>extend it to free
>    functions.
>
>
>  
>
>>You are probably right that the big thing I am missing is complete
>>documentation.  For example a table with all the type traits, how to
>>call them, and what they return.
>>    
>>
>
>What is wrong with this documentation
>http://language-binding.net/pygccxml/apidocs/pygccxml.declarations.type_traits-module.html
>?
>
>  
>
>>Similarly with the api for
>>lookup/search, documentation of all the methods, all the params,
>>    
>>
>
>It is a huge effort for me really. Now, when you understand how this
>lookup/search/query api works, can you add documentaton to source
>file?
>  
>
I can help when I see places that need documented.  As long as you 
promise to look at the docs I add and make sure they actually reflect 
the reality of what you implemented. :)

>Thanks.
>
>  
>
>>and all the matchers.
>>    
>>
>
>What is wrong with this documentation:
>http://language-binding.net/pygccxml/apidocs/index.html
>?
>
>More over in most cases you don't have to use matchers at all. Query API
>will does it for you.
>
>  
>
>>(once again, just a table that lists everything in one
>>place with a short description would be helpful).  I know from
>>experience what source files to look in, but new users don't know this.
>>    
>>
>
>I agree with you.
>
>  
>
>>This could be helped a lot by just having a complete tutorial with pages
>>that have these tables.
>>    
>>
>
>I am going to build documentation, similar to Pyste. It will describe
>functionality
>of py++ and how I expect it should be used.
>  
>
I would like to help with this and I would like to make it possible for 
the community to help with this.  I know writing clear documentation in 
English is difficult for you.  Luckily English is one area where I can 
help out. :)

What do you think about:
- Moving the development of this documentation to a "live" site online?
     I can contribute a wiki backend or server space for any other 
method that people recommend.
- To start, I would copy the current tutorial docs from the svn trunk.  
After that is done, the online docs would be considered the most up to date.
- Letting everyone (you, me, Matthias, and everyone else) contribute to 
this tutorial in it's "live" format
- Make this to document that is equivalent to the pyste tutorial
- Extend this document as needed based on user feedback.  I could add 
documentation about templates, Matthiascould add docs about the 
experimental API, etc.
- When you release a version of pyplusplus, we either 1) just package up 
the current online version of the docs or 2) Copy the online docs to an 
archive section online to be the stable docs for the release, then point 
everyone to those docs for that release version.

Roman, Matthias, everyone: what do you think?  would this be workable 
and acceptable?

-Allen

>
>
>  
>
>>>>If the query api was more completely documented in a tutorial form (so
>>>>newbies don't have to delve deeply into the reference docs), then I
>>>>think we would be on much better footing here.
>>>>        
>>>>
>>>What is wrong with this
>>>http://language-binding.net/pygccxml/query_interface.html
>>>tutorial. If you understand how to use "member_function(s)" , you
>>>understand all others.
>>>
>>>      
>>>
>>Yes, but you have to know what all the "others" are and that they take
>>the same parameters.  Once again, I am not saying we are too far from
>>this, but there is still a disconnect for a new user.
>>    
>>
>
>I will add "others" to the documentation. Thanks for the tip.
>
>  
>
>>>I don't agree with you. I think, the project does not have enough
>>>documentation.
>>>If I will describe every public function in terms of: precondition,
>>>post condition,
>>>arguments and return value, then you will almost never will have to
>>>look to source code.
>>>
>>>      
>>>
>>But even then you are talking about reference documentation.  There
>>needs to be some starting point that lets the user know the capability
>>exists.  Then this can be used as a launching point to looking for the
>>detailed documentation.
>>    
>>
>
>What is wrong with this tutorial
>http://www.language-binding.net/pyplusplus/tutorials/module_builder/module_builder.html
>?
>
>  
>
>>I could be totally wrong here though.  I would love for you to prove me
>>wrong.  I don't care how we get there or who's ideas work, just as long
>>as new users can pick up, understand, and use pyplusplus easily.
>>    
>>
>
>No, you are right. I need to concentrate my attention on documentation.
>
>
>  
>

Re: [pygccxml-development] pyplusplus status

[Roman Y. <rom...@gm...>]

On 7/25/06, Matthias Baas <ba...@ir...> wrote:
> Allen Bierbaum wrote:
> > What do you think about:
> > - Moving the development of this documentation to a "live" site online?
> >      I can contribute a wiki backend or server space for any other
> > method that people recommend.
> > [...]

I see, I have no choice, sorry: I don't like this idea. I think that
the project is
still young and correct documentation is vital for it success. Before every
release I review all documentation and update. I check almost every
piece of code, that is still works. Boost has wiki, almost every week, they
have to rollback few pages back, because of spammers.

> Then what are you waiting for? :)
> I'm definitely in favor of having a wiki for pyplusplus related stuff
> (even if it is not considered to be the official source for
> documentation). The recent logging modifications (+ a small HOWTO how
> log messages can be written to a file, etc) are already an example of
> what I would have liked to add to the wiki.

Now, when this functionality is finally implemented, yesterday I begun to write
documentation to it. You can find the initial version here.

http://svn.sourceforge.net/viewcvs.cgi/pygccxml/pyplusplus_dev/docs/documentation/feedback.rest?view=markup

I'll be glad if you could continue this document.

Please tell me why do you want use wiki instead of writing documentation?
Is there something that I can do with an obstacle?

-- 
Roman Yakovenko
C++ Python language binding
http://www.language-binding.net/

Re: [pygccxml-development] pyplusplus status

[Allen B. <al...@vr...>]

Roman Yakovenko wrote:

>On 7/25/06, Matthias Baas <ba...@ir...> wrote:
>  
>
>>Allen Bierbaum wrote:
>>    
>>
>>>What do you think about:
>>>- Moving the development of this documentation to a "live" site online?
>>>     I can contribute a wiki backend or server space for any other
>>>method that people recommend.
>>>[...]
>>>      
>>>
>
>I see, I have no choice, sorry: I don't like this idea. I think that
>the project is still young and correct documentation is vital for it success. Before every
>release I review all documentation and update. I check almost every
>piece of code, that is still works. 
>
You do have a choice, that is what I was waiting for.  I wanted to see 
if everyone could agree to it being a good idea or a bad idea.  I do not 
plan on creating or updating a pyplusplus wiki documentation area 
without Roman's support.  If Roman is not on board with it, then it is 
bound to fail.

Roman: Could you describe the reasons you don't want the tutorial  to be 
user-editable online?  (so far I think your list is)

- Removes the documentation from the source code.
- How to make sure it is accurate (spammers, bad users, 
misunderstandings, etc)?
- This will prevent the in-code documentation from being updated.
- How do we make a "stable" copy for a release?

I agree with some of this but I think the benefits out weight the costs. 

My response to these issues are.
- Online is only meant for the tutorial, how-tos, and faqs. The code is 
still the absolute authority with the generated reference API being a 
close second.  We should only use the online tools to document things 
that are relatively stable or describe frequent questions.
- Protecting against spammers and bad editis can be difficult.  What I 
have been doing to prevent this is to use a blacklisting plugin that 
detects mis-use and autobans people and also allowing change 
notification so people that are interested get notified of every change 
on the wiki (this allows review).  It is also still possible to read 
through the documentation before a release to make sure it is accurate.
- In code documentation still needs to be updated.  This is not a 
replacement for that.
- I don't know of a great way to make a stable copy for release.  One 
idea would be to create a wiki page that includes all the documentation 
pages for the tutorial into a single page.  Then this page could be 
saved out as html and packaged with the release.  There are also wiki 
plugins that could help support something like this but I have not used 
them before.  (see: http://twiki.org/cgi-bin/view/Plugins/PublishContrib)

Now as to why we want to work on tutorial documentation in this way, I 
can not speak for Matthias, but here is my reasoning:
- Making the documentation live make is very easy for anyone (not just 
people with commit access) to write and update documentation
- Using live documentation in a wiki form allows for immediate editing 
of documentation.  You can make a change in text format and immediately 
see the result.  You don't have to use an html editor or even a text 
editor.  You can just be sitting there reading the documentation, think 
of something that is missing, and add it.  This a very short development 
loop.... (it reminds me of coding in python vs. coding in C++ :)
- Live docs allow the user community to work together to create, edit, 
and comment on documentation. For example plone does this here: 
http://plone.org/documentation/how-to  and php allows comments in their 
docs here: http://www.php.net/manual/en/
- We can make a live knowledge base of issues, howtos, and faqs that 
really describe what people are trying to do and how they have 
accomplished it
- It removes a huge bottleneck in the documentation and feedback process 
because the suggestions and comments don't have to be routed through a 
developer with commit access.
- It is possible for users to see the latest documentation without 
checking out the source code.  For example, what good is an FAQ that has 
an entry about how to do something with a release if you don't see it 
until the next release?

As you can tell, I am biased towards having on-line tutorials and 
howtos, but like I said above, I won't do it without Roman's approval 
and support.

-Allen



>Boost has wiki, almost every week, they
>have to rollback few pages back, because of spammers.
>
>  
>
>>Then what are you waiting for? :)
>>I'm definitely in favor of having a wiki for pyplusplus related stuff
>>(even if it is not considered to be the official source for
>>documentation). The recent logging modifications (+ a small HOWTO how
>>log messages can be written to a file, etc) are already an example of
>>what I would have liked to add to the wiki.
>>    
>>
>
>Now, when this functionality is finally implemented, yesterday I begun to write
>documentation to it. You can find the initial version here.
>
>http://svn.sourceforge.net/viewcvs.cgi/pygccxml/pyplusplus_dev/docs/documentation/feedback.rest?view=markup
>
>I'll be glad if you could continue this document.
>
>Please tell me why do you want use wiki instead of writing documentation?
>Is there something that I can do with an obstacle?
>
>  
>

Re: [pygccxml-development] pyplusplus status

[Roman Y. <rom...@gm...>]

On 7/25/06, Allen Bierbaum <al...@vr...> wrote:
> The way I handle template now and in the experimental API will require
> some changes to how module builder is created.  Specifically, module
> builder will not be able to parse immediately as a side-effect of
> __init__.  It will need to wait until later like the experimental API
> does to give the user time to call template related methods on the
> module builder.  Then when the module builder finally does start parsing
> it will have the information it needs to create the template code
> dynamically.

There is another solution:
http://svn.sourceforge.net/viewcvs.cgi/pygccxml/pyplusplus_dev/unittests/algorithms_tester.py?view=markup

Almost every tester in that file pass C++ code as a string to
module_builder_t.__init__ method.

The documentation to this method is here:
http://www.language-binding.net/pyplusplus/apidocs/pyplusplus.module_builder.builder.module_builder_t-class.html#__init__
and here:
http://www.language-binding.net/pyplusplus/apidocs/pygccxml.parser.project_reader.file_configuration_t-class.html

> I can help when I see places that need documented.  As long as you
> promise to look at the docs I add and make sure they actually reflect
> the reality of what you implemented. :)

I do. May be you can start with documentation, that already exists and
improve it?

> >I am going to build documentation, similar to Pyste. It will describe
> >functionality
> >of py++ and how I expect it should be used.
> >
> >
> I would like to help with this and I would like to make it possible for
> the community to help with this.  I know writing clear documentation in
> English is difficult for you.  Luckily English is one area where I can
> help out. :)

:-)

-- 
Roman Yakovenko
C++ Python language binding
http://www.language-binding.net/

Re: [pygccxml-development] pyplusplus status

[Allen B. <al...@vr...>]

Matthias Baas wrote:

>Allen Bierbaum wrote:
>  
>
>>>>- 90% of users should never have to delve beyond the "easy API" (never
>>>>need to know about creators). The current API is close to this, but
>>>>there are still some times when IMHO users have to suddenly delve very
>>>>deep into the internal code.
>>>>        
>>>>
>>>[...]
>>>      
>>>
>>The big ones I find missing are:
>>
>>    * Do not require the user to know anything outside of the high-level
>>      API to accomplish most tasks.
>>    * Provide access to all the power of pypluplus and pygccxml *if* the
>>      user wants it
>>
>>[...]
>>
>>Am I the only one that feels this way when using the API?
>>    
>>
>
>No, I also think that most of the time it should be enough to stick to 
>the high-level API.
>I would say this is more or less the case with my Maya bindings, but 
>then, I'm still using the "experimental" API instead of Roman's version.
>I've just committed the current version of the API into the "contrib" 
>directory (subdirectory "pypp_api").
>My main script to generate the bindings can be found here (pypp_setup.py):
>http://svn.sourceforge.net/viewcvs.cgi/cgkit/maya/trunk/maya_wrapper/
>  
>
I did not know you were still keeping these up-to-date.  I have to admit 
it has been a long time since I looked at this interface but it does 
seem a little more high-level or at least more self contained.

Q: If I remember correctly, when I first wrote these I had to modify the 
code creators to change they code they output.  Is this still necessary 
or is everything captured in the api itself?  Maybe the better way to 
say this is how do you handle decorating and creating for features that 
are not supported by Roman's API?

>  
>
>>>>- template support: I would like to see an API that allows users to more
>>>>easily wrap templates.  I have had to manually create some code that
>>>>does this but I am sure something better could be done.  You can see
>>>>what I have done at:
>>>>https://realityforge.vrsource.org/viewvc/pyopensg/trunk/src/gen_bindings.py?view=markup 
>>>>
>>>>Look for the TemplateBuilder helper class.
>>>>        
>>>>
>>>My main objection to this is that users will not use it. Think about
>>>it. You can create/generate/generate on fly header file/string and to
>>>include it to the list of header files
>>>passed to module_builder_t.__init__. You don't have to learn  new API.
>>>      
>>>
>>And my main reason for saying this is needed is that doing it manually 
>>is too hard for most users.  It is *much* easier to do this with Pyste.  
>>You just say Template("class") and then instantiate templates.  Very 
>>straight forward in Pyste's domain specific lanaguage.  Unfortunately I 
>>think the domain specific language of pyplusplus is still python and 
>>this is not good IMHO.
>>    
>>
>
>I agree with Allen. If you can use a Template() function then you don't 
>have to know *how* the template class is actually wrapped. Whereas if 
>you have to create C++ source code yourself you have to know what code 
>to create, where to put that code, how the code is added to the sources, 
>etc.
>
>By the way, the pypp_api stuff still contains the Template() 
>functionality that Allen has originally written (though I haven't tested 
>it myself yet as the Maya SDK doesn't contain any templates).
>  
>
I took a quick look at it.  It looks like I implemented it quite a bit 
like the Template helper I am using now, but it was more integrated.  
One of the big reasons is that in the experimental API, the construction 
of the builder is separated from the parsing.  So you could create a 
builder, call the Template() method on it and then when parsing times 
comes around the builder could take care of all the autocreation needed 
behind the scenes for the templates.  It wasn't perfect, but it did make 
it pretty transparent to the users.

>  
>
>>>mb = module_builder_t( ...
>>>    , compilation_mode=pygccxml.parser.COMPILATION_MODE.ALL_AT_ONCE
>>>    , ... )
>>>      
>>>
>>Does this behave *exactly* the same way.  Does it only create one entry 
>>in the cache?
>>    
>>
>
>I don't think so. We were talking about that already in a previous 
>thread quite a while ago. If I remember correctly the ALL_AT_ONCE mode 
>doesn't use the cache at all, that's why I also create my own header 
>file for the Maya bindings and do not use ALL_AT_ONCE.
>
>  
>
>>Would it be useful to make the tutorial and howto a "live" document so 
>>everyone can contribute, add questions, make changes?  If so, what about 
>>using a wiki so everyone can contribute and fix up the descrptions.
>>    
>>
>
>Sounds like a good idea to me!
>  
>
Anyone else agree or disagree?

>  
>
>>>>- Wrap method: Add API for just wrapping an existing method with a new
>>>>defined method.  (right now this can be cone but you have to exclude the
>>>>current method and then call add_code with a 'def'. It is just too
>>>>complex for a new user and makes the wrapper gen script look 
>>>>complicated.)
>>>>        
>>>>
>>>http://www.language-binding.net/pyplusplus/peps/call_wrapper_policies.html 
>>>
>>>
>>>When I implement this PEP, it will be pretty easy to do what you want.
>>>Until then I don't want to introduce something, that I will not 
>>>support later.
>>>      
>>>
>>I don't see how this pep fixes the problem, but then again I don't fully 
>>understand what the pep will do.  I will just trust you that this will 
>>help out.
>>    
>>
>
>I think you two are talking about somewhat different things here.
>If I understand Allen correctly he wants to replace a method with his 
>own code instead of wrapping the original method. The original method 
>might even never get called in the wrapper code but the wrapper code 
>will still provide the same functionality. I also did that for methods 
>that deal with stuff like function pointers that need some manual 
>intervention anyway (even though in most cases I did actually call the 
>original method).
>  
>
Exactly.

>The "call wrapper policies" (in my version they are still called arg 
>policies) are rather meant to attach additional code to a wrapper method 
>that surrounds the original method invocation. This surrounding code is 
>mainly used to transform input arguments or return values between Python 
>and C++ (which cannot be done by Boost.Python automatically in those 
>cases). One example is the often mentioned "void getSize(int& width, 
>int& height)" method which cannot be wrapped directly because of the 
>references.
>
>  
>
Yes, I need these too.

>>>>- Add ability to add user code to namespace or global *without* having
>>>>to use code creators directly
>>>>        
>>>>
>>>I want to solve this problem, to this release. Can you write what you
>>>want/need/expect
>>>here? In other words I need use cases and how you see they should be 
>>>solved.
>>>      
>>>
>>I will have to think about this and get back to you.
>>    
>>
>
>I take it your basically talking about the addStartText(), 
>addBodyTailText() methods that you implemented in the experimental 
>version, right? They are still available in pypp_api and I'm also using 
>them myself.
>  
>
Yes, that is what I am thinking about.  I am actually just trying to 
port some code that used the experimental pypp_api and I could not find 
a way to do this.

>  
>
>>>>- Cache parsing and preparing query optimizer.  If the input has not
>>>>changed (the headers are the same) why do I have to wait for all the
>>>>processing of the declarations and query optimization each time.  Can't
>>>>we cache all of that?
>>>>        
>>>>
>>>Yes, but you can guess what the priority of this. Also I think that
>>>solution for this
>>>problem will be completely in the user code.
>>>      
>>>
>
>Wouldn't that rather be located in the high level API where the queries 
>are made? (if it's in the user code it would have to be duplicated with 
>every new project)
>  
>
I agree.  This should be handled by the module builder so users don't 
need to know the implementation details.  As I think about it right now, 
we are really just caching some of the module builder data structures so 
this seems like exactly something that should be encapsulated in the 
module builder.

Experimental API, pypp_api...

I did not realize that there were still two active high-level APIs being 
developed.  As a user this concerns me a little because it means that 
there are probably good ideas in both that are not being cross-mixed to 
get the best API possible.  (some of the topics above point out those 
cases).

Also, after thinking about it more I believe that many of the limits and 
issues I am having were addressed at least in some form by the 
experimental API.  The way pypp_api was designed was to provide a very 
simple and easy to use API that could accomplish what most users would 
want with a minimal understanding of pyplusplus.  One way to make 
Roman's API more complete and simple would be to re-examine the pypp_api 
and make sure that Roman's API can do all the things that pypp_api can 
do with the same level of simplicitly.

Comments?

-Allen

Re: [pygccxml-development] pyplusplus status

[Matthias B. <ba...@ir...>]

Allen Bierbaum wrote:
> I did not know you were still keeping these up-to-date.  I have to admit 
> it has been a long time since I looked at this interface but it does 
> seem a little more high-level or at least more self contained.

Being self contained has always been a feature that I liked with our 
high level API(s). There has always been a clear separation between 
"high level" and "low level" stuff which in my opinion is an advantage 
to keep maintenance simpler. Unfortunately, this separation got somewhat 
lost in Roman's version and when I look at code in pyplusplus (or even 
try to modify something) I'm not always sure if this belongs to the "low 
level" side and that there might be interdependencies that I just don't 
know of (see my previous post about the broken make_flatten() function).

> Q: If I remember correctly, when I first wrote these I had to modify the 
> code creators to change they code they output.  Is this still necessary 
> or is everything captured in the api itself?  

The code in the repository is exactly the code that I am using, I don't 
have a private version of pyplusplus that is different from the repository.

> Maybe the better way to 
> say this is how do you handle decorating and creating for features that 
> are not supported by Roman's API?

Which features are you referring to? There might still be some 
decoration functions that don't have the desired effect (like 
finalize()) because the underlying functionality in pyplusplus is still 
missing. Some other stuff (like argument policies) are implemented in 
pypp_api itself.

- Matthias -

Re: [pygccxml-development] pyplusplus status

[Matthias B. <ba...@ir...>]

Allen Bierbaum wrote:
>>> - 90% of users should never have to delve beyond the "easy API" (never
>>> need to know about creators). The current API is close to this, but
>>> there are still some times when IMHO users have to suddenly delve very
>>> deep into the internal code.
>>
>> [...]
> 
> The big ones I find missing are:
> 
>     * Do not require the user to know anything outside of the high-level
>       API to accomplish most tasks.
>     * Provide access to all the power of pypluplus and pygccxml *if* the
>       user wants it
> 
> [...]
> 
> Am I the only one that feels this way when using the API?

No, I also think that most of the time it should be enough to stick to 
the high-level API.
I would say this is more or less the case with my Maya bindings, but 
then, I'm still using the "experimental" API instead of Roman's version.
I've just committed the current version of the API into the "contrib" 
directory (subdirectory "pypp_api").
My main script to generate the bindings can be found here (pypp_setup.py):
http://svn.sourceforge.net/viewcvs.cgi/cgkit/maya/trunk/maya_wrapper/

>>> - template support: I would like to see an API that allows users to more
>>> easily wrap templates.  I have had to manually create some code that
>>> does this but I am sure something better could be done.  You can see
>>> what I have done at:
>>> https://realityforge.vrsource.org/viewvc/pyopensg/trunk/src/gen_bindings.py?view=markup 
>>>
>>> Look for the TemplateBuilder helper class.
>>
>> My main objection to this is that users will not use it. Think about
>> it. You can create/generate/generate on fly header file/string and to
>> include it to the list of header files
>> passed to module_builder_t.__init__. You don't have to learn  new API.
> 
> And my main reason for saying this is needed is that doing it manually 
> is too hard for most users.  It is *much* easier to do this with Pyste.  
> You just say Template("class") and then instantiate templates.  Very 
> straight forward in Pyste's domain specific lanaguage.  Unfortunately I 
> think the domain specific language of pyplusplus is still python and 
> this is not good IMHO.

I agree with Allen. If you can use a Template() function then you don't 
have to know *how* the template class is actually wrapped. Whereas if 
you have to create C++ source code yourself you have to know what code 
to create, where to put that code, how the code is added to the sources, 
etc.

By the way, the pypp_api stuff still contains the Template() 
functionality that Allen has originally written (though I haven't tested 
it myself yet as the Maya SDK doesn't contain any templates).

>> mb = module_builder_t( ...
>>     , compilation_mode=pygccxml.parser.COMPILATION_MODE.ALL_AT_ONCE
>>     , ... )
> 
> Does this behave *exactly* the same way.  Does it only create one entry 
> in the cache?

I don't think so. We were talking about that already in a previous 
thread quite a while ago. If I remember correctly the ALL_AT_ONCE mode 
doesn't use the cache at all, that's why I also create my own header 
file for the Maya bindings and do not use ALL_AT_ONCE.

> Would it be useful to make the tutorial and howto a "live" document so 
> everyone can contribute, add questions, make changes?  If so, what about 
> using a wiki so everyone can contribute and fix up the descrptions.

Sounds like a good idea to me!

>>> - Wrap method: Add API for just wrapping an existing method with a new
>>> defined method.  (right now this can be cone but you have to exclude the
>>> current method and then call add_code with a 'def'. It is just too
>>> complex for a new user and makes the wrapper gen script look 
>>> complicated.)
>>
>> http://www.language-binding.net/pyplusplus/peps/call_wrapper_policies.html 
>>
>>
>> When I implement this PEP, it will be pretty easy to do what you want.
>> Until then I don't want to introduce something, that I will not 
>> support later.
> 
> I don't see how this pep fixes the problem, but then again I don't fully 
> understand what the pep will do.  I will just trust you that this will 
> help out.

I think you two are talking about somewhat different things here.
If I understand Allen correctly he wants to replace a method with his 
own code instead of wrapping the original method. The original method 
might even never get called in the wrapper code but the wrapper code 
will still provide the same functionality. I also did that for methods 
that deal with stuff like function pointers that need some manual 
intervention anyway (even though in most cases I did actually call the 
original method).

The "call wrapper policies" (in my version they are still called arg 
policies) are rather meant to attach additional code to a wrapper method 
that surrounds the original method invocation. This surrounding code is 
mainly used to transform input arguments or return values between Python 
and C++ (which cannot be done by Boost.Python automatically in those 
cases). One example is the often mentioned "void getSize(int& width, 
int& height)" method which cannot be wrapped directly because of the 
references.

>>> - Add ability to add user code to namespace or global *without* having
>>> to use code creators directly
>>
>> I want to solve this problem, to this release. Can you write what you
>> want/need/expect
>> here? In other words I need use cases and how you see they should be 
>> solved.
> 
> I will have to think about this and get back to you.

I take it your basically talking about the addStartText(), 
addBodyTailText() methods that you implemented in the experimental 
version, right? They are still available in pypp_api and I'm also using 
them myself.

>>> - Cache parsing and preparing query optimizer.  If the input has not
>>> changed (the headers are the same) why do I have to wait for all the
>>> processing of the declarations and query optimization each time.  Can't
>>> we cache all of that?
>>
>> Yes, but you can guess what the priority of this. Also I think that
>> solution for this
>> problem will be completely in the user code.

Wouldn't that rather be located in the high level API where the queries 
are made? (if it's in the user code it would have to be duplicated with 
every new project)

>>> - This is a small nitpick, but unless you are making a lot of money from
>>> Google AdSense, could you remove the Google ads in the table of contents
>>> on the website.  They are just annoying and make the documentation
>>> harder to read.
>>
>> I am not, the AdSence is there to return the money I pay for running 
>> web site.
>> I hate the idea to ask for donations. User experience is importer.
>> I will do something about it.
> 
> That would be very helpful. I do not care about the ads on the left bar 
> or even if you added ones at the other sides of the pages.  But putting 
> ads in the middle of the table of contents or text body is a little 
> annoying.

I also think the web page is a bit difficult to read because of the ads. 
  Roman, I don't know how much control you have about the layout of the 
site and the ads, but would it also be possible to separate them from 
the actual content somehow? Like for example, using a different 
background color, adding separating lines or something like this. 
Currently, the distinction between content and ad is not obvious at 
first glance.


- Matthias -

Re: [pygccxml-development] pyplusplus status

[Roman Y. <rom...@gm...>]

On 7/18/06, Matthias Baas <ba...@ir...> wrote:
> No, I also think that most of the time it should be enough to stick to
> the high-level API.
> I would say this is more or less the case with my Maya bindings, but
> then, I'm still using the "experimental" API instead of Roman's version.
> I've just committed the current version of the API into the "contrib"
> directory (subdirectory "pypp_api").

Would you mind to clean experimental directory?

> My main script to generate the bindings can be found here (pypp_setup.py):
> http://svn.sourceforge.net/viewcvs.cgi/cgkit/maya/trunk/maya_wrapper/

It will take some time to me to learn pypp_api and how you use it in
your script.


I will try to take a look on cache and ALL_AT_ONCE issue in next few days.

> > Would it be useful to make the tutorial and howto a "live" document so
> > everyone can contribute, add questions, make changes?  If so, what about
> > using a wiki so everyone can contribute and fix up the descrptions.
>
> Sounds like a good idea to me!

I am not against this idea. I think that before we going to it we can improve
existing documentation, faqs and how to. I prefer to have only 1
place, where user
have to look for documentation.

> I think you two are talking about somewhat different things here.
> If I understand Allen correctly he wants to replace a method with his
> own code instead of wrapping the original method. The original method
> might even never get called in the wrapper code but the wrapper code
> will still provide the same functionality. I also did that for methods
> that deal with stuff like function pointers that need some manual
> intervention anyway (even though in most cases I did actually call the
> original method).

"User defined transformation" does not have to call to original function.
If you talk about function "replace" you are talking transformation, otherwise
it is much easier to exclude function and to add reference to new function under
same name.

> The "call wrapper policies" (in my version they are still called arg
> policies) are rather meant to attach additional code to a wrapper method
> that surrounds the original method invocation. This surrounding code is
> mainly used to transform input arguments or return values between Python
> and C++ (which cannot be done by Boost.Python automatically in those
> cases). One example is the often mentioned "void getSize(int& width,
> int& height)" method which cannot be wrapped directly because of the
> references.

Think about method transformation as a generalization of your idea.

> >>> - Add ability to add user code to namespace or global *without* having
> >>> to use code creators directly
> >>
> >> I want to solve this problem, to this release. Can you write what you
> >> want/need/expect
> >> here? In other words I need use cases and how you see they should be
> >> solved.
> >
> > I will have to think about this and get back to you.
>
> I take it your basically talking about the addStartText(),
> addBodyTailText() methods that you implemented in the experimental
> version, right? They are still available in pypp_api and I'm also using
> them myself.

Why you work so hard? You can start the editor you use every day. To write
"start text" in it. ( The better name is - user defined  declarations. )
Then using the technique described
http://svn.sourceforge.net/viewcvs.cgi/pygccxml/pyplusplus_dev/docs/faqs/faqs.rest?view=markup
section "How to add custom exception translation?" you can add it to module
body.

> >>> - Cache parsing and preparing query optimizer.  If the input has not
> >>> changed (the headers are the same) why do I have to wait for all the
> >>> processing of the declarations and query optimization each time.  Can't
> >>> we cache all of that?
> >>
> >> Yes, but you can guess what the priority of this. Also I think that
> >> solution for this
> >> problem will be completely in the user code.
>
> Wouldn't that rather be located in the high level API where the queries
> are made? (if it's in the user code it would have to be duplicated with
> every new project)

I think you missed the point. py++ can do( and may be some day will do ) the
dirty job of updating decl wrapper classes within a cache, but the cache
managment will be done completly from user code.

-- 
Roman Yakovenko
C++ Python language binding
http://www.language-binding.net/

Re: [pygccxml-development] pyplusplus status

[Matthias B. <ba...@ir...>]

Roman Yakovenko wrote:
> On 7/18/06, Matthias Baas <ba...@ir...> wrote:
>> I've just committed the current version of the API into the "contrib"
>> directory (subdirectory "pypp_api").
> 
> Would you mind to clean experimental directory?

Done. I've removed the experimental directory (anybody who still wants 
to have a look at those files (Allen?) has to roll back temporarily to 
revision 330).

- Matthias -

Re: [pygccxml-development] pyplusplus status

[Allen B. <al...@vr...>]

[snip]

>>>Would it be useful to make the tutorial and howto a "live" document so
>>>everyone can contribute, add questions, make changes?  If so, what about
>>>using a wiki so everyone can contribute and fix up the descrptions.
>>>      
>>>
>>Sounds like a good idea to me!
>>    
>>
>
>I am not against this idea. I think that before we going to it we can improve
>existing documentation, faqs and how to. I prefer to have only 1
>place, where user
>have to look for documentation.
>  
>
Agreed, but what if the one place for the tutorial and faq was a wiki or 
something similar where users and developers could contribute and make 
comments?

[snip]

>  
>
>>>>>- Cache parsing and preparing query optimizer.  If the input has not
>>>>>changed (the headers are the same) why do I have to wait for all the
>>>>>processing of the declarations and query optimization each time.  Can't
>>>>>we cache all of that?
>>>>>          
>>>>>
>>>>Yes, but you can guess what the priority of this. Also I think that
>>>>solution for this
>>>>problem will be completely in the user code.
>>>>        
>>>>
>>Wouldn't that rather be located in the high level API where the queries
>>are made? (if it's in the user code it would have to be duplicated with
>>every new project)
>>    
>>
>
>I think you missed the point. py++ can do( and may be some day will do ) the
>dirty job of updating decl wrapper classes within a cache, but the cache
>managment will be done completly from user code.
>
>  
>
What do you mean by "cache management" will be done in user code.  Do 
you just mean the user code will tell pyplusplus what things to cache 
and where the cache is and then it will be up to pyplusplus to read and 
update the cache?

-Allen

Re: [pygccxml-development] pyplusplus status

[Roman Y. <rom...@gm...>]

On 7/19/06, Allen Bierbaum <al...@vr...> wrote:
> What do you mean by "cache management" will be done in user code.  Do
> you just mean the user code will tell pyplusplus what things to cache

No

> and where the cache is

Yes

> and then it will be up to pyplusplus to read and
> update the cache?

Yes and no. Only user knows whether code chaned in a such way, that he should
drop configuration from cache and to create new configuration.

That what I mean under "cache management". Of course I could be wrong.

-- 
Roman Yakovenko
C++ Python language binding
http://www.language-binding.net/

Re: [pygccxml-development] pyplusplus status

[Matthias B. <ba...@ir...>]

Allen Bierbaum wrote:
> What do you think about:
> - Moving the development of this documentation to a "live" site online?
>      I can contribute a wiki backend or server space for any other 
> method that people recommend.
> [...]

Then what are you waiting for? :)
I'm definitely in favor of having a wiki for pyplusplus related stuff 
(even if it is not considered to be the official source for 
documentation). The recent logging modifications (+ a small HOWTO how 
log messages can be written to a file, etc) are already an example of 
what I would have liked to add to the wiki.


- Matthias -

Re: [pygccxml-development] pyplusplus status

[Matthias B. <ba...@ir...>]

I think we are intermingling two separate questions that, in my opinion, 
should be treated independently:

(1) Is it reasonable/useful/desirable/cool to have a pyplusplus related 
wiki where *users* can add any information they deem useful when dealing 
with pyplusplus?

(2) Should the above wiki also be used as the primary source for the 
official pyplusplus documentation?

My previous answer to Allen's posting was dealing with the first 
question and I'm still in favor of such a wiki.
As to the second question, that's entirely up to Roman as this 
influences the way he creates the documentation. If he doesn't feel 
comfortable with using the wiki for the official documentation, then I 
accept that and it's no problem with me. But if the answer to the second 
question from above is "no" then I don't see why the answer to the first 
question also has to be "no".

Basically, I agree with all points that Allen has made. The main 
advantages of a wiki for me are the following:

- *Anybody* can contribute and it's as little hassle as it can get (an 
arbitrary web browser is the only tool that is required) => It reduces 
the threshold of whether a user will decide to contribute or not.

- You get immediate feedback on how the page looks. You can use 
formatting such as bold face, italics, switch the font, use tables, 
images (if the wiki allows it), link to other pages, etc.

- Wikis are quite common nowadays which means chances are that a user 
already has used a wiki before. And if you've used one wiki you know how 
to use other wikis as well => the above threshold is lowered even some 
more as a user doesn't have to learn new tools

- When there's the option to register you get the chance to get notified 
about changes to the wiki. This means you have the option to always be 
informed about the contents of the wiki and what changes have been done. 
On a regular web page you would have to maintain (and publish) a 
changelog to achieve the same thing.

- A wiki would also be a nice place for adding information about the 
stuff in "contrib" which is no official code and won't be mentioned in 
the official documentation anyway.


Roman Yakovenko wrote:
>> if everyone could agree to it being a good idea or a bad idea.  I do not
>> plan on creating or updating a pyplusplus wiki documentation area
>> without Roman's support.  If Roman is not on board with it, then it is
>> bound to fail.
> 
> I think you exaggerate a little. I don't want to maintain it 

If I've interpreted Allen's mail correctly then he has already 
volunteered to maintain the wiki and even host it. So it doesn't mean 
any extra work for you.

> or insure that all that is written there is 100 % correct. 

That's the beauty of a wiki, whenever some user encounters something 
that is not correct he has the option to edit the page and simply fix it 
himself. :)

> The maintainer of the wiki can subscribe to
> svn-commit list and update the wiki according to the changes.

Sounds good in theory, but I'm pretty much sure that this won't work in 
practice (unless you find someone who has really a lot of time at hand).
But anyway, this is not required at all. A wiki would never replace the 
reference manual generated by epydoc and having a wiki also doesn't mean 
that we can drop doc strings.

>> Roman: Could you describe the reasons you don't want the tutorial  to be
>> user-editable online?  (so far I think your list is)
>>
>> - Removes the documentation from the source code.
>> - How to make sure it is accurate (spammers, bad users,
>> misunderstandings, etc)?
>> - This will prevent the in-code documentation from being updated.
>> - How do we make a "stable" copy for a release?
>>
>> I agree with some of this but I think the benefits out weight the costs.
>>
>> My response to these issues are.
>> - Online is only meant for the tutorial, how-tos, and faqs.
> 
> In my opinion tutorials could not be written using wiki. I just don't
> see how it
> could work.  Tutorials is short, clear, well formulated and 100%
> correct document. Wiki can not achieve this.

Why do you think so?

1) A wiki is just a tool for writing text and making it available to the 
public. It's up to the person who is writing the text whether the text 
is correct or not. If a person can write a correct tutorial in Word, 
Emacs or whatever then that same person can also enter a correct 
tutorial into a wiki.

2) As already mentioned above, if some other users notice something that 
is not correct they can simply fix it themselves.

3) How do you explain the success of Wikipedia? ;)

>> Now as to why we want to work on tutorial documentation in this way, I
>> can not speak for Matthias, but here is my reasoning:
>> - Making the documentation live make is very easy for anyone (not just
>> people with commit access) to write and update documentation
> 
> I don't count this as argument. You can open any email client, write a
> documentaiton and send it to me. I will integrate it in a day or two.
> Every one who contributed to pyplusplus is mentioned.

How many such mails have you got so far? Personally, I have already 
entered text into wikis but I have never sent a piece of documentation 
to an author of a software.
Writing an email doesn't have the advantages of a wiki and the above 
mentioned threshold that a user has to overcome before deciding to 
contribute something is higher (why should I bother someone personally 
just because I want some modifications to the documentation which is not 
meant to be edited publically?).

> This is another problem with the wiki. In order to prevent spam you will
> force user to register himself. I don't have statistic, but as for me, I 
> use registration only when I absolutely need.

I agree that registration is a minor nuisance. But I wouldn't mind 
registering if 1) the site tells me that this is only to protect the 
site from spammers and 2) I only have to provide a user name and 
password and no other personal information.
On the other hand, registration has the advantage that you can customize 
the wiki to your own personal taste and you can be notified about changes.

>> - Live docs allow the user community to work together to create, edit,
>> and comment on documentation.
> 
> pyplusplus still does not have community :-(. It does have users, but not
> community.

 >>> users==community
True

See? :)

>> For example, what good is an FAQ that has
>> an entry about how to do something with a release if you don't see it
>> until the next release?
> 
> I think, that the answer is obvious: use code from Subversion. Anyway
> my point here is that this item does not worse any effort.

Not everyone is familiar with subversion and knows how to build the 
documentation (or is willing to do all that just to check if there's a 
new FAQ item). Pointing your web browser to a particular page is much 
easier.


So the bottom line is that I would answer my initial question (1) with 
"yes, definitely" and leave the answer of question (2) up to Roman 
(which he has already answered with "no").

- Matthias -

Re: [pygccxml-development] pyplusplus status

[Roman Y. <rom...@gm...>]

On 7/26/06, Matthias Baas <ba...@ir...> wrote:
> I think we are intermingling two separate questions that, in my opinion,
> should be treated independently:
>
> (1) Is it reasonable/useful/desirable/cool to have a pyplusplus related
> wiki where *users* can add any information they deem useful when dealing
> with pyplusplus?
>
> (2) Should the above wiki also be used as the primary source for the
> official pyplusplus documentation?
>
> My previous answer to Allen's posting was dealing with the first
> question and I'm still in favor of such a wiki.
> As to the second question, that's entirely up to Roman as this
> influences the way he creates the documentation. If he doesn't feel
> comfortable with using the wiki for the official documentation, then I
> accept that and it's no problem with me. But if the answer to the second
> question from above is "no" then I don't see why the answer to the first
> question also has to be "no".

I agree with you.
>
> Basically, I agree with all points that Allen has made. The main
> advantages of a wiki for me are the following:

I understand those points. I'd like that all contribution to the wiki
will be done
under boost license. I want to take all good thing from the wiki to py++.

> > pyplusplus still does not have community :-(. It does have users, but not
> > community.
>
>  >>> users==community
> True
>
> See? :)

:-) yes.

> So the bottom line is that I would answer my initial question (1) with
> "yes, definitely" and leave the answer of question (2) up to Roman
> (which he has already answered with "no").

I agree with Matthias

-- 
Roman Yakovenko
C++ Python language binding
http://www.language-binding.net/

Re: [pygccxml-development] pyplusplus status

[Roman Y. <rom...@gm...>]

On 7/25/06, Allen Bierbaum <al...@vr...> wrote:
> Roman Yakovenko wrote:
> You do have a choice, that is what I was waiting for.

:-)

>  I wanted to see
> if everyone could agree to it being a good idea or a bad idea.  I do not
> plan on creating or updating a pyplusplus wiki documentation area
> without Roman's support.  If Roman is not on board with it, then it is
> bound to fail.

I think you exaggerate a little. I don't want to maintain it or insure
that all that is
written there is 100 % correct. The maintainer of the wiki can subscribe to
svn-commit list and update the wiki according to the changes.

> Roman: Could you describe the reasons you don't want the tutorial  to be
> user-editable online?  (so far I think your list is)
>
> - Removes the documentation from the source code.
> - How to make sure it is accurate (spammers, bad users,
> misunderstandings, etc)?
> - This will prevent the in-code documentation from being updated.
> - How do we make a "stable" copy for a release?
>
> I agree with some of this but I think the benefits out weight the costs.
>
> My response to these issues are.
> - Online is only meant for the tutorial, how-tos, and faqs.

In my opinion tutorials could not be written using wiki. I just don't
see how it
could work.  Tutorials is short, clear, well formulated and 100%
correct document.
Wiki can not achieve this.

> Now as to why we want to work on tutorial documentation in this way, I
> can not speak for Matthias, but here is my reasoning:
> - Making the documentation live make is very easy for anyone (not just
> people with commit access) to write and update documentation

I don't count this as argument. You can open any email client, write a
documentaiton and send it to me. I will integrate it in a day or two.
Every one who contributed to pyplusplus is mentioned.

> - Using live documentation in a wiki form allows for immediate editing
> of documentation.  You can make a change in text format and immediately
> see the result.  You don't have to use an html editor or even a text
> editor.  You can just be sitting there reading the documentation, think
> of something that is missing, and add it.  This a very short development
> loop....

This is another problem with the wiki. In order to prevent spam you will
force user to register himself. I don't have statistic, but as for me, I use
registration only when I absolutely need.

> - Live docs allow the user community to work together to create, edit,
> and comment on documentation.

pyplusplus still does not have community :-(. It does have users, but not
community.

> For example plone does this here:
> http://plone.org/documentation/how-to  and php allows comments in their
> docs here: http://www.php.net/manual/en/

Python does it too.

> - We can make a live knowledge base of issues, howtos, and faqs that
> really describe what people are trying to do and how they have
> accomplished it

Here you are right. Wiki can provide good feedback.

> - It is possible for users to see the latest documentation without
> checking out the source code.

Here you are almost right too, but it has nothing to do with wiki. I
don't update
documentation on site between releases, because I want the functionality to
become stable. This process takes few month.

> For example, what good is an FAQ that has
> an entry about how to do something with a release if you don't see it
> until the next release?

I think, that the answer is obvious: use code from Subversion. Anyway
my point here is that this item does not worse any effort.

> As you can tell, I am biased towards having on-line tutorials and
> howtos, but like I said above, I won't do it without Roman's approval
> and support.

As I said, will not be an active maintainer but I will do provide a help.

As for me wiki will be good in a future. But before starting wiki, I
think pyplusplus
should have good documentation.

-- 
Roman Yakovenko
C++ Python language binding
http://www.language-binding.net/

Re: [pygccxml-development] pyplusplus status

[Allen B. <al...@vr...>]

>> Roman: Could you describe the reasons you don't want the tutorial  to be
>> user-editable online?  (so far I think your list is)
>>
>> - Removes the documentation from the source code.
>> - How to make sure it is accurate (spammers, bad users,
>> misunderstandings, etc)?
>> - This will prevent the in-code documentation from being updated.
>> - How do we make a "stable" copy for a release?
>>
>> I agree with some of this but I think the benefits out weight the costs.
>>
>> My response to these issues are.
>> - Online is only meant for the tutorial, how-tos, and faqs.
>
>
> In my opinion tutorials could not be written using wiki. I just don't
> see how it
> could work.  Tutorials is short, clear, well formulated and 100%
> correct document.
> Wiki can not achieve this.

I have to respectfully disagree here.  I have seen a wiki work for this 
type of thing and work very well.  I think you too would believe it once 
you see it. :)

>
>> Now as to why we want to work on tutorial documentation in this way, I
>> can not speak for Matthias, but here is my reasoning:
>> - Making the documentation live make is very easy for anyone (not just
>> people with commit access) to write and update documentation
>
>
> I don't count this as argument. You can open any email client, write a
> documentaiton and send it to me. I will integrate it in a day or two.
> Every one who contributed to pyplusplus is mentioned.

There are bottlenecks here though:
- Someone has to check out subversion and know how to edit the rest files
- They have to edit it and generate the docs
- They then have to send it to you and wait for it to be integrated.

In my experience, wiki just makes this much faster.  What do other 
people think here?

>
>> - Using live documentation in a wiki form allows for immediate editing
>> of documentation.  You can make a change in text format and immediately
>> see the result.  You don't have to use an html editor or even a text
>> editor.  You can just be sitting there reading the documentation, think
>> of something that is missing, and add it.  This a very short development
>> loop....
>
>
> This is another problem with the wiki. In order to prevent spam you will
> force user to register himself. I don't have statistic, but as for me, 
> I use
> registration only when I absolutely need.

True, but already people have to go through at least as much trouble as 
registering if they want to get access to the svn docs and if they want 
to edit and submit changes.

>
>> - Live docs allow the user community to work together to create, edit,
>> and comment on documentation.
>
>
> pyplusplus still does not have community :-(. It does have users, but not
> community.

I think it could have a community if we start building one.  Until we 
build it, there won't be one.

>
> [cut]
>
>> As you can tell, I am biased towards having on-line tutorials and
>> howtos, but like I said above, I won't do it without Roman's approval
>> and support.
>
>
> As I said, will not be an active maintainer but I will do provide a help.
>
> As for me wiki will be good in a future. But before starting wiki, I
> think pyplusplus
> should have good documentation.

One other way to look at it is that by putting it on the wiki you could 
get a lot of help on the documentation.  I know I would use the wiki as 
my primary documentation for pyplusplus and would add to it all the time 
while using the API.  It sounds like there may be some other people that 
would be willing to help out with this as well.

So in a way, it could make your life easier by letting us help you write 
the documentation while you are still concentrating on fixing lingering 
bugs and documenting the code.

But enough of what I think, what do other people think?  Are there other 
users on this list that would contribute to a wiki for documenting and 
extending pyplusplus?

-Allen