From documentation@opengroupware.org  Thu Dec  6 08:05:37 2007
From: documentation@opengroupware.org (Sebastian Reitenbach)
Date: Thu, 06 Dec 2007 09:05:37 +0100
Subject: [OGo-Documentation] developer documentation
Message-ID: <20071206080538.0119149C29@smtp.l00-bugdead-prods.de>

Hi,

as said, i'd start a bit developer documentation.


I'd also think, the document should start with an introductional chapter on 
debugging ogo using gdb. So with my little knowledge, I would suggest, 
starting there. When I have this, then I'd go on, explaining all the neat 
enhancements I've done over the past, the AsteriskDialer plugin, the 
AsteriskUI, some enhancements on the Chat-page in Misc, stuff like that.
For these modules, I thought, explaining each in one chapter, directory 
structure layout, GNUmakefiles, *plist files, and in the end how the 
objective-c and webobjects are working together to get the module used in 
the WebUI. 

While I was just fiddling around with the AsteriskDialer, I'd start with 
explaining how I added that piece.

But be warned, all my knowledge on how OGo is working internally, is just 
from reading docs and sources, asking here on the mailing lists, and making 
assumptions and guesses out of findings. So there will be errors and piece 
missing, that I just don't know (better).


Before that, some questions should be clarified:
* Just start with a *txt file, to get it fast working, or better from the 
beginning using a odf file?
* In case of *odf file, Adam, do you have an empty one, that you use for the 
admin and users docs, but with all the styles already in there? I'd suggest 
that these documents should look similar.

greetings
Sebastian


From documentation@opengroupware.org  Thu Dec  6 23:15:20 2007
From: documentation@opengroupware.org (Adam Tauno WIlliams)
Date: Thu, 06 Dec 2007 18:15:20 -0500
Subject: [OGo-Documentation] developer documentation
In-Reply-To: <20071206080538.0119149C29@smtp.l00-bugdead-prods.de>
References: <20071206080538.0119149C29@smtp.l00-bugdead-prods.de>
Message-ID: <1196982920.2969.5.camel@ws01.whitemice.org>

> I'd also think, the document should start with an introductional chapter on 
> debugging ogo using gdb. So with my little knowledge, I would suggest, 
> starting there. When I have this, then I'd go on, explaining all the neat 
> enhancements I've done over the past, the AsteriskDialer plugin, the 
> AsteriskUI, some enhancements on the Chat-page in Misc, stuff like that.
> For these modules, I thought, explaining each in one chapter, directory 
> structure layout, GNUmakefiles, *plist files, and in the end how the 
> objective-c and webobjects are working together to get the module used in 
> the WebUI. 

Doesn't sound bad;  I'd just make sure we don't start to create an
Objective-C developers guide, etc...  Narrow and focused is good
sticking to stuff that isn't already documented elsewhere.

> While I was just fiddling around with the AsteriskDialer, I'd start with 
> explaining how I added that piece.
> But be warned, all my knowledge on how OGo is working internally, is just 
> from reading docs and sources, asking here on the mailing lists, and making 
> assumptions and guesses out of findings. So there will be errors and piece 
> missing, that I just don't know (better).

Same here;  if there was documentation I would have read it. :)

> Before that, some questions should be clarified:
> * Just start with a *txt file, to get it fast working, or better from the 
> beginning using a odf file?

Certainly would work.  Text is easy enough to pull into anything.

> * In case of *odf file, Adam, do you have an empty one, that you use for the 
> admin and users docs, but with all the styles already in there? I'd suggest 
> that these documents should look similar.

I just use the default ones; if you link the document into an ODM the
styles are easy enough to change globally.  The most import thing is to
use headers 1 ,2, 3, etc... so you can automatically build a useful
table of contents.  Second is to keep a list of keep terms and the like
so it can be added to the index.


