Re: [Lazarus] Lazarus Digest, Vol 99, Issue 32

[Marco van de Voort]

On Fri, Apr 15, 2016 at 03:37:37PM +0200, Michael Schnell wrote:
> On 04/15/2016 03:29 PM, Marco van de Voort wrote:
> >> As said: I (unsuccessfully) tried.
> > So you can't operate a text editor?
> >
> I unsuccessfully tried to create an environment that lets me see the 
> modified help text (we already did discuss this some years ago).

True, but that is not the same as not being able to contribute.

You can submit the textual patch just fine.

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Lazarus Digest, Vol 99, Issue 32

[Jürgen Hestermann]

Am 2016-04-18 um 12:53 schrieb Michael Schnell:

On 04/18/2016 12:40 PM, Ondrej Pokorny wrote:


No, the equation includes everything along with everybody's interests.

Example:
You spend X hours to write documentation for A that saves Y hours to Z users 
that otherwise had to study the code.
Then you can compare X to Y*Z.


That was my initial proposal leading to "extremely hard to define", as (due to 
no intended and hence measurable revenue) the developers don't have any idea about the 
count of users and the effort they need to get their work done.

As an extreme you would say: no documentation at all is best, as that means no 
hours to create it and there supposedly will be at least a single user who is 
able to make some small benefit from the project and hence the positive ratio 
is infinite .


It's not the ratio (quotient) that is of relevance here but the difference.

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Lazarus Digest, Vol 99, Issue 32

[Ondrej Pokorny]

On 18.04.2016 12:53, Michael Schnell wrote:

On 04/18/2016 12:40 PM, Ondrej Pokorny wrote:


No, the equation includes everything along with everybody's interests.

Example:
You spend X hours to write documentation for A that saves Y hours to 
Z users that otherwise had to study the code.

Then you can compare X to Y*Z.


That was my initial proposal leading to "extremely hard to define", as 
(due to no intended and hence measurable revenue) the developers don't 
have any idea about the count of users and the effort they need to get 
their work done.


You use the word /define/ wrongly. Please see 
https://en.wikipedia.org/wiki/Definition . Florian gave you the exact 
definition.

You probably meant it is hard to /estimate/ the unknown parameters.

Furthermore, it is wrong that a user can judge better than a developer. 
The quality of a judgement doesn't depend on the role of the person.



As an extreme you would say: no documentation at all is best, as that 
means no hours to create it and there supposedly will be at least a 
single user who is able to make some small benefit from the project 
and hence the positive ratio is infinite .


No, you are wrong. The "resulting benefit" is not taken into 
consideration. You compare the times you need to get to the "resulting 
benefit" once without the work X (in my example "without documentation") 
and once with the work X (in my example "with documentation").


Ondrej
--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Lazarus Digest, Vol 99, Issue 32

[Lukasz Sokol]

On 18/04/16 11:53, Michael Schnell wrote:
> On 04/18/2016 12:40 PM, Ondrej Pokorny wrote:
>> 
>> No, the equation includes everything along with everybody's
>> interests.
>> 
>> Example: You spend X hours to write documentation for A that saves
>> Y hours to Z users that otherwise had to study the code. Then you
>> can compare X to Y*Z.
> 
> That was my initial proposal leading to "extremely hard to define",
> as (due to no intended and hence measurable revenue) the developers
> don't have any idea about the count of users and the effort they need
> to get their work done.
> 
> As an extreme you would say: no documentation at all is best, as that
> means no hours to create it and there supposedly will be at least a
> single user who is able to make some small benefit from the project
> and hence the positive ratio is infinite .
> 

This only is right, if the user who decides to invest in writing documentation, 
only writes it, and then uses it once, and then doesn't care any more.

Which I'd say, is /hardly ever/ the case ?

Same with the readers of the docs, 
can you remember EVERY content of EVERY doc you ever read, every time you wish 
to use 
the knowledge contained therein ? 

You have a chance of remembering by heart what you read, at least '7' times, if 
you wrote it
yourself 

(7 is just arbitrary number here; although not far from reality of creating 
'written works',
that I read of having at least 8 revisions before considered stable & good 
style ), 

while consumers of the docs need to read them more times to remember.

-L.

> -Michael
> 


--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Lazarus Digest, Vol 99, Issue 32

[Michael Schnell]

On 04/18/2016 12:40 PM, Ondrej Pokorny wrote:


No, the equation includes everything along with everybody's interests.

Example:
You spend X hours to write documentation for A that saves Y hours to Z 
users that otherwise had to study the code.

Then you can compare X to Y*Z.


That was my initial proposal leading to "extremely hard to define", as 
(due to no intended and hence measurable revenue) the developers don't 
have any idea about the count of users and the effort they need to get 
their work done.


As an extreme you would say: no documentation at all is best, as that 
means no hours to create it and there supposedly will be at least a 
single user who is able to make some small benefit from the project and 
hence the positive ratio is infinite .


-Michael

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Lazarus Digest, Vol 99, Issue 32

