[fpc-devel] [RFC] fpdoc output comment from the source

[Daniël Mantione]

Op Wed, 21 Dec 2005, schreef L:

> 
> > We've looked at the people on the mailing list many times, but we've
> > never seen people sticking out their neck and actually doing something
> > along these lines. It takes long-range commitment, which is probably
> > what scares many people off...
> 
> 
> I've volunteered to help, but I think there are too many conflicts with what I would
> use to program a website versus the current system in place. All I heard was "we
> don't need any concepts or ideas, we need people to help" But I did offer to help -
> don't deny that.

Exactly, we cannot have a lot of people wanting to throw eveything away 
and their own thing. That'll cause a horrible mess. We are flexible 
however. For a good plan, that doesn't conflict too much, help will be 
more than welcome.

> This is why time after time I keep recommending more pascal users to 
> make their own
> websites. Many of us don't have the same website engines or choice of website
> databases. Better 50 users create 50 high quality websites on Pascal than 50 users
> all arguing about what the engine behind the doc system is going to be.

Yes, but people need to work together. An example of a failed site is 
www.friends-of-fpc.org. The idea is good, but there is only one man behind 
it, which caused the website never to have attractive content. A very good 
example how to do it is pascalgamedevelopment. I would definately like to 
see more of those sites. Most PR should be done outside freepascal.org.

> We are discussing an open documentation system that does not require and SVN account
> or patching. The whole idea of an open documentation system that does not require an
> SVN account, is that you do not need to "stick your neck in" - you only need to
> stick your pinky finger in!  You are proving my point by saying I must "stick my
> neck in" .  I shouldn't have to stick my neck in. It should be one click shopping.
> For updating the compiler code itself? Yes, that you should definitely have to stick
> your neck in. That is more complicated, for sure.  It's got nothing to do with PR
> right now, really. The popularity might come as a side effect to a good manual. But
> I'm not saying it is the reason Pascal isn't as popular as C. i.e., I'm not pushing
> PR here.. that's not what I'm getting at.
> 
> My only fear of building a documentation engine on my domain, is that I will reinvent
> the wheel. I'd rather make improvements or suggestions to the current doc system in
> place, so people don't have to run to 60 different websites to read different
> documentation engines out there. It's not that I'm afraid of grunt work - I can throw
> together a system - but I'd rather not if it will cause more harm, causing users to
> run around to my doc site, freepascal's doc site, another doc site, and another doc
> site, etc.

Indeed, writing fpc documentation outside freepascal.org is definately not 
a good idea. You want the community to help writing documentation. That 
is a good idea, we're evaluating the options to do that as well, but not 
very easily implemented, so should be a well thought out plan. Help is 
welcome here.

> You do have to have discussions, before you implement something big like this. I'm
> not just talking out my my fat mouth here. I'm honestly fearing that having more than
> one documentation engine out there will cause some harm, instead of some good. That,
> and of course I don't program in PHP any more, so I may not even be of help to the
> current freepascal engine anyway (and last I looked, I couldn't see the PHP code on
> SVN anyway - just html. Maybe I missed it).

The only part of the web site that uses php is the bug tracker. The new 
bug tracker will be written in Free Pascal.

Daniël