Karl Weber wrote:
Sorry, but I have to resend this mail since my subscription wasn't complete
before....
Hi,
since it was suggested to move this thread to d...@api I crosspost _this_ mail
to d...@api and as a copy to [email protected]. 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.o
rg_Developers_Guide)
mmh, i think that is partly done with dynamic page lists. We can add a
new category for DevGuide examples if necessary. And of course we can
link it from the DevGuide but that should be done from every single code
snippet
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?
well that is one of the main ideas, link back into the DevGuide to get
more context info. The same as from the API reference.
(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.
i agree that we should think about a clever structure to have the source
code only ones. But that should possible.
But having specific IDE projects would simplify the work with the
examples a lot. As i mentioned before we can add links to the source
code repository as well. But in case of extension i would always prefer
a nice IDE project that does all the packaging for me and allows me to
easy step through an example when it is deployed in the office. I can
use such a project and can customize it for my own purpose ...
Maybe it's fine for you to read only the source code and in this case a
link to the repository is fine. But for many others i am sure that the
IDE projects will be appreciated.
And of course the work needs to be done. I will focus on NB for example
and if others would like to contribute Eclipse or other project thats
fine. Just do it.
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.
well in case of Java you often have project import features from other
IDEs. From my point of view a minor issue. It becomes more difficult
when the office specific stuff comes into the game.
I would always prefer the easiest way for new developers to get started.
And i think that is at the moment NB with our office plugin.
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.
yes that would be possible but i see a maintenance problem. For me it
would be ok that the examples work with the current release. And until
we change our compatibility statement the examples should work always
;-) (please no discussion about the compatibility here, that will be
addressed in some way ...)
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.
no, i think it's good to see that people think about improvements.
Juergen
-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: [email protected]
For additional commands, e-mail: [email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
-------------------------------------------------------
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
