Allen Bierbaum wrote: > Marcus Lindblom wrote: > >> Allen Bierbaum wrote: >> >> >>> So you want to pull the examples inline into the class docs? Or could >>> we just do something like Qt where we refer to the full applications. >>> Doxygen would even let use have the code for that full application >>> example be syntax highlighted with links back to the documentation of >>> the classes and methods being used. >>> >>> I guess I would rather see full examples that show how to fully use the >>> system, then see trivial examples that still sound like tutorials to me. >>> >>> >> I think Dirk's writing on the wiki sums up my opinion pretty good as >> well, and they don't really agree with your point here. We need to >> settle on concepts and names. What we have is: >> >> Examples: 5-10 lines of code, preferrably inline in the class dox. >> Perhaps referenced to from a larger 'tutorial document'? >> >> > To me this is not much of an example. It is just a code snippet. It > doesn't really show the capabilities IMHO. I would prefer to just link > from the classes to more extensive examples. See my comments on the wiki.
Ok. So you want a step beyong a 'snippet'? I think snippets/'small examples' are pretty good to have though, so I'd like to keep them in. >> Tutorials: small but complete executables that larger concepts (like >> your "full examples" above), with small data. Usually less than a meg. >> Source could be referenced to from class dox. >> >> > I think of tutorials as showing a single concept for the purposes of > teaching. I don't get the difference between this and what you think is a 'more extensive example' in the previous pararaph? .. is it just in the way it is commented/documented? >> Demos: large applications, potentially tens of megabytes of data. >> Referring from class dox to the source of these is not necessary, IMHO. >> I..e mentioning in FBOViewport class that 'SurfaceScatterRhubarbPieDemo' >> extensively uses it is sufficient. Linking to the actual source is not, >> as there should be an example and a preferrably a small tutorial as well. >> >> > Agreed. > >> I think the divisions into the three concepts are pretty sound. Do you >> think we need something not covered here? Do you have good reasons to >> change the names we will use for these concepts? Do you have better >> names? For sure, a tutorial could be used to 'demonstrate' a concept or >> so. It would just not be branded as a 'demo' (hrm... ;). >> >> > The big thing I see missing is a consensus on examples and the fallout > from that. If examples end up being small pieces of code then we have > lost 2 major things that we need IMHO. > > 1. Marketing demonstrations of new features. I know I have harped on > this a lot, but it is vitally important. OpenSG has no marketing, zero, > nada. We have tons of features and new ones all the time but nothing to > demonstrate them. I want something in the standard build that shows > these capabilities so when someone adds feature X, the very next day we > can go to opengl.org and announce "OpenSG adds feature X, download the > nightly from here and run Xexample." Don't the tutorials that we have to day to a decent job at that? They are prebuilt and all, at least in the 1.6.0-release for windows. Do we just need to include them in the nightly? Or add more of them making sure each feature is covered? > 2. Examples for people to base real applications and that show real > usage. snipets and tutorials only show a very simple way of using most > code. In a "real" application it normally has to handle more issues and > deal with more cases. We need applications like this for people to base > their applications and look to for "examples" of using the code. > > Take a look at the examples directory in the OpenSceneGraph dist. It is > exactly the type of thing I think we need for examples. They have 81 > examples of simple applications showing off and using the capabilities > of OSG. This is what OpenSG needs. *surf* *dl* *inspect*. The OpenSG tutorials directory today has exactly that. Small applications of a single 5-20k source file. What am I missing? > If we still need little 5-10 line code snipets, that is fine, but I > suggest making them part of something besides examples. Really > something like that may be part of the unit tests. In my mind snippets are meant to go into docs to explain how to invoke a certain feature. Imagine creating a beacon for a camera, adding a materialchunk to a chunkmaterial, etc. They are not executable applications/tests as such. >> I'm all for settling on different namings, if there are better >> alternatives. Half of design is defining concepts and defining names for >> said concepts, the rest is just trying not to confuse the two. ;-) >> >> > Agreed. Let's hash it out on the mailing list and then update the wiki > with the definitions we agree upon. Yeah. It's _on_. ;) Cheers, /Marcus ------------------------------------------------------------------------- Take Surveys. Earn Cash. Influence the Future of IT Join SourceForge.net's Techsay panel and you'll get the chance to share your opinions on IT & business topics through brief surveys -- and earn cash http://www.techsay.com/default.php?page=join.php&p=sourceforge&CID=DEVDEV _______________________________________________ Opensg-users mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/opensg-users
