[fpc-pascal] Re: Where and how is the FPC documentation created?

[michael.vancanneyt at wisa.be]

On Thu, 1 Mar 2012, Frank Church wrote:

> On 29 February 2012 19:52, Michael Van Canneyt <michael at freepascal.org>wrote:
>
>>
>>
>> On Wed, 29 Feb 2012, Reinier Olislagers wrote:
>>
>>  On 29-2-2012 17:07, michael.vancanneyt-**0Is9KJ9Sb0A at public.gmane.org<michael.vancanneyt-0Is9KJ9Sb0A at public.gmane.org>wrote:
>>>
>>>> On Wed, 29 Feb 2012, Frank Church wrote:
>>>>
>>>>> Another question, are you and Florian Klaempfl the main or only
>>>>> contributors?
>>>>>
>>>>
>>>> I am virtually the only one, but I do receive and apply minor patches
>>>> from time to time.
>>>>
>>> *Cough*
>>> http://bugs.freepascal.org/**view.php?id=20735<http://bugs.freepascal.org/view.php?id=20735>
>>> *cough*
>>>
>>> I'd love to see that patch committed or get some feedback on it ;)
>>>
>>
>> oh :/
>>
>> I tried it at once when you submitted it.
>> But there were quite some errors in the XML, which is why I left it for
>> later...
>>
>> .... and eventually forgot about it :(
>>
>> My apologies for this.
>>
>> I now corrected the XML and committed it. Rev 892.
>>
>> Thank you for the contribution !
>>
>> Michael.
>>
>> ______________________________**_________________
>> fpc-pascal maillist  -  fpc-pascal at lists.freepascal.**org<fpc-pascal at lists.freepascal.org>
>> http://lists.freepascal.org/**mailman/listinfo/fpc-pascal<http://lists.freepascal.org/mailman/listinfo/fpc-pascal>
>>
>
>
> Isn't this an example of what is considered wrong with the FPC/Lazarus
> processes?

Absolutely not.

> At the very least if Reinier did not have the rights to commit, he should
> have had a duplicate set of the tools  Michael used to check of the
> correctness of the file (assuming that it was not visually inspected). If
> there was some automated system capable of checking the file's syntax and
> accepting it, Reinier would have known straight away and fixed it

He has all the needed tools and he should have done so prior to submitting.

That he did not check before submitting is not an error in the system, but his mistake.

That I didn't notify him of the errors when I first checked, is my mistake.


> immediately. Others who have registered an interest in that topic would
> also have been automatically emailed then they could review the correctness
> and quality of the contents etc. Perhaps they exist and I and a lot of
> others don't know about them.
>
> At this stage it doesn't look like Reinier knows what the flaws in the file
> he submitted are, unless he diffs what Michael committed against what he
> submitted
>

He could perfectly have run fpdoc on the file. The command

fpdoc --package=fcl --input=ibconnection.pp --descr=ibconnection.xml --output=latex

would have given him all the info he needs. The standalone editor can
construct and run this command for you, if I'm correct. The Makefiles contain
lots of examples, waiting to be consulted. And all this is documented in
official docs on the Free Pascal website.

What more can people want ?

> Imagine what happens when more and more people submit docs and the extra
> work for the few people with commit rights.

Everyone on the FPC/lazarus teams has commit rights. 
It's just like regular submissions.

> There is also one thing. The documentation of the libraries and the
> compiler proper are different issues. In the case of the libraries
> shouldn't those who create them have commit rights in that area assuming
> that they have the tools to check the syntactic correctness of their
> submissions?

But they do. But this doesn't help in this particular case.

Reinier didn't create the ibconnection unit; He has no SVN access to
anything. I assume he uses the unit, and therefor decided to document it.

Michael.