Hi, since it was suggested to move this thread to d...@api I crosspost _this_ mail to d...@api and as a copy to d...@openoffice.org. Follow-ups to this thread should be directed to d...@api only.
Furthermore, since the discussion is continued in a new mailing list, I beg your pardon for using TOFU in this mail to put a summary (of what is mostly Juergens idea) at the beginning -- as I understand it. The DevGuide Wiki contains a lot of code to explain how to do things, but it almost always limits the code shown to some snippet. The whole picture is not given. In order to better support the DevGuide with examples, the following could be done (which is similar to http://wiki.services.openoffice.org/wiki/API/Samples/Java): From every code snippet in the DevGuide there is a link to a page which discusses the example (to which the snippet belongs) in greater detail. On this page one finds links to NetBeans, and/or Eclipse and/or other projects for this example. One may also add plain source code files. The idea is to later remove the SDK examples from the SDK and have them only in the Wiki. I may continue the discussion and add the following suggestions: (1) I would add a main page, listing all examples and linking each example to its page, where the example is discussed (see above). The main page should be referenced from the main page of the DevGuide Wiki (http://wiki.services.openoffice.org/wiki/Documentation/DevGuide/OpenOffice.org_Developers_Guide) If each examples page links back to (some of) the sections in the DevGuide, which link to the example, people would be able to start out from a runnable example and go from there to the DevGuide. Does this make sense? (2) I am not happy with the idea to wrap an example in an NetBeans (or other IDE) project and make this downloadable. First of all, there will be people (like myself) which may only want to read the code. It would be cumbersome if they had to download a project and import it into the IDE in order to just read a bit more of the code. Even more so, if they do not use this IDE at all. Or people may indeed want to build and run the code in their beloved IDE, but there is only a project for a different IDE. They would have to spend some effort to extract the source code from the project and move it to their IDE. And if there would be N projects for different IDEs, each containing the source code, the latter would be (highly) redundant. Even more so, if the source code would in addition be given plain-vanilla. Error might be fixed in one project but not in others. I think this problem can be solved, at least in parts: One could split the source code from the project and provide one archive file (zip) containing the plain-vanilla source-code and other archive files containing an IDE project _without_ the source code each. In order to build and run the example, one would have to download two archives and unpack them in the same place. This way one would have completely separated the source-code from the building environments. And if there is no project for ones own beloved IDE it would be more easy to create one and import the source code. This will not solve the problem with the redundancy between the plain-vanilla source code as archive file and a wiki page containing this source code as well -- at least as I understand the Wiki technology. Or is there a way to solve it? All examples I looked at contain only between one and three source code files. (3) Things always change and some examples will work only with particular OOo releases. So one could think about making the OOo release for which a particular example was created and with which it will run explicit, e.g. in the filenames of the archive files. Thus one could have more versions of one example, e.g., one which is only running with OOo 2.x and another one with is only running with OOo 3.x. Maybe this separation should already start at the page explaining the example in greater detail. I don't know how much and how fast things discussed in the DevGuide change, so I cannot judge whether this is an issue. I hope I didn't write too much. I am looking forward to any comments. -Karl Am Dienstag, 17. Februar 2009 16:25 schrieb Juergen Schmidt: > Karl Weber wrote: > > Hi Juergen, > > > > first of all, thanks for your long answer. Please find my reply below. > > > > Am Montag, 16. Februar 2009 22:25 schrieb Juergen Schmidt: > >> Hi Karl, > >> > >> let me describe what i have in mind ... > >> > >> First of all i would like to reduce the size of the SDK and i would like > >> to remove most of the examples. In case of the Java examples it > >> definitely makes sense to provide NetBeans or Eclipse projects because > >> it simplifies the whole stuff a lot (easy building and debugging through > >> the code). > >> > >> So the idea is to provide in a first step NB projects for the Java > >> examples of SDK (more or less done by Ariel -> many thanks again, > >> http://wiki.services.openoffice.org/wiki/API/Samples/Java) and document > >> them in the wiki. Well the wiki should explain the examples in general > >> and on potential subpages the specific details for NB or Eclipse > >> projects are explained. Ideally we will have the examples available not > >> only in Java but alos in C++ and Python. That means MS Visual Studio > >> projects, maybe XCode projects, etc. > >> > >> The DevGuide will still present related code snippets and of course > >> should provide links to the main example wiki page. Java as the > >> preferred example language should remain in the DevGuide. But as > >> mentioned before we would ideally have the examples in different > >> languages available. > >> > >> Users can easy checkout the example sources from the code repository and > >> can use them in there preferred IDE. Currently they can be easy > >> downloaded as zips. > >> > >> The advantage of this approach is that we can reach more potential > >> users. And of course advanced users can easier help to improve the > >> examples, fix problems etc. > >> > >> It's still a lot of work to provide good example that are well > >> documented ... > >> > >> Often the developers don't focus on developer documentation and > >> examples. But we need it and it is a good opportunity for new developers > >> to get started. Working on examples, understanding the concepts and help > >> others to understand what they have learned etc. > >> > >> Later on the next step to work on or with the real office code should > >> become easier... > >> > >> Juergen > > > > Hmm, may be it is too late already, but I do not quite understand your > > idea. So let me try to express it in my words: > > > > (1) The DevGuide, in particular with respect to presenting only code > > snippets in Java, should remain as it is. > > > > (2) Boxes with code snippets in the DevGuide should have a link to the > > one(!) main examples page. So, starting from a code snippet in the > > DevGuide I click one link to get to the main examples page. > > no, not a main example page of all examples. A main page for the > specific example where the snippet is from. In the old DevGuide we had > the links to the Java files in the SDK because the DevGuide came with > the SDK. > > > (3) The main examples page contains a list of all examples available. On > > this page I can click on another link to get to another page that > > discusses the particular example in Java (or any other language) which > > contains the code snippet from (1), where I started. (One page for every > > example or even one page for every example _and_ every language?) From > > this page, I can again navigate to other pages, giving me particulars > > about the project files for NB or Eclipse or, ... On these pages I might > > also find links to download the project files for the particular example > > for the respective IDE. > > no, the example page should explain the example in more detail and you > will find links to NB or Eclipse or whatever IDE projects to simply the > usage if you want. > > We can also add links to the plain source files, either on this example > page or in DevGuide directly. > > Juergen > > PS: i agree to Ariel that we should move further discussion to d...@api > > > If this is what you mean, where do I find the code? My idea was to start > > from (1) and find a link to a page where I can read the code on-line. A > > very good example about what I have in mind is [1]. > > > > When I learn something like UNO I don't have to build and run every > > example. Very often it is enough to just read the code. So it would be > > great if I could read it by just clicking some links -- refer to [1] > > again. > > > > It would be cumbersome, if I had to download the example and install the > > project in an IDE in order to just read the code. Even worse, what if I > > don't use NB, and don't want to use it? If the examples are available > > only as NB projects, chances are high, that I will not only get > > frustrated, but that I will loose interest. > > > > O.K., my idea will not work for BASIC examples with dialogs. These > > examples I will have to download and open with OOo. > > > > To summarise: > > > > (a) It is not clear to me, whether your idea will incorporate the > > possibility to read code on-line or not. > > > > (b) How many pages should there be for every example (see question > > above)? > > > > -Karl > > > > [1] > > https://developer.mozilla.org/en/Viewing_and_searching_Mozilla_source_cod > >e_online > > > > > > --------------------------------------------------------------------- > > To unsubscribe, e-mail: dev-unsubscr...@openoffice.org > > For additional commands, e-mail: dev-h...@openoffice.org > > --------------------------------------------------------------------- > To unsubscribe, e-mail: dev-unsubscr...@openoffice.org > For additional commands, e-mail: dev-h...@openoffice.org --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@openoffice.org For additional commands, e-mail: dev-h...@openoffice.org
