Where and how is the FPC documentation created?

classic Classic list List threaded Threaded
26 messages Options
12
Reply | Threaded
Open this post in threaded view
|

Where and how is the FPC documentation created?

vfclists .

A few months ago I inquired and got some info about FPC docs - discussed in this thread http://lists.lazarus.freepascal.org/pipermail/lazarus/2011-November/068595.html, the result of which can be found here - http://fpdocs.rca2.net and here  - http://fpdocs.rca2.net/user/user.html, when FPC was at 2.4.4

When I visit the source page http://www.freepascal.org/docs-html/user/user.html it is not on 2.6.0.

1. Are the created by a tool or hand edited?

2. Is there some page where the original docs are created?

3. Are they text files that are stored under version control?

4. Is there some page where previous versions are available?

PS. After some searching questions 2, 3 and 4 are answered - http://svn.freepascal.org/svn/fpcdocs/.

One more thing is there some other page where the commit messages for the files are noted? I can only see plain text.

I am of now to ask similar questions about Lazarus

--
Frank Church

=======================
http://devblog.brahmancreations.com

_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Where and how is the FPC documentation created?

michael.vancanneyt


On Wed, 29 Feb 2012, Frank Church wrote:

> A few months ago I inquired and got some info about FPC docs - discussed in
> this thread
> http://lists.lazarus.freepascal.org/pipermail/lazarus/2011-November/068595.html,
> the result of which can be found here - http://fpdocs.rca2.net and here  -
> http://fpdocs.rca2.net/user/user.html, when FPC was at 2.4.4
>
> When I visit the source page
> http://www.freepascal.org/docs-html/user/user.html it is not on 2.6.0.
>
> 1. Are the created by a tool or hand edited?

Depends on what you mean. The docs are made by hand. When we make a release,
we manually upload the new version.

>
> 2. Is there some page where the original docs are created?

No.

>
> 3. Are they text files that are stored under version control?

Yes.

>
> 4. Is there some page where previous versions are available?

No.

>
> PS. After some searching questions 2, 3 and 4 are answered -
> http://svn.freepascal.org/svn/fpcdocs/.
>
> One more thing is there some other page where the commit messages for the
> files are noted? I can only see plain text.

No.

Michael.
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Where and how is the FPC documentation created?

Tomas Hajny-2
On Wed, February 29, 2012 16:44, [hidden email] wrote:

> On Wed, 29 Feb 2012, Frank Church wrote:
>
>> A few months ago I inquired and got some info about FPC docs - discussed
>> in
>> this thread
>> http://lists.lazarus.freepascal.org/pipermail/lazarus/2011-November/068595.html,
>> the result of which can be found here - http://fpdocs.rca2.net and here
>> -
>> http://fpdocs.rca2.net/user/user.html, when FPC was at 2.4.4
>>
>> When I visit the source page
>> http://www.freepascal.org/docs-html/user/user.html it is not on 2.6.0.
 .
 .
>> 4. Is there some page where previous versions are available?
>
> No.

To amend Michael's answer a bit - previous releases of the compiled
documentation are obviously available for download in the standard way and
the source files for the documentation can be accessed via the SVN
repository in a standard way to check for differences to some older
revisions.

Tomas


_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Where and how is the FPC documentation created?

vfclists .
In reply to this post by michael.vancanneyt


On 29 February 2012 15:44, <[hidden email]> wrote:


On Wed, 29 Feb 2012, Frank Church wrote:

A few months ago I inquired and got some info about FPC docs - discussed in
this thread
http://lists.lazarus.freepascal.org/pipermail/lazarus/2011-November/068595.html,
the result of which can be found here - http://fpdocs.rca2.net and here  -
http://fpdocs.rca2.net/user/user.html, when FPC was at 2.4.4

When I visit the source page
http://www.freepascal.org/docs-html/user/user.html it is not on 2.6.0.

1. Are the created by a tool or hand edited?

Depends on what you mean. The docs are made by hand. When we make a release,
we manually upload the new version.



2. Is there some page where the original docs are created?

No.



3. Are they text files that are stored under version control?

Yes.



4. Is there some page where previous versions are available?

No.



PS. After some searching questions 2, 3 and 4 are answered -
http://svn.freepascal.org/svn/fpcdocs/.

One more thing is there some other page where the commit messages for the
files are noted? I can only see plain text.

No.

Michael.
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal


I am asking because if there some changes to some of the pages because of new language facilities etc, some features, deprecated etc commit messages would make it easier to track what is new and what has been changed. The pages are also not dated so it is difficult to find out what may be pertinent in the present and what is old and perhaps little used.

Another question, are you and Florian Klaempfl the main or only contributors? Is it open to only a few people and do you upload it for general viewing only when it is ready? In a nutshell is it possible to non contributors to view the changes as they are happening?

--
Frank Church

=======================
http://devblog.brahmancreations.com

_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Where and how is the FPC documentation created?

michael.vancanneyt