[Ondrej Pokorny]

On 18.04.2016 12:27, Michael Schnell wrote:

On 04/15/2016 08:50 PM, Florian Klämpfl wrote:
It is very very simple for a non-profit/OSS project: more man hours 
earned back than those which were invested.


that would completely ignore the interest of the users of the project. 
(Which in commercial projects can be measured in the revenue.)


No, the equation includes everything along with everybody's interests.

Example:
You spend X hours to write documentation for A that saves Y hours to Z 
users that otherwise had to study the code.

Then you can compare X to Y*Z.


On 18.04.2016 12:27, Michael Schnell wrote:

So not a friendly attitude at all.


No. You seem to have misunderstood Florian's statement ;)

Ondrej

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Lazarus Digest, Vol 99, Issue 32

[Michael Schnell]

On 04/15/2016 08:50 PM, Florian Klämpfl wrote:
It is very very simple for a non-profit/OSS project: more man hours 
earned back than those which were invested.


that would completely ignore the interest of the users of the project. 
(Which in commercial projects can be measured in the revenue.)


So not a friendly attitude at all.

-Michael

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Lazarus Digest, Vol 99, Issue 32

[Florian Klämpfl]

Am 15.04.2016 um 15:39 schrieb Michael Schnell:
> On 04/15/2016 03:30 PM, Marco van de Voort wrote:
>> And an investment in manhours to make that happen that IMHO will never be 
>> earned back.
> I can't contradict.
> 
> But in fact "earned back" is extremely hard to define when comparing two far 
> distant edges of a
> non-profit project.

It is very very simple for a non-profit/OSS project: more man hours earned back 
than those which
were invested.


--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Lazarus Digest, Vol 99, Issue 32

[Michael Schnell]

On 04/15/2016 03:30 PM, Marco van de Voort wrote:
And an investment in manhours to make that happen that IMHO will never 
be earned back.

I can't contradict.

But in fact "earned back" is extremely hard to define when comparing two 
far distant edges of a non-profit project.


-Michael


--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Lazarus Digest, Vol 99, Issue 32

[Michael Schnell]

On 04/15/2016 03:29 PM, Marco van de Voort wrote:

As said: I (unsuccessfully) tried.

So you can't operate a text editor?

I unsuccessfully tried to create an environment that lets me see the 
modified help text (we already did discuss this some years ago).


AFAIR, I did send (you ?) a modified help text for "CheckSynchronize()" 
(in fact a "patch" as it was the complete small chapter). (Of course 
this was not for the Lazarus help files, but RTL.)


Maybe it now is included.

-Michael

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Lazarus Digest, Vol 99, Issue 32

[Marco van de Voort]

On Tue, Apr 12, 2016 at 10:01:26AM +0200, Michael Schnell wrote:
> On 04/11/2016 09:28 PM, Marco van de Voort wrote:
> > It is the conjecture that the content will actually improve because of it
> > that I find highly doubtful.
> >
> Absolutely agreed ! An unmanaged Wiki would be highly dangerous. A 
> complete managing system on top of the standard Wiki software would be 
> required.

And an investment in manhours to make that happen that IMHO will never be
earned back.

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Lazarus Digest, Vol 99, Issue 32

[Marco van de Voort]

On Tue, Apr 12, 2016 at 10:02:56AM +0200, Michael Schnell wrote:
> On 04/11/2016 09:34 PM, Marco van de Voort wrote:
> >> Maybe you do remember that (with your help) I once tried to contribute
> >> to the fpc help.
> > Sorry, can't remember any patches, so it can't have been too serious!
> >
> As said: I (unsuccessfully) tried.

So you can't operate a text editor? 

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Lazarus Digest, Vol 99, Issue 32

[Salvatore Coppola]

2016-04-09 12:20 GMT+02:00 Giuliano Colla :

> Il 08/04/2016 21:13, Juha Manninen ha scritto:
>
>> Welcome to open source.
>> Instead of complaining here and wasting everybody's time, you could
>> have improved the documentation yourself and provide a patch.
>>
>
> In principle you're right. However you should take into account some other
> factors.
>
> Frequently users do complain when a problem arises which they are unable
> to solve by themselves.
>
> Asking them to provide a patch doesn't help too much.


Sorry to reply so late but here you have hit the core of the question. Many
times I've tried to do something that failed in a miserable way (i.e.
miserable/hobbist/old programmer). BTW, contribute to an open source
project can be done as programmer, tester, artist, disigner, marketter etc.
So if someone has a good idea to improve the project but is not able to
implement it, I think there is nothing wrong with proposing it here without
this being interpreted as a request that the core developers must do. If
anyone knows how to do it, and overall want to do it, well, otherwise it
goes on and nothing changes. Anyway I want to say thanks to all of you, old
and new developers
Salvatore


> Giuliano
>
>
>
> --
> ___
> Lazarus mailing list
> Lazarus@lists.lazarus.freepascal.org
> http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
>
--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Lazarus Digest, Vol 99, Issue 32

