Hi all,

I've been browsing the net looking for an autodoc generator for FPC. I found PasDoc (pasdoc.sourceforge.net) but I don't know if it will fit my needs. I read something about a FPdoc util which uses xml files for the documentation, but I can not find it, perhaps it's in the CVS. Is this tool ready for its use? and if so could someone give me a link?

cheers, Ivan

Pasdoc has more or less been dropped by the original developer. There are some other people that forked off other versions. I myself have recently modified Pasdoc to work with MySQL database of content. I will be using this with the Lazarus project.

I read something about a FPdoc util which uses xml files for the documentation, but I can not find it, perhaps it's in the CVS.

Correct it is available in CVS. I think that is the only way to get it at this point.

Is this tool ready for its use? and if so could someone give me a link?

MVC can probably give you a better idea of the status of fpDoc. He is using it for the FPC documentation.

Ivan Montes wrote: > I've been browsing the net looking for an autodoc generator for FPC.

I

> found PasDoc (pasdoc.sourceforge.net) but I don't know if it will fit

my

> needs.

Greetings,
Why don'tt you update and use the version of pasdoc that I've included in the projects section of the CVS tree??

> I read something about a FPdoc util which uses xml files for the > documentation, but I can not find it, perhaps it's in the CVS.

MVC can probably give you a better idea of the status of fpDoc. He is using it for the FPC documentation.

Currently for the FPC internal documentation we'll be using the modified pasdoc, but i think that for the RTL and standard unit documentation we'll eventually use FPDoc...

I think the best solution would be if we would merge our changes into the sourceforge
project. Is the maintainer of pasdoc reachable?

Carl Eric Codere wrote

Why don'tt you update and use the version of pasdoc that I've included in the projects section of the CVS tree??

Frankly because I had no idea that it was there. I only just stumbled across it by accident on last week when looking for the mysql files. I saw it when I was using the web cvs access. By that time I had already modified my version of pasdoc which was already a fork of the original version from when I was working on it with Marco.

What modifications have you done to the original code?

No. I haven't had a reply from Marco for almost 2 years. There is another fork of Pasdoc that was made but focuses totally on Win32 and Delphi and probably won't work with FPC any more.

I can try to reach Marco again and see if he wants to turn over the maintainence.

Otherwise, it's always possible to get control over the project if the author has abandoned it and doesn't reply to mails. That's the way we got control over the Freepascal project at sourceforge (we mainly use them as a download mirror :)

Jonas

But it took 3-4 months ...

Not 'eventually'. The classes unit and all other things in the FCL will be documented in fpdoc. If we find some time, the RTL standard units documentation will also be switched to fpdoc. The classes unit is almost done.

It's in the interest of Lazarus and any other components to use fpdoc, and drop pasdoc, as cross-referencing between these two tools will be quite hard. Not to mention that I think that fpdoc is more suitable for the job and produces better output.

Which doesn't mean that pasdoc is bad, but I think the concept of fpdoc is simply better, and I personally will endorse it as the 'official' FPC documentation tool.

Lastly:
I am currently working on a GUI editor for the XML documentation files that fpdoc needs. It's written in a small OOP GTK wrapper so should function on both windows and Linux. When Lazarus is ready for release, I will look at switching the implementation to the LCL.

I've asked Sebastian Guenther when we'll release fpdoc; as far as i'm concerned, this can be done even this week because fpdoc is fully functional. The editor can be released at a later time.

Michael.

Since it wasn't released that is why I wasn't working with it. I wasn't even sure that it was still being worked on.

Because of the way I have setup the MySQL database to hold the documentation it doesn't really make a difference what engine is used to pull the content. It will be just as easy to tweek fpDoc to pull from MySQL as from the current XML. It could even dump to the XML file first and process it that way.

Since I want all Lazarus documentation content to come out of the database which will be Edited via a web page the GUI aspect isn't that important for the LCL right now.

We had talked before about adding the MySQL aspect to fpDoc and you had laid out some tables. Did that ever get added to fpDoc? Should I be able to use that or should I stick with what I have currently designed?

I've asked Sebastian Guenther when we'll release fpdoc; as far as i'm concerned, this can be done even this week because fpdoc is fully functional. The editor can be released at a later time.

I hope I can fix the last remaining bugs until the end of this week; perhaps we'll even get the makeskel update function working until then. But in principal there are no real show-stopper bugs left, as far as I know.

- Sebastian

Since it wasn't released that is why I wasn't working with it. I wasn't even sure that it was still being worked on.

it is...

as a quick hack, you could modify TDocNode (unit 'dglobals') to load its data from a database table instead of XML files. In the long term, we should try to make such base classes more abstract, so that we can officially support several documentation data backends.

- Sebastian

I didn't add anything, since I never received feedback any from you :-) But it should be very easy to add. It's a nice opportunity to test the database components. After I finish the GUI, I will have a look at a mysql -> XML conversion tool.

Michael.

I didn't add anything, since I never received feedback any from you :-)

Hmmm. I thought I had. I guess I must of just answered it in my brain and forgot to commit it to keyboard. ;-)

I just remembered (and checked) why. That was exactly at the time when I switched from using Windows as my work station to Linux. All of that mail was still sitting on the old machine. :-\

But it should be very easy to add. It's a nice opportunity to test the database components. After I finish the GUI, I will have a look at a mysql -> XML conversion tool.

I have to go review our March conversation. :-)

Greetings,
I already contacted sourceforge regarded this, they are currently working on the problem. It was a personal goal of mine to continue pasdoc (outside the FPC project entirely), and as Florian said, it would be interesting to merge Michael's changes with mine.

Carl

> Why don'tt you update and use the version of pasdoc that I've included > in the projects section of the CVS tree??

F> rankly because I had no idea that it was there. I only just stumbled

Greetings,
The most important changes are :
- paragraph support, if text is separated by an empty line, it will create a paragraph in the output text.
- types are now parsed and written (e.g variables, constants and fields now have also their types in the final output)
- @param() for declaring parameters of routines in text.
- An option has been added to only parse comments starting with @ characters (by default this options is off to be backward compatible).

The other stuff is mainly bugfixes, but there is one important difference. i started from a web version modified by someone on the web (which was in turned based on 0.6.20). I don't know which version was the more stable, but the version i used had several bugs i needed to fix.

I also tried to contact Marco, with no answer. As i said it would be interesting to merge our changes, no??

This is a good one.

- types are now parsed and written (e.g variables, constants and fields now have also their types in the final output)

I'm not sure what you mean here. I thought these were already parsed.

- @param() for declaring parameters of routines in text.

Nice.

- An option has been added to only parse comments starting with @ characters (by default this options is off to be backward compatible).

Again very useful. I avoided this by moving all of the documentation out of the source code completely. Let me rephrase that. It first pulls from the source code but if there is content located in the database for that object it takes precedent.

The other stuff is mainly bugfixes, but there is one important difference. i started from a web version modified by someone on the web (which was in turned based on 0.6.20). I don't know which version was the more stable, but the version i used had several bugs i needed to fix.

OK this might be one major difference. I am working from a 0.6.21 version. Why don't you have that version you ask. Because it was a version that Marco and I were working on and I think I am the only one that got a copy of it. It was never posted to the site. It does alot more with using external files, dealing with include files, and a few other things. It was something he modified for me for Lazarus needs.

I will checkout your current version of pasdoc and compare it to what I have and see about merging my changed into your code. I doubt it will be that difficult. I'll let you know how it goes.

So if he doesn't react you'll start a project "take over" as well?