On Wed, 29 Feb 2012, Frank Church wrote:

>
> I am asking because if there some changes to some of the pages because of
> new language facilities etc, some features, deprecated etc commit messages
> would make it easier to track what is new and what has been changed. The
> pages are also not dated so it is difficult to find out what may be
> pertinent in the present and what is old and perhaps little used.
>
> 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.

> Is it open to only a few people and do you upload it for
> general viewing only when it is ready? In a nutshell is it possible to non
> contributors to view the changes as they are happening?

Everything is in subversion, the fpcdocs repository.

Michael.
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Where and how is the FPC documentation created?

vfclists .


On 29 February 2012 16:07, <[hidden email]> wrote:


On Wed, 29 Feb 2012, Frank Church wrote:


I am asking because if there some changes to some of the pages because of
new language facilities etc, some features, deprecated etc commit messages
would make it easier to track what is new and what has been changed. The
pages are also not dated so it is difficult to find out what may be
pertinent in the present and what is old and perhaps little used.

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.


Is it open to only a few people and do you upload it for
general viewing only when it is ready? In a nutshell is it possible to non
contributors to view the changes as they are happening?

Everything is in subversion, the fpcdocs repository.


Michael.
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal


So it means that if I want to check on updates I have to download the repository and link it with something like ViewVC or ViewSVN?

How often do you update it?




--
Frank Church

=======================
http://devblog.brahmancreations.com

_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Where and how is the FPC documentation created?

Vincent Snijders-3
In reply to this post by vfclists .
Op 29 februari 2012 16:29 heeft Frank Church <[hidden email]> het
volgende geschreven:
> 4. Is there some page where previous versions are available?
>
> PS. After some searching questions 2, 3 and 4 are answered -
> http://svn.freepascal.org/svn/fpcdocs/.

or: http://svn.freepascal.org/cgi-bin/viewvc.cgi/?root=docs

Vincent
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Where and how is the FPC documentation created?

Reinier Olislagers
In reply to this post by vfclists .
On 29-2-2012 18:57, Frank Church wrote:
> On 29 February 2012 16:07, <[hidden email]
> <mailto:[hidden email]>> wrote:

>         Is it open to only a few people and do you upload it for
>         general viewing only when it is ready? In a nutshell is it
>         possible to non
>         contributors to view the changes as they are happening?
>
>
>     Everything is in subversion, the fpcdocs repository.

>
> So it means that if I want to check on updates I have to download the
> repository and link it with something like ViewVC or ViewSVN?


or svn update, svn log | more, I suppose?

Reinier

_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Where and how is the FPC documentation created?

Vincent Snijders-3
In reply to this post by vfclists .
Op 29 februari 2012 18:57 heeft Frank Church <[hidden email]> het
volgende geschreven:
>
> How often do you update it?

See:
http://svn.freepascal.org/svn/logs/fpcdocs-trunk.log

(also available with viewvc).

Vincent
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Where and how is the FPC documentation created?

Reinier Olislagers
In reply to this post by michael.vancanneyt
On 29-2-2012 17:07, [hidden email] 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
*cough*

I'd love to see that patch committed or get some feedback on it ;)

Regards,
Reinier
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Where and how is the FPC documentation created?

vfclists .


On 29 February 2012 18:10, Reinier Olislagers <[hidden email]> wrote:
On 29-2-2012 17:07, [hidden email] 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
*cough*

I'd love to see that patch committed or get some feedback on it ;)

Regards,
Reinier
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal

I take it that only Michael can add the ibxconnection.xml files to the documentation?

--
Frank Church

=======================
http://devblog.brahmancreations.com

_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Where and how is the FPC documentation created?

vfclists .
In reply to this post by Reinier Olislagers


On 29 February 2012 18:10, Reinier Olislagers <[hidden email]> wrote:
On 29-2-2012 17:07, [hidden email] 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
*cough*

I'd love to see that patch committed or get some feedback on it ;)

Regards,
Reinier
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal


Another question I want to ask. Was the file generated created completely by hand or did you use a tool to generate a skeleton and layout from the source before filling it out?
--
Frank Church

=======================
http://devblog.brahmancreations.com

_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Where and how is the FPC documentation created?

Reinier Olislagers
On 29-2-2012 20:08, Frank Church wrote:

> On 29 February 2012 18:10, Reinier Olislagers
> <[hidden email] <mailto:[hidden email]>> wrote:
>     *Cough*
>     http://bugs.freepascal.org/view.php?id=20735
>     *cough*
>
>     I'd love to see that patch committed or get some feedback on it ;)
>
>     Regards,
>     Reinier
>     _______________________________________________
>     fpc-pascal maillist  -  [hidden email]
>     <mailto:[hidden email]>
>     http://lists.freepascal.org/mailman/listinfo/fpc-pascal
>
>
>
> Another question I want to ask. Was the file generated created
> completely by hand or did you use a tool to generate a skeleton and
> layout from the source before filling it out?
 --
