[Insight-users] Examples wiki

Tue Jul 14 06:52:59 EDT 2009

Hi Bill, 

I wonder if the trac open source project may have the beginnings of tools to achieve
your vision:

http://trac.edgewall.org/

It combines a module-level source view with linked wiki pages. I'm not sure it has
testing behind it, but it may be achievable collaboratively.

Badri Roysam
Professor, Department of Electrical, Computer and Systems Engineering
Associate Director, NSF Center for Subsurface Sensing & Imaging Systems (CenSSIS ERC)
Co-Director, Rensselaer Center for Open Source Software
Rensselaer Polytechnic Institute
110 8th Street, Troy, New York 12180-3590, USA.
Office(JEC 7010): 518-276-8067, Assistant: 518-276-8525, Lab(JEC 6308): 518-276-8207, Fax: 518-276-8715
Email: roysam at ecse.rpi.edu, Web: http://www.ecse.rpi.edu/~roysam

----- Original Message -----
From: Bill Lorensen [mailto:bill.lorensen at gmail.com]
To: David Doria [mailto:daviddoria+itk at gmail.com]
Cc: insight-users at itk.org
Subject: Re: [Insight-users] Examples wiki

> David,
> 
> I think it is a worthwhile discussion. I think a wiki is a great spot
> for these examples. But, simple examples can still be compiled and
> tested. Perhaps one way would to do is to have a cvs or svn link that
> the user could click to download the example. The wiki could still
> show the text of the example, although it could get out of date with
> the cvs/svn.
> 
> For instance, all of the examples in the Insight Software Guide are
> built and run nightly. The images are regression checked. The examples
> have the documentation markup included in them.
> 
> I think creating wiki examples that conform to the itk style is not
> very difficult and the development team could certainly help out
> creating a process.
> 
> Bill
> 
> On Mon, Jul 13, 2009 at 2:37 PM, David Doria<daviddoria+itk at gmail.com>
> wrote:
> > On Mon, Jul 13, 2009 at 1:41 PM, Bill Lorensen<bill.lorensen at gmail.com>
> wrote:
> >> My concern is that these examples would not be compiled, regression
> >> tested, valgrind'ed, style checked, etc. Will they compile on all
> >> platforms? If we can come up with mechanism to test them, then it
> >> sounds like a good idea.
> >>
> >> I looked at one example on the vtk wiki:
> >> http://www.vtk.org/Wiki/Get_the_names_of_all_of_the_data_arrays
> >> A few things I noticed:
> >> 1) It uses hard tabs. This code could not be checked into the itk
> repository.
> >> 2) main uses exit() rather than return().
> >> 3) It creates a vtk object with ::New, but does not do a Delete().
> >>
> >> 1) would be caught at checkin.
> >> 2) might be picked up as a warning by one of the itk compilers.
> >> 3) would be detected by valgrind.
> >>
> >> Bill
> >>
> >
> > Bill -
> >
> > Certainly all valid concerns. My intention, however, has been to
> > provide something simply to demonstrate the ideas. There could
> > certainly be a disclaimer "This code is intended to demonstrate
> > concepts and is not guaranteed to be memory-leak free and does not
> > necessary adhere to VTK coding standards". After all, they are not
> > part of VTK, but simply a cut and paste of a users code (which,
> > obviously, is not usually going to follow the standards!).
> >
> > As a user who has gone through the learning curve (well, GOING
> > through, haha), personally I would have benefited from such things
> > immensely - in fact, they are directly the result of my learning VTK!
> > They are kind of like pointers from ideas that the user pre-VTK
> > understands, e.g. "I want to make a cube" to vtk classes/ideas, e.g.
> > vtkCubeSource. If a new user digs through the examples that ship with
> > the software, it is sometimes difficult to find such a pointer.
> >
> > I guess my concern with actually checking in this kind of example is
> > that it would cause a lack of "ability/desire to contribute". That is,
> > "non-developers" may not want to take the time to learn the coding
> > styles and practices enough to get their examples into shape to add to
> > the repository, but they would be much more willing to "dump" a page
> > of code onto the wiki. I guess I was kind of counting on the "wiki"
> > phenomenon to clean up the code - that is, someone like yourself
> > quickly caught a couple of problems in the
> > Get_the_names_of_all_of_the_data_arrays example and then they would be
> > fixed. Also, they would not want the responsibility of ensuring the
> > examples compile cross-platform / with different versions of VTK, etc.
> > - the point is just "it took me an afternoon to figure X out - maybe
> > this will save you some trouble". That all said - maybe we can't count
> > on this type of contribution, either, as not a SINGLE example has been
> > added to the examples section I started by another user - but it DOES
> > seem like people are looking at them judging by some of the hit
> > counters being > 500 (assuming this is accurate and "bot free").
> >
> > To your point about regression testing - again this would rely on the
> > wiki mentality. There are plenty of other places that code appears
> > which is not regression tested (the Insight journal,
> > xxSoftwareGuide.pdf, etc) and, clearly, it is not even possible to
> > test (as it is in a document format). When I find a source like that
> > and then realize it is not compatible with the current release, there
> > is basically nothing that can be done. With the wiki, if a user finds
> > an error in the code due to regression, it can simply be modified.
> > Obviously the check for this is more manual than an actual regression
> > test, but, because of my "lack of contribution" notes above, it seems
> > like a reasonable alternative.
> >
> > Maybe there could be some sort of "Examples sandbox" which could have
> > public svn access rights for people to "dump" code into, and then as
> > experienced users with time on their hands come along they could
> > slowly be cleaned up into actual, regression testable examples? I just
> > fear something like that would not get as much visibility as the wiki
> > - where from the VTK homepage the user can simply find "Help->Wiki"
> > and many examples are visible right away. And if a user downloads the
> > release version of the code (non-cvs), these would clearly be
> > inaccessible.
> >
> > Please let me know if we should continue this conversation / if you
> > have any comments on these ideas.
> >
> > Thanks,
> >
> > David
> > _____________________________________
> > Powered by www.kitware.com
> >
> > Visit other Kitware open-source projects at
> > http://www.kitware.com/opensource/opensource.html
> >
> > Please keep messages on-topic and check the ITK FAQ at:
> http://www.itk.org/Wiki/ITK_FAQ
> >
> > Follow this link to subscribe/unsubscribe:
> > http://www.itk.org/mailman/listinfo/insight-users
> >
> _____________________________________
> Powered by www.kitware.com
> 
> Visit other Kitware open-source projects at
> http://www.kitware.com/opensource/opensource.html
> 
> Please keep messages on-topic and check the ITK FAQ at:
> http://www.itk.org/Wiki/ITK_FAQ
> 
> Follow this link to subscribe/unsubscribe:
> http://www.itk.org/mailman/listinfo/insight-users
> 