[Michael Schnell]

On 04/11/2016 09:34 PM, Marco van de Voort wrote:

Maybe you do remember that (with your help) I once tried to contribute
to the fpc help.

Sorry, can't remember any patches, so it can't have been too serious!


As said: I (unsuccessfully) tried.

-Michael

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Lazarus Digest, Vol 99, Issue 32

[Michael Schnell]

On 04/11/2016 09:28 PM, Marco van de Voort wrote:

It is the conjecture that the content will actually improve because of it
that I find highly doubtful.

Absolutely agreed ! An unmanaged Wiki would be highly dangerous. A 
complete managing system on top of the standard Wiki software would be 
required.


-Michael


--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Lazarus Digest, Vol 99, Issue 32

[Marco van de Voort]

On Mon, Apr 11, 2016 at 01:00:46PM +0200, Michael Schnell wrote:
> On 04/11/2016 12:30 PM, Graeme Geldenhuys wrote:
> > What's so hard about this:
> 
> Maybe you do remember that (with your help) I once tried to contribute 
> to the fpc help.

Sorry, can't remember any patches, so it can't have been too serious!

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Lazarus Digest, Vol 99, Issue 32

[Marco van de Voort]

On Mon, Apr 11, 2016 at 01:28:40PM +0200, Mattias Gaertner wrote:
> > 
> > Uh? I don't believe that anybody takes a patch from Mantis and applies
> > it blindly without actually looking at the patch. If they do, that is
> > very sad news for the Lazarus project.
> 
> No one is applying blindly patches and no one adds stuff blindly to the
> wiki.  I meant that the developers are humans.  They are not experts on
> all topics.  Buggy patches has been applied.  The more people look over it
> the better.

True.

>  This is true for both fpdoc and wiki.

No. Wiki has patches applied without any kind of post-commit filter. So
fpdoc is first order (at worst), and wiki 0th order (at best).

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Lazarus Digest, Vol 99, Issue 32

[Marco van de Voort]

On Mon, Apr 11, 2016 at 11:59:39AM +0200, Michael Schnell wrote:
> On 04/11/2016 11:26 AM, Graeme Geldenhuys wrote:
> > Wiki's are only good for knowledge base - adding random thoughts as 
> > pages - loosely linked together by cross-links. It is terrible as a 
> > help format/medium.
> 
> While I do see your point I can't think of any other authoring system 
> that might be able to allow for possible volunteers to do contributions 
> (as has been the wish of some previous posters).

Nobody disputes that. If you want to sacrifice content to easy access on
principle, then that would definitely be the way to go.

It is the conjecture that the content will actually improve because of it
that I find highly doubtful.

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Lazarus Digest, Vol 99, Issue 32

[Graeme Geldenhuys]

On 2016-04-11 12:49, Michael Schnell wrote:
> OSX is based on BSD,
> 
> So maybe this is not really  Volunteer driven :-)

Apple had nothing to do with it. FreeBSD's documentation existed long
before OSX saw the light of day.

Regards,
  - Graeme -


--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Lazarus Digest, Vol 99, Issue 32

[Michael Schnell]

On 04/11/2016 01:37 PM, Graeme Geldenhuys wrote:

FreeBSD has.

OSX is based on BSD,

So maybe this is not really  Volunteer driven :-)

-Michael

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Lazarus Digest, Vol 99, Issue 32

[Graeme Geldenhuys]

On 2016-04-11 12:19, Michael Schnell wrote:
> Anyway: just dreaming. Volunteer driven systems never get there.

FreeBSD has. So there is hope for others. ;-)
FreeBSD's documentation is impressive and complete. Not only do they
have very extensive "handbook" documentation in different languages,
they have published books detailing the intricate details of the OS
kernel, file system, boot process etc.

Regards,
  - Graeme -


--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Lazarus Digest, Vol 99, Issue 32

[Mattias Gaertner]

On Mon, 11 Apr 2016 11:56:38 +0100
Graeme Geldenhuys  wrote:

> On 2016-04-11 11:50, Mattias Gaertner wrote:
> >> > Currently with the wiki, rubbish can be added and no review is done! 
> > You could say the same for the fpdoc files.
> 
> Uh? I don't believe that anybody takes a patch from Mantis and applies
> it blindly without actually looking at the patch. If they do, that is
> very sad news for the Lazarus project.

No one is applying blindly patches and no one adds stuff blindly to the
wiki. 
I meant that the developers are humans. They are not experts on all
topics. Buggy patches has been applied.
The more people look over it the better. This is true for both fpdoc
and wiki.
 
> Patches via Mantis has infinitely more chance of being reviewed (at
> minimum glanced over once by a trusted expert) than the 10's or 100's of
> changes made in the Wiki every day.

I doubt these numbers. Especially since infinitely is not a number. ;)

Mattias

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Lazarus Digest, Vol 99, Issue 32

[Michael Schnell]