From documentation@opengroupware.org  Fri Dec  7 08:14:00 2007
From: documentation@opengroupware.org (Sebastian Reitenbach)
Date: Fri, 07 Dec 2007 09:14:00 +0100
Subject: [OGo-Documentation] developer documentation
Message-ID: <20071207081401.2484449DAE@smtp.l00-bugdead-prods.de>

documentation@opengroupware.org wrote: 
> > I'd also think, the document should start with an introductional chapter 
on 
> > debugging ogo using gdb. So with my little knowledge, I would suggest, 
> > starting there. When I have this, then I'd go on, explaining all the 
neat 
> > enhancements I've done over the past, the AsteriskDialer plugin, the 
> > AsteriskUI, some enhancements on the Chat-page in Misc, stuff like that.
> > For these modules, I thought, explaining each in one chapter, directory 
> > structure layout, GNUmakefiles, *plist files, and in the end how the 
> > objective-c and webobjects are working together to get the module used 
in 
> > the WebUI. 
> 
> Doesn't sound bad;  I'd just make sure we don't start to create an
> Objective-C developers guide, etc...  Narrow and focused is good
> sticking to stuff that isn't already documented elsewhere.
Yeah, I do not want to do that either ;) I'll only very shortly talk about 
the Makefiles, then point to the GNUstep documentation. So wherever I am 
aware of external documentation, I'll point to it.

> 
> > While I was just fiddling around with the AsteriskDialer, I'd start with 
> > explaining how I added that piece.
> > But be warned, all my knowledge on how OGo is working internally, is 
just 
> > from reading docs and sources, asking here on the mailing lists, and 
making 
> > assumptions and guesses out of findings. So there will be errors and 
piece 
> > missing, that I just don't know (better).
> 
> Same here;  if there was documentation I would have read it. :)
Hey, but now we are at least two, with hopefully a bit different knowledge 
about that all, and I hope there will be comments from Helge and others 
later on too, to fill in the missing pieces.