> Frank Church

I think I used makeskel; see my postings on the list (would be around
November).
After that, it turned out editing the file by hand was quicker than
using fpdoc editor/lazde...

Regards,
Reinier
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Where and how is the FPC documentation created?

Michael Van Canneyt
In reply to this post by Reinier Olislagers


On Wed, 29 Feb 2012, Reinier Olislagers wrote:

> On 29-2-2012 17:07, [hidden email] 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
> *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  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Where and how is the FPC documentation created?

Sven Barth-2
In reply to this post by vfclists .
Am 29.02.2012 19:16, schrieb Frank Church:

>
>
> On 29 February 2012 18:10, Reinier Olislagers
> <[hidden email] <mailto:[hidden email]>> wrote:
>
>     On 29-2-2012 17:07, [hidden email]
>     <mailto:[hidden email]> 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
>     *cough*
>
>     I'd love to see that patch committed or get some feedback on it ;)
>
>     Regards,
>     Reinier
>     _______________________________________________
>     fpc-pascal maillist  - [hidden email]
>     <mailto:[hidden email]>
>     http://lists.freepascal.org/mailman/listinfo/fpc-pascal
>
>
> I take it that only Michael can add the ibxconnection.xml files to the
> documentation?

Not everyone has write accesss to SVN. I don't know who exactly has
write access to fpcdocs, but Michael is one of them.

Regards,
Sven

_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Where and how is the FPC documentation created?

vfclists .
In reply to this post by Michael Van Canneyt


On 29 February 2012 19:52, Michael Van Canneyt <[hidden email]> wrote:


On Wed, 29 Feb 2012, Reinier Olislagers wrote:

On 29-2-2012 17:07, [hidden email] 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
*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  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal


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.

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

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

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?

--
Frank Church

=======================
http://devblog.brahmancreations.com

_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Where and how is the FPC documentation created?

Reinier Olislagers
In reply to this post by Michael Van Canneyt
On 29-2-2012 20:52, Michael Van Canneyt wrote:

>
>
> On Wed, 29 Feb 2012, Reinier Olislagers wrote:
>
>> On 29-2-2012 17:07, [hidden email]
>> 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
>> *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.
>
Thanks Michael,

Sorry about the errors, glad it got committed!

I did try to check for errors, e.g. with something like:
cd /d D:\Reinier\Documents\SourceCode\fpc_laz_patch_playground\docs

rem all on one line ;)
c:\development\fpc\utils\fpdoc\fpdoc.exe
--package=fcl
--input=C:\Development\fpc\packages\fcl-db\src\sqldb\interbase\ibconnection.pp

--format=chm
--output=ibconnection.chm

When that didn't throw up errors and generated a valid ibconnection.chm,
I didn't look for any further errors.

Perhaps there's a better way to check for errors?

Regards,
Reinier
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Where and how is the FPC documentation created?

michael.vancanneyt
In reply to this post by vfclists .


On Thu, 1 Mar 2012, Frank Church wrote:

> On 29 February 2012 19:52, Michael Van Canneyt <[hidden email]>wrote:
>
>>
>>
>> On Wed, 29 Feb 2012, Reinier Olislagers wrote:
>>
>>  On 29-2-2012 17:07, michael.vancanneyt-**[hidden email]<[hidden email]>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  -  [hidden email].**org<[hidden email]>
>> 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.
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Where and how is the FPC documentation created?

michael.vancanneyt
In reply to this post by Reinier Olislagers


On Thu, 1 Mar 2012, Reinier Olislagers wrote:

> On 29-2-2012 20:52, Michael Van Canneyt wrote:
>>
>>
>> On Wed, 29 Feb 2012, Reinier Olislagers wrote:
>>
>>> On 29-2-2012 17:07, [hidden email]
>>> 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
>>> *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.
>>
> Thanks Michael,
>
> Sorry about the errors, glad it got committed!
>
> I did try to check for errors, e.g. with something like:
> cd /d D:\Reinier\Documents\SourceCode\fpc_laz_patch_playground\docs
>
> rem all on one line ;)
> c:\development\fpc\utils\fpdoc\fpdoc.exe
> --package=fcl
> --input=C:\Development\fpc\packages\fcl-db\src\sqldb\interbase\ibconnection.pp
>
> --format=chm
> --output=ibconnection.chm
>
> When that didn't throw up errors and generated a valid ibconnection.chm,
> I didn't look for any further errors.

It should have given you the same errors as I got.
But it will produce a chm file, simply with some parts missing.

Originally, fpdoc would simply bomb out on the smallest mistake.

I got plenty of complaints about that, so now, recoverable errors are just
displayed, but fpdoc will happily grind on and try and produce a file.

Michael.
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Where and how is the FPC documentation created?

Reinier Olislagers
In reply to this post by vfclists .
On 1-3-2012 9:16, Frank Church wrote:

> On 29 February 2012 19:52, Michael Van Canneyt <[hidden email]
>
>     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
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
12