On 04/11/2016 01:12 PM, Graeme Geldenhuys wrote:

... and we are talking about Lazarus documentation here


Of course at this location we are.

But a documentation decently usable by the Lazarus "customer" needs to 
cover  (at least) IDE, LCL, the language, the compiler, RTL, and the 
most common packages.


Anyway: just dreaming. Volunteer driven systems never get there.

-Michael

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Lazarus Digest, Vol 99, Issue 32

[Graeme Geldenhuys]

On 2016-04-11 12:00, Michael Schnell wrote:
> 
> Maybe you do remember that (with your help) I once tried to contribute 
> to the fpc help.

1) If you can type, you can contribute.

2) The other thing you need to know:
 http://wiki.freepascal.org/Creating_A_Patch

That's it!


> mail, maybe it had been included in the next release of the fpc help (at 
> least a year later).

FPC documentation is timed with FPC releases. So that only happens one a
year at best. So obviously you will not see updates sooner. The Lazarus
project releases much more often, and we are talking about Lazarus
documentation here.



Regards,
  - Graeme -

-- 
fpGUI Toolkit - a cross-platform GUI toolkit using Free Pascal
http://fpgui.sourceforge.net/

My public PGP key:  http://tinyurl.com/graeme-pgp

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Lazarus Digest, Vol 99, Issue 32

[Michael Schnell]

On 04/11/2016 12:30 PM, Graeme Geldenhuys wrote:

What's so hard about this:


Maybe you do remember that (with your help) I once tried to contribute 
to the fpc help.


I failed to do this in a decent way (I finally sent in the text per 
mail, maybe it had been included in the next release of the fpc help (at 
least a year later). I id not dare to check.


I'm not going to try to contribute to the help until I'm retired (which 
is not that far away ;-) ).


-Michael

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Lazarus Digest, Vol 99, Issue 32

[Graeme Geldenhuys]

On 2016-04-11 11:50, Mattias Gaertner wrote:
>> > Currently with the wiki, rubbish can be added and no review is done! 
> You could say the same for the fpdoc files.

Uh? I don't believe that anybody takes a patch from Mantis and applies
it blindly without actually looking at the patch. If they do, that is
very sad news for the Lazarus project.

Patches via Mantis has infinitely more chance of being reviewed (at
minimum glanced over once by a trusted expert) than the 10's or 100's of
changes made in the Wiki every day.

Regards,
  - Graeme -

-- 
fpGUI Toolkit - a cross-platform GUI toolkit using Free Pascal
http://fpgui.sourceforge.net/

My public PGP key:  http://tinyurl.com/graeme-pgp

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Lazarus Digest, Vol 99, Issue 32

[Michael Schnell]

On 04/11/2016 12:18 PM, Graeme Geldenhuys wrote:

Currently with the wiki, rubbish can be added and no review is done! The
wiki is the best of the worst.
Of course (and as I said) the wiki for the help needs to be managed. The 
writer needs to see what he did (at best integrated in the help view of 
his local IDE), but for others to see (i.e. a release) one of the 
"powers" need to review it .


Of course the standard Wiki software does not provide the necessary 
features (such as only "personal" update until review/release, enforcing 
certain rules for providing decent conversion to the target help text 
formats.


That is why I said: a lot of work.

No it does not make much sense to discuss this here, unless somebody 
with a lot of spare time stands up and says "I'll take it on" ;-) .


- Michael

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Lazarus Digest, Vol 99, Issue 32

[Mattias Gaertner]

On Mon, 11 Apr 2016 11:18:25 +0100
Graeme Geldenhuys  wrote:

>[...]
> Currently with the wiki, rubbish can be added and no review is done! 

You could say the same for the fpdoc files.

IMO review means someone else reads it and reports/fixes errors. This is
done for both though in different form.
The Wiki has a problem with spammers though.

Mattias

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Lazarus Digest, Vol 99, Issue 32

[Graeme Geldenhuys]

On 2016-04-11 11:04, Michael Schnell wrote:
> Unless 
> you go a very hard way to be able to compile the complete help system

What's so hard about this:

  fpdoc --project=lcl-docs-project.xml --format=html
or
  fpdoc --project=lcl-docs-project.xml --format=chm
or
  fpdoc --project=lcl-docs-project.xml --format=ipf
or
  fpdoc --project=lcl-docs-project.xml --format=rtf


You don't need all those *.sh or *.bat scripts, makefiles or custom
console tools any more. FPDoc has made it dead simple to generate
documentation with the help of a fpdoc project file. Project file
support has been around since FPC 2.6.2 or 2.6.4 - not sure which.

[...few seconds later...]

To my surprise, it seems Lazarus doesn't include a fpdoc project file
for LCL. I'm happy to contribute mine. I'll submit it to Mantis now. In
fact I see the http://fpgui.sourceforge.net/

My public PGP key:  http://tinyurl.com/graeme-pgp

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Lazarus Digest, Vol 99, Issue 32

[Graeme Geldenhuys]