Do you are aware of any documentation, that explains the various *plist 
files, their contents, and especially its meaning?
Lots of guides that I find are for xcode, where it says click here n there, 
and in the end there is a plist file :( Where only that stupid point n click 
is explained, but not how to create these things correctly from scratch with 
just a text editor.

> 
> > Before that, some questions should be clarified:
> > * Just start with a *txt file, to get it fast working, or better from 
the 
> > beginning using a odf file?
> 
> Certainly would work.  Text is easy enough to pull into anything.
> 
> > * In case of *odf file, Adam, do you have an empty one, that you use for 
the 
> > admin and users docs, but with all the styles already in there? I'd 
suggest 
> > that these documents should look similar.
> 
> I just use the default ones; if you link the document into an ODM the
> styles are easy enough to change globally.  The most import thing is to
> use headers 1 ,2, 3, etc... so you can automatically build a useful
> table of contents.  Second is to keep a list of keep terms and the like
> so it can be added to the index.
> 
OK, as I'm not a seasoned office program user, I'll take a plain .txt file 
for the start, and keep a list of interesting things to index separate.

greetings
Sebastian


From documentation@opengroupware.org  Fri Dec  7 11:44:59 2007
From: documentation@opengroupware.org (Adam Tauno Williams)
Date: Fri, 07 Dec 2007 06:44:59 -0500
Subject: [OGo-Documentation] developer documentation
In-Reply-To: <20071207081401.2484449DAE@smtp.l00-bugdead-prods.de>
References: <20071207081401.2484449DAE@smtp.l00-bugdead-prods.de>
Message-ID: <1197027899.4807.13.camel@aleph.morrison.iserv.net>

> Do you are aware of any documentation, that explains the various *plist 
> files, their contents, and especially its meaning?

Wikipedia has an article about plist files (I think).  What is in WMOGAG
is the sum of my knowledge about plist files.  As far as developing
bundles are concerned I haven't been able to find anything at all about
the role of the plist files;  in some cases the purpose is fairly
obvious in other in probably lies buried in the NGBundleManager.

> Lots of guides that I find are for xcode, where it says click here n there, 
> and in the end there is a plist file :( Where only that stupid point n click 
> is explained, but not how to create these things correctly from scratch with 
> just a text editor.

Yep;  the Apple documentation is about the only documentation worth
mentioning when it comes to Objective-C stuff.  The GNUstep
documentation is almost worthless,  consisting mostly of empty bullet
points.


From documentation@opengroupware.org  Tue Dec 11 10:48:39 2007
From: documentation@opengroupware.org (documentation@opengroupware.org)
Date: Tue, 11 Dec 2007 11:48:39 +0100 (CET)
Subject: [OGo-Documentation] [Bug 1930] New: Important notes left out of Debian OGo ducumentation (patch provided)
Message-ID: <20071211104839.18CA17426F@bugzilla.opengroupware.org>

Please do not reply directly to this email. All additional
comments should be made in the comments box of this bug
report.

http://bugzilla.opengroupware.org/bugzilla/show_bug.cgi?id=1930

           Summary: Important notes left out of Debian OGo ducumentation
                    (patch provided)
           Product: Documentation
           Version: TRUNK
          Platform: PC
        OS/Version: other
            Status: NEW
          Severity: normal
          Priority: normal
         Component: General
        AssignedTo: chris123@magma.ca
        ReportedBy: pav5088@internode.on.net
         QAContact: je@skyrix.com
                CC: documentation@opengroupware.org


>From Bugzilla Helper:
User-Agent: Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.8.1.10) Gecko/20071115
Iceweasel/2.0.0.10 (Debian-2.0.0.10-0etch1)

Description of problem:
  There is no README.Debian file in OGo packaged for Debian.  Perhaps the
following text could be cut-and-pasted to create it (although it would be
preferable for the package to provide a dialog warning for #1 before installation) :

  There are three issues that need to be dealt with when installing OGo on
Debian Etch :

1)  The Etch "Apache" and "Postgres" virtual packages will install old versions
by default.  OGo depends on these virtual packages, so pre-install Apache2
and/or Postgresql-8 if these later versions are preferred.

2)  The rewrite and include modules need to be enabled in Apache for OGo to work.

3)  OGo should be enabled in the appropriate runlevels if OGo needs to run at
startup.

Version-Release number of selected component (if applicable):
TRUNK

How reproducible:
Always

Steps to Reproduce:
1.  Install OGo - no docs in /usr/share/doc/opengroupware
    

Additional info:

------- You are receiving this mail because: -------
You are on the CC list for the bug, or are watching someone who is.

From documentation@opengroupware.org  Sun Dec 16 16:16:42 2007
From: documentation@opengroupware.org (Sebastian Reitenbach)
Date: Sun, 16 Dec 2007 17:16:42 +0100
Subject: [OGo-Documentation] ogo debugging paramters
Message-ID: <20071216161643.457735A200@smtp.l00-bugdead-prods.de>

Hi,

To start some development documentation, I compiled a list of OGo Defaults 
that might be useful when it comes to debug OGo behavior. The Defaults are 
taken from the OGo Defaults list there in plone.

Where I felt able, I tried to explain them a bit, and added example 
debugging output. 

While just starting to write a bit about OGo in gdb, I came across an
explanation on the GNUstep site. So I only refer to there and talk about the 
WOUseWatchdog.

Both pages you can find here:
http://docs.opengroupware.org/Members/buzzdee/hacking%20ogo/debugging%20OGo/

This is work in progress, missing pieces, corrections, hints for additions 
are welcome.

Sebastian


From documentation@opengroupware.org  Mon Dec 17 07:13:37 2007
From: documentation@opengroupware.org (Sebastian Reitenbach)
Date: Mon, 17 Dec 2007 08:13:37 +0100
Subject: [OGo-Documentation] code documentation
Message-ID: <20071217071338.1CEF45A485@smtp.l00-bugdead-prods.de>

