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

[Reinier Olislagers]

On 1-3-2012 9:16, Frank Church wrote:
> On 29 February 2012 19:52, Michael Van Canneyt <michael at freepascal.org
> 
>     On Wed, 29 Feb 2012, Reinier Olislagers wrote:
>         I'd love to see that patch committed or get some feedback on it ;)
>     But there were quite some errors in the XML, which is why I left it
>     for later...
> Isn't this an example of what is considered wrong with the FPC/Lazarus
> processes?
> 
> 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 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.

Good point.
I do suspect they might exist but might be just not well known enough
for people to stumble on... I hope this thread brings them out.

As for people being emailed etc... there's a separate docs category in
Mantis... so people interested in docs could follow that anyway...

(Apart from that, I don't know if you noticed, but I did email the list
in November with the docs before submitting the patch... which might be
a good idea if submitting larger changes..)


> 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?
Actually, why not leave it as is but couple it with DoDi's idea: people
submitting patches for libraries should also include documentation -
even if it's just the barest notes. If not, their patch does not get
into the code.
Yes, they would need a tool to check syntactic correctness in any case.

If they already have commit rights on the source code repository, it
might be useful to also allow them on the fpdocs repository...
IMO, sketchy documentation is better than none - people that know the
libraries shouldn't be deterred to contribute docs.
A solution might be to mark a package in the documentation as "temporary
documentation" or something which gets output to the help.

That might be a compromise between having tight control of docs (current
situation) and fewer barriers to contribute...

However, already having an automated way of checking the XML would be a
large step forward...

Regards,
Reinier