On 2016-04-11 10:59, Michael Schnell wrote:
> that might be able to allow for possible volunteers to do contributions 

As Mattias mentioned, Lazarus IDE even includes a fpdoc editor built-in.
You can't get easier than that! You don't even have to leave the IDE.
Then simply generated a patch and post it to Mantis (like all other
contributions).

Somebody will review the patch and apply it as soon as possible. At
least that way the documentation gets a review and can be rejected if
there are mistakes.

Currently with the wiki, rubbish can be added and no review is done! The
wiki is the best of the worst.

Regards,
  - Graeme -

-- 
fpGUI Toolkit - a cross-platform GUI toolkit using Free Pascal
http://fpgui.sourceforge.net/

My public PGP key:  http://tinyurl.com/graeme-pgp

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Lazarus Digest, Vol 99, Issue 32

[Michael Schnell]

On 04/11/2016 11:26 AM, Graeme Geldenhuys wrote:


Yes, it's called "fpdoc" and have been around for years!


Of course I do know this.

I did play with it.

Its a kind of "Write only memory": you don't see what you did. (Unless 
you go a very hard way to be able to compile the complete help system on 
your local PC.)


It's a perfect means to shy away any volunteers.

-Michael



--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Lazarus Digest, Vol 99, Issue 32

[Michael Schnell]

On 04/11/2016 11:26 AM, Graeme Geldenhuys wrote:
Wiki's are only good for knowledge base - adding random thoughts as 
pages - loosely linked together by cross-links. It is terrible as a 
help format/medium.


While I do see your point I can't think of any other authoring system 
that might be able to allow for possible volunteers to do contributions 
(as has been the wish of some previous posters).


Of course strict rules would be needed to be defined and (at best 
automatically) be enforces to allow Wiki pages to (automatically) be 
converted to help content. That is why it's obvious that setting up such 
a system would be a lot of work and would bind a lot of manpower for a 
decent amount of time. So supposedly no chance. :-( .


-Michael

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Lazarus Digest, Vol 99, Issue 32

[Mattias Gaertner]

On Mon, 11 Apr 2016 10:26:40 +0100
Graeme Geldenhuys  wrote:

>[...]
> Yes, it's called "fpdoc" and have been around for years! It takes a
> minute or two to generate your own help in whatever format you prefer -
> HTML, CHM, INF, TXT etc. Users can contribute by supplying documentation
> patches. It also solves all the above mentioned wiki problems.

There is a simple fpdoc editor built-in the IDE for identifiers
(View / FPDoc Editor). It allows even lazy programmers to easily add
a sentence about an identifier. Just place the source editor cursor on
an identifier, write a short explanation in the fpdoc editor - done.
It also allows to create fpdoc entries for your own projects/packages
with a simple click.

For topics and examples you can use LazDE.

See here:

http://wiki.freepascal.org/FPDoc_Editor

Mattias

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Lazarus Digest, Vol 99, Issue 32

[Graeme Geldenhuys]

On 2016-04-11 09:11, Michael Schnell wrote:
> (e.g. by using a single managed Wiki exclusively as the root 
> of the articles)

Wiki's are only good for knowledge base - adding random thoughts as
pages - loosely linked together by cross-links. It is terrible as a help
format/medium.

The other problem with the wiki. Too many hands in the pot and no
control of who edits what. So somebody could add rubbish or inaccurate
information, and the next person will read that thinking it is correct.

Also there is no wiki help per Lazarus release. eg: Can I see the wiki
help for when Lazarus v1.0 was released? NO!


> is open for volunteers to provide fixes and additions 
> and actually see "live" what they did without waiting for the next 
> Lazarus release.

Yes, it's called "fpdoc" and have been around for years! It takes a
minute or two to generate your own help in whatever format you prefer -
HTML, CHM, INF, TXT etc. Users can contribute by supplying documentation
patches. It also solves all the above mentioned wiki problems.



Regards,
  - Graeme -

-- 
fpGUI Toolkit - a cross-platform GUI toolkit using Free Pascal
http://fpgui.sourceforge.net/

My public PGP key:  http://tinyurl.com/graeme-pgp

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Lazarus Digest, Vol 99, Issue 32

[Michael Schnell]

On 04/09/2016 04:07 PM, Giuliano Colla wrote:


Because without a minimal amount of documentation all this valuable 
work risks to be useless, because:

- nobody except a few core developers know of its existence
- nobody except the developer itself knows how to use it


There already have been lots of discussions on a reform of the help 
system that (e.g. by using a single managed Wiki exclusively as the root 
of the articles) is open for volunteers to provide fixes and additions 
and actually see "live" what they did without waiting for the next 
Lazarus release.


AFAIK this is a too great task to be considered doable in near future.

-Michael

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Lazarus Digest, Vol 99, Issue 32

[Giuliano Colla]

Il 09/04/2016 16:41, Juha Manninen ha scritto:

Comments are overrated.
If you think of them as "deodorant masking fishy code" then less
comments is better.


Comments may help to clarify what is obvious to you at the moment of 
writing, but not to anybody else, and maybe even to you some time later.


You are right that usually commenting code is not very useful. Well 
written code is most of the times self documenting, even if *most of the 
times* doesn't mean *always*.
Commenting variables, on the other side, may be crucial for the 
understanding, and not always names are or can be self explanatory. The 
same holds true for procedure parameters, and function results.


I remember reading long time ago the assembler source code of an Intel 
Real-time nanokernel, where I couldn't grasp what a "crflag" variable 
was used for. It appeared to have to do with some kind of data 
protection but it was rather unclear.


Then the same nanokernel was rewritten in PLM which allows for longer 
identifiers, and "crflag" was renamed "CriticalRegionFlag": suddenly 
everything became clear. The purpose and the usage of the flag became 
obvious. If the declaration of crflag had carried a short comment 
"critical region flag", the assembler code would have been much clearer.


Giuliano


--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Lazarus Digest, Vol 99, Issue 32

[Michael Thompson]

On 9 April 2016 at 22:41, Juha Manninen  wrote:

> Are you good in drawing diagrams?
>

:-)  Me?  I'm useless at drawing and at documentation.