Hi,

I raised that topic a long time ago, but in the end, not much came out, as 
it not went into the source tree. So I'll try again raising the topic ;)

I'm going to try to write new development documentations, a bit more high 
level. While doing that, I have to wade through a lot of source files, 
figuring out, how things are working. 
E.g. after get the OGoAddressMapLink using a SkyExternalLink or sth. 
similar, I wanted to add a plone page, how to create and use OGoUIElements.

While doing that, I would add documentation comments to the source files, 
e.g. GSDoc, or doxygen?
Is there any kind of automatic code generation stuff used already, then I'd 
stick to that, if not, are there any preferences?

Well, GSDoc should be fine, as it is designed for GNUstep/Objective-c stuff, 
but e.g. doxygen might have more features,... (ok, don't know whether these 
more features are useful at all for the ogo docs)

If it could be agreed amongst the developers to a documentation system, and 
that automatic code documentation is sth. wanted, and that documentation 
comments in the code will be added to the source tree.

Also I don't think that it is important that the documentation is looking 
nice, and that the documentation system has lots of nifty features, I think 
that the important thing first is, that there is some code documentation at 
all, and it is easily usable.

any thoughts on that?

thanks 
Sebastian


From documentation@opengroupware.org  Mon Dec 17 12:41:01 2007
From: documentation@opengroupware.org (Adam Tauno Williams)
Date: Mon, 17 Dec 2007 07:41:01 -0500
Subject: [OGo-Documentation] code documentation
In-Reply-To: <20071217071338.1CEF45A485@smtp.l00-bugdead-prods.de>
References: <20071217071338.1CEF45A485@smtp.l00-bugdead-prods.de>
Message-ID: <1197895261.6346.45.camel@aleph.morrison.iserv.net>

> I'm going to try to write new development documentations, a bit more high 
> level. While doing that, I have to wade through a lot of source files, 
> figuring out, how things are working. 
> E.g. after get the OGoAddressMapLink using a SkyExternalLink or sth. 
> similar, I wanted to add a plone page, how to create and use OGoUIElements.
> While doing that, I would add documentation comments to the source files, 
> e.g. GSDoc, or doxygen?
> Is there any kind of automatic code generation stuff used already, then I'd 
> stick to that, if not, are there any preferences?
> Well, GSDoc should be fine, as it is designed for GNUstep/Objective-c stuff, 
> but e.g. doxygen might have more features,... (ok, don't know whether these 
> more features are useful at all for the ogo docs)

I'd prefer doxygen since it is widely known and available;  but don't
know how well it works with Objective-C.  If it can't recognize
categories or build cross reference tables allot of the value is lost.

I've never seen GSDoc in action and, personally, I'm hesitant about
GNU-Step stuff in general since maintenance seems to be almost entirely
absent and the documentation is complete trash (excepting Apple's stuff,
which seems to apply about 99.44% to the GNUStep classes).

> If it could be agreed amongst the developers to a documentation system, and 
> that automatic code documentation is sth. wanted, and that documentation 
> comments in the code will be added to the source tree.
> Also I don't think that it is important that the documentation is looking 
> nice, and that the documentation system has lots of nifty features, I think 
> that the important thing first is, that there is some code documentation at 
> all, and it is easily usable.
> any thoughts on that?

Yep.  No fancy features are required but if the automatic documentation
can't do much more than list methods and arguement lists it also isn't
worth much.

This is probably my biggest peeve with anything in Java,  people
generate Javadoc (or whatever it is properly called) and say: "see,
documentation".  To which my reaction is, "Gee, thanks, you listed all
the obvious stuff I can get from just glancing at the code anyway."

Probably the biggest issue I encounter as a part-time developer when
working inside complex applications is object life-cycle.  When does an
object get created, when can it be used [ for example a Gtk widget has
to be realized ], how long does the object last, etc...  The OGo page
cache is a good example.  Is a page object created, processed, and
disposed for each request or does it persist across requests, etc...
That kind of information is really important and requires a much deeper
of analysis of the code to discover.  Same is true with a ZideStore
bundle,  when is the bundle's object(s) created,  what is the purpose of
the bundle's main class, etc...


From documentation@opengroupware.org  Mon Dec 17 13:47:13 2007
From: documentation@opengroupware.org (Adam Tauno Williams)
Date: Mon, 17 Dec 2007 08:47:13 -0500
Subject: [OGo-Documentation] ogo debugging paramters
In-Reply-To: <20071216161643.457735A200@smtp.l00-bugdead-prods.de>
References: <20071216161643.457735A200@smtp.l00-bugdead-prods.de>
Message-ID: <1197899233.8605.1.camel@WM_ADAM1.morrison.iserv.net>

--=-qd8JtZSqWy/GIb71LBw5
Content-Type: text/plain
Content-Transfer-Encoding: quoted-printable

> Both pages you can find here:
> http://docs.opengroupware.org/Members/buzzdee/hacking%20ogo/debugging%20O=
Go/
> This is work in progress, missing pieces, corrections, hints for addition=
s=20
> are welcome.

WMOGAG's debugging section covers some of these defaults as well,  feel
free to cut-n-paste to augment your explanations of the defaults.


--=-qd8JtZSqWy/GIb71LBw5
Content-Type: application/pgp-signature; name=signature.asc
Content-Description: This is a digitally signed message part

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.4-svn0 (GNU/Linux)

iD4DBQBHZn3hLRePpNle04MRAor8AJdBEONCDZ8xCINz7XxQWzembV7uAJ99Vcp0
dxFGoUSQQitCCl69uOTiDQ==
=h3U3
-----END PGP SIGNATURE-----

--=-qd8JtZSqWy/GIb71LBw5--


From documentation@opengroupware.org  Mon Dec 17 13:58:18 2007
From: documentation@opengroupware.org (Helge Hess)
Date: Mon, 17 Dec 2007 14:58:18 +0100
Subject: [OGo-Documentation] code documentation
In-Reply-To: <20071217071338.1CEF45A485@smtp.l00-bugdead-prods.de>
References: <20071217071338.1CEF45A485@smtp.l00-bugdead-prods.de>
Message-ID: <672636F0-E9C7-4E41-B791-87D2B4A23AC5@opengroupware.org>

Hm,

I'm not sure whether its worth the effort. I dislike talking about  
thing being done before they are actually done, but at least I am  
shifting most OGo developments to JOPE/Java.

And while JOPE also lacks high-level documentation, the source code  
itself is now pretty well documented (I'm getting older too and need  
to document things to remember stuff myself ;-).

What this implies should be discussed on discuss, just wanted to raise  
the point that the existing codebase might be become important for  
starters in the future ;-)

Thanks,
   Helge

From documentation@opengroupware.org  Mon Dec 17 14:44:05 2007
From: documentation@opengroupware.org (Sebastian Reitenbach)
Date: Mon, 17 Dec 2007 15:44:05 +0100
Subject: [OGo-Documentation] ogo debugging paramters
Message-ID: <20071217144405.8FBE55A482@smtp.l00-bugdead-prods.de>

documentation@opengroupware.org wrote: 
> > Both pages you can find here:
> > 
http://docs.opengroupware.org/Members/buzzdee/hacking%20ogo/debugging%20OGo/
> > This is work in progress, missing pieces, corrections, hints for 
additions 
> > are welcome.
> 
> WMOGAG's debugging section covers some of these defaults as well,  feel
> free to cut-n-paste to augment your explanations of the defaults.
Good point, I'll extract missing pieces from there.

thanks
Sebastian


From documentation@opengroupware.org  Mon Dec 17 14:41:49 2007
From: documentation@opengroupware.org (Sebastian Reitenbach)
Date: Mon, 17 Dec 2007 15:41:49 +0100
Subject: [OGo-Documentation] code documentation
Message-ID: <20071217144152.A57C85A58B@smtp.l00-bugdead-prods.de>