When I contributed to mplayer, I came up with three tactics of
documentation - expanded comments in code,
http://wiki.freepascal.org/TMPlayerControl and a demo project that covered
every thing I could think of.

When people ask for help, it's the demo project I point them to :-)

My personal opinion?  Code!  Code always has the answer :-)

Mike
--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Lazarus Digest, Vol 99, Issue 32

[Giuliano Colla]

Il 09/04/2016 16:22, Juha Manninen ha scritto:

On Sat, Apr 9, 2016 at 5:07 PM, Giuliano Colla
 wrote:

Because without a minimal amount of documentation all this valuable work
risks to be useless, because:
- nobody except a few core developers know of its existence
- nobody except the developer itself knows how to use it

LCL is documented more or less.
I guess you mean the IDE internals are not documented. It is true,
their documentaion has low priority compared to public libs.
I also would love to see high level diagrams and other docs about the
IDE. Like always, somebody must do it.
Maybe you ... :)


My comment was about the portions of your or other's valuable work (IT 
IS VALUABLE, you can say it loudly) which aren't documented, or are 
poorly documented. (the *less* sections of the *more or less*)
And to stress to developers (myself included, I'm as documentation lazy 
as anybody else around here, maybe more..) the importance of letting 
other people understand exactly what it's been done, so that it is 
widely used, giving the only possible reward to Open Source developers: 
their work is not just an idle exercise, but it is actually used.


There is a specific moment in the development cycle when a developer can 
find the time to write some documentation: it is between the submitting 
of his patch/implementation/enhancement/whatever, and the testing from 
others. In this stage it would be unwise to change something before 
receiving some feedback, and the developer has still a fresh memory of 
what he's done. If he is encouraged to do it, chances are good that he 
will comply. And chances are also good that while browsing what he's 
just done, he will spot and fix a couple of bugs


Giuliano




--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Lazarus Digest, Vol 99, Issue 32

[Juha Manninen]

On Sat, Apr 9, 2016 at 5:18 PM, Michael Thompson
 wrote:
> You say minimal, code analysis says Average.

Comments are overrated.
If you think of them as "deodorant masking fishy code" then less
comments is better.
What would really help are high level documents of IDE internals.
Diagrams and textual description. My favorite diagram is Sequence
Diagram because it shows both actors and cronological order.
Such documents would help only (potential) developers of the IDE, but
that is already very useful.
Why is it not done?
I think because they help only initially when learning certain code.
The same understanding comes from reading and browsing code, but it
takes longer time.
That's why the developer who knows the code has only little motivation
to draw diagrams.
Anyway, after the initial understanding is got, everybody must read the code.
Thus diagrams are not necessary but the sure would make the project
more attractive to new potential developers.

Are you good in drawing diagrams?

Juha

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Lazarus Digest, Vol 99, Issue 32

[Juha Manninen]

On Sat, Apr 9, 2016 at 5:07 PM, Giuliano Colla
 wrote:
> Because without a minimal amount of documentation all this valuable work
> risks to be useless, because:
> - nobody except a few core developers know of its existence
> - nobody except the developer itself knows how to use it

LCL is documented more or less.
I guess you mean the IDE internals are not documented. It is true,
their documentaion has low priority compared to public libs.
I also would love to see high level diagrams and other docs about the
IDE. Like always, somebody must do it.
Maybe you ... :)

Juha

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Lazarus Digest, Vol 99, Issue 32

[Michael Thompson]

On 9 April 2016 at 22:07, Giuliano Colla 
wrote:

> Because without a minimal amount of documentation all this valuable work
> risks to be useless, because:
> - nobody except a few core developers know of its existence
> - nobody except the developer itself knows how to use it


from OpenHub (which for some reason stopped tracking lazarus a year ago)
In a Nutshell, Lazarus...

   - ...
   - is mostly written in Pascal
   
   with an average number of source code comments
   