Hi,

documentation@opengroupware.org wrote: 
> > I'm going to try to write new development documentations, a bit more 
high 
> > level. While doing that, I have to wade through a lot of source files, 
> > figuring out, how things are working. 
> > E.g. after get the OGoAddressMapLink using a SkyExternalLink or sth. 
> > similar, I wanted to add a plone page, how to create and use 
OGoUIElements.
> > While doing that, I would add documentation comments to the source 
files, 
> > e.g. GSDoc, or doxygen?
> > Is there any kind of automatic code generation stuff used already, then 
I'd 
> > stick to that, if not, are there any preferences?
> > Well, GSDoc should be fine, as it is designed for GNUstep/Objective-c 
stuff, 
> > but e.g. doxygen might have more features,... (ok, don't know whether 
these 
> > more features are useful at all for the ogo docs)
> 
> I'd prefer doxygen since it is widely known and available;  but don't
> know how well it works with Objective-C.  If it can't recognize
> categories or build cross reference tables allot of the value is lost.
When I go take a look into the gnustep-base sources, there it is full of 
GSDoc documentation. I think should find a good place in ogo sources, where 
I can add both, so that we can compare.

Is there a class that uses protocols, and categories and other objective-c 
stuff, that would be good for a test document to show all the features?
I'd take OpenGroupware+CTI.m or sth. like that, but there might be sth. 
better I am not aware of.

Then I'd document that using doxygen and gsdoc, and then lets see what both 
can do for us.
I never used gsdoc before. As I last tried to start that, I used doxygen, 
but that is a long time ago, and new features will be in there I think.
> 
> I've never seen GSDoc in action and, personally, I'm hesitant about
> GNU-Step stuff in general since maintenance seems to be almost entirely
> absent and the documentation is complete trash (excepting Apple's stuff,
> which seems to apply about 99.44% to the GNUStep classes).
yeah, but I think I've seen on the gnustep-ml, at least someone is working 
on manual pages.

> 
> > If it could be agreed amongst the developers to a documentation system, 
and 
> > that automatic code documentation is sth. wanted, and that documentation 
> > comments in the code will be added to the source tree.
> > Also I don't think that it is important that the documentation is 
looking 
> > nice, and that the documentation system has lots of nifty features, I 
think 
> > that the important thing first is, that there is some code documentation 
at 
> > all, and it is easily usable.
> > any thoughts on that?
> 
> Yep.  No fancy features are required but if the automatic documentation
> can't do much more than list methods and arguement lists it also isn't
> worth much.
> 
> This is probably my biggest peeve with anything in Java,  people
> generate Javadoc (or whatever it is properly called) and say: "see,
> documentation".  To which my reaction is, "Gee, thanks, you listed all
> the obvious stuff I can get from just glancing at the code anyway."
yeah, just a list is not worth that much, but some added details, what the 
inventor had in mind, when writing this method... just that would help.
Well, its a bit hard to document later, but we will see.

> 
> Probably the biggest issue I encounter as a part-time developer when
> working inside complex applications is object life-cycle.  When does an
> object get created, when can it be used [ for example a Gtk widget has
> to be realized ], how long does the object last, etc...  The OGo page
> cache is a good example.  Is a page object created, processed, and
The whole memory management is sth. that I also did not yet understood, 
besides the most basic things.

Maybe a good chapter for the developer docs ;).

> disposed for each request or does it persist across requests, etc...
> That kind of information is really important and requires a much deeper
> of analysis of the code to discover.  Same is true with a ZideStore
> bundle,  when is the bundle's object(s) created,  what is the purpose of
> the bundle's main class, etc...
yeah, the same things I am facing when trying to add things to the WebUI.
My hope is, that when I start that documenting, that at the end, all the 
small pieces will find together to the large picture.

cheers
Sebastian