You say minimal, code analysis says Average.
I also disagree that the wiki contains minimal content.

Mike
--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Lazarus Digest, Vol 99, Issue 32

[Giuliano Colla]

Il 09/04/2016 14:03, Juha Manninen ha scritto:

Why all this valuable work from me and from other developers is ignored?


Because without a minimal amount of documentation all this valuable work 
risks to be useless, because:

- nobody except a few core developers know of its existence
- nobody except the developer itself knows how to use it

Giuliano


--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Lazarus Digest, Vol 99, Issue 32

[Juha Manninen]

On Sat, Apr 9, 2016 at 1:20 PM, Giuliano Colla
 wrote:
> An answer such as: "Your patch is good, it adds a desirable functionality,
> but without proper documentation, nobody will be able to take advantage of
> it. Please add some concise comments on variable and procedure usage, and we
> will be glad to commit it." would do a lot of good, IMHO.
>
> Should this become a general rule, the situation might strongly improve with
> time.

Giuliano, you have contributed code yourself. I did not expect such
nonsense from you.
Your own code was equally good with other Lazarus code. It had about
the same amount of comments which was fine.
Rejecting patches because they don't have enough comments would have
only negative effects.
Well written code does not need much comments.
"Comments are like a deodorant masking the smell of fishy code that
could be improved."
as sourcemaking.com so well describes:
  https://sourcemaking.com/refactoring/smells/comments

So, your suggestion would only reduce contributions without any
benefit. Typically such ideas come from people who only want to bash
the developers. "Do this and that and then contributions start to
flood in." For some reason those people have no intention to
contribute anything themselves...

Poorly written patches are already rejected and their authors are
guided how to improve them. Things are in order in that front. Most
patches now get accepted or rejected reasonably quickly.
Why all this valuable work from me and from other developers is ignored?

Juha

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Lazarus Digest, Vol 99, Issue 32

[Michael Thompson]

Am 2016-04-09 um 12:20 schrieb Giuliano Colla:
> An answer such as: "Your patch is good, it adds a desirable
functionality,
> but without proper documentation, nobody will be able to take advantage
of it.
> Please add some concise comments on variable and procedure usage, and we
> will be glad to commit it." would do a lot of good, IMHO.
> Should this become a general rule, the situation might strongly improve
with time.

Agreed :-)  In reality though we shouldn't exclude patches just because
they lack the above.  We should only be encouraging decent documentation,
not enforcing it.

"Yay, we've got a patch that finally fixes that annoying TreeView issue,
but rats, we can't commit it because those variables aren't sufficiently
documented"

Mike
--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Lazarus Digest, Vol 99, Issue 32

[Jürgen Hestermann]

Am 2016-04-09 um 12:20 schrieb Giuliano Colla:
> An answer such as: "Your patch is good, it adds a desirable functionality, but 
without proper documentation, nobody will be able to take advantage of it. Please add some 
concise comments on variable and procedure usage, and we will be glad to commit it." 
would do a lot of good, IMHO.
> Should this become a general rule, the situation might strongly improve with 
time.

+1

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Lazarus Digest, Vol 99, Issue 32

[Giuliano Colla]

Il 08/04/2016 21:13, Juha Manninen ha scritto:

Welcome to open source.
Instead of complaining here and wasting everybody's time, you could
have improved the documentation yourself and provide a patch.


In principle you're right. However you should take into account some 
other factors.


Frequently users do complain when a problem arises which they are unable 
to solve by themselves.


Asking them to provide a patch doesn't help too much.

On the other hand there is something that could be done to improve the 
situation, and to encourage contributors to help improving the 
documentation.


There's a number of core developers, which set the rules of the game, by 
evaluating contributions, supervising them and accepting or rejecting 
depending on their view of what the product should look like.


It wouldn't be unthinkable that a contribution be evaluated also in 
terms of documentation. Appropriate comments in the source code make 
almost easy to generate a good documentation.


An answer such as: "Your patch is good, it adds a desirable 
functionality, but without proper documentation, nobody will be able to 
take advantage of it. Please add some concise comments on variable and 
procedure usage, and we will be glad to commit it." would do a lot of 
good, IMHO.


Should this become a general rule, the situation might strongly improve 
with time.


Just my 2 cents.

Giuliano


--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Lazarus Digest, Vol 99, Issue 32

[Juha Manninen]

On Fri, Apr 8, 2016 at 9:33 PM, Alan Corey  wrote:
> OK, I was just hoping for a sentence or paragraph to be added to the
> documentation.

Welcome to open source.
Instead of complaining here and wasting everybody's time, you could
have improved the documentation yourself and provide a patch.

You also happened to trigger Jürgen Hestermann's passion to bash
Lazarus developers with whatever excuse, but that is not your fault.
We should impose some rules for such people. From experience I know it
can escalate indefinitely. Such people feel they have right to use a
free tool and then complain about how bad service they have got and
how the developers should do more and better for serve him.

One more thing:
Copying the whole e-mail thread history in your message is bad.
Please copy only small snippets that you want to answer to or comment.

Juha

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Lazarus Digest, Vol 99, Issue 32

[Alan Corey]

Re: [Lazarus] Suggestion for TRadioGroup documentation

OK, I was just hoping for a sentence or paragraph to be added to the
documentation.  In HTML you group radiobuttons by giving every button
in the group the same name but different values.  I started with a
tgroupbox then went to a tradiogroupbox when it didn't work.  Still
got -1 for ItemIndex so I defined some with tstrings and got a
duplicate set, but itemindex works on those.  Aha!  But a radio button
that doesn't belong to a group isn't much different than a checkbox.

I agree with most things said about documentation except that nobody
has time to read it all.  And it can change, so you have to keep
rereading.  Being a multilingual project complicates things too.  When
I started in Linux I read (and printed) howtos, took them very
seriously.  But by the time I got around to doing what I was reading
about I found the howtos were years old and almost worthless.

I don't have my internal help working yet, and it may not be as good
as Delphi's when I do.  So I Google a lot.  Documentation that looks
like it came out of doxygen turns me off because so much of it's bad.
Good internal help may be a thing of the past.

I've seen bad documentation that looks like it was written by
fledgling technical writers and tells you obvious things. I agree, the
programmer is the ultimate reference/authority but I've had to
document projects and didn't enjoy it either.  So I think some
compromise like the newbie tech writer writes it and the programmer
checks/edits it might work.  How that works in a multilingual
environment I haven't a clue.

Really, I'm sort of trying out Lazarus again.  A year or so when I
tried it last I kept getting an error which, from Googling, I thought
came from the fact that OpenBSD basically has no working locale and
little interest in it.  So I gave up on using it.  Now I find it's
better, and when I get the error doing a "clean up and build" seems to
always get rid of it.  "Illegal character in format string" I think it
was.

On 4/8/16, lazarus-requ...@lists.lazarus.freepascal.org
 wrote:
> Send Lazarus mailing list submissions to
>   lazarus@lists.lazarus.freepascal.org
>
> To subscribe or unsubscribe via the World Wide Web, visit
>   http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
> or, via email, send a message with subject or body 'help' to
>   lazarus-requ...@lists.lazarus.freepascal.org
>
> You can reach the person managing the list at
>   lazarus-ow...@lists.lazarus.freepascal.org
>
> When replying, please edit your Subject line so it is more specific
> than "Re: Contents of Lazarus digest..."
>
>
> Today's Topics:
>
>1. Re: Suggestion for TRadioGroup documentation (Michael Van Canneyt)
>2. Re: *** GMX Spamverdacht *** Re: Suggestion for TRadioGroup
>   documentation (J?rgen Hestermann)
>3. Re: Suggestion for TRadioGroup documentation (Bart)
>4. Re: *** GMX Spamverdacht *** Re: Suggestion for TRadioGroup
>   documentation (Ondrej Pokorny)
>5. Re: Suggestion for TRadioGroup documentation (J?rgen Hestermann)
>6. Re: *** GMX Spamverdacht *** Re: Suggestion for TRadioGroup
>   documentation (J?rgen Hestermann)
>7. Re: *** GMX Spamverdacht *** Re: Suggestion for TRadioGroup
>   documentation (Ondrej Pokorny)
>8. Re: *** GMX Spamverdacht *** Re: Suggestion for TRadioGroup
>   documentation (Michael Thompson)
>
>
> --
>
> Message: 1
> Date: Fri, 8 Apr 2016 17:35:46 +0200 (CEST)
> From: Michael Van Canneyt 
> Subject: Re: [Lazarus] Suggestion for TRadioGroup documentation
> To: Lazarus mailing list 
> Message-ID: 
> Content-Type: TEXT/PLAIN; charset=US-ASCII; format=flowed
>
>
>
> On Fri, 8 Apr 2016, Graeme Geldenhuys wrote:
>
>> On 2016-04-08 15:54, Michael Thompson wrote:
>>> To be fair, a TGroupBox gets things dropped in it, and both nomenclature
>>> and look/feel are similar.
>>
>> I fully agree. As far as I can remember, even in my Delphi days I've
>> made that mistake of dropping radiobutton controls on a TRadioGroup.
>> Bart, it's not as obvious as you think. It's learning by error, and then
>> getting used to that fact.
>
> Or maybe read the documentation ? At least in the case of early Delphis
> that
> would have helped. (can't comment on current Lazarus)
>
> Thinking that you start without reading any form of documentation is an
> attitude which I highly condemn.
>
> Unfortunately, this attitude seems typical for IT.
>
> If NASA or Airbus or Boeing engineers would use that approach,
> I guess a lot of rockets, planes and whatnot would fall on our heads.
>
> I am glad they do not seem to have this attitude.
>
> Even cars come with a manual: usually located in the glove box, because
> your average citizen manages to open that