Hi all,

I like to put a lot of comment in the source and I would like fpdoc to output this comment into the output files. I wrote a small patch to do this with types, it puts all the comment in front of a type declaration into the output html as section "Comment text".

Since I'm not really familiar with both fpdoc and passrc internals I don't know whether this is the best way to do it, could someone enlighten me?

Would people like to include this option in fpdoc, behind the option --include-comment?

Greets,

Mark de Wever

PS comment of the type (* comment *) don't work, don't know why and didn't look into it yet.

(This is kind of shameless self promotion, since I took the PasDoc projects this year: )

If you want to get documentation generated from comments in your source code, PasDoc may be a better tool for you. See [http://pasdoc.sf.net/].

Michalis

Why ;)? Indeed, if you want generated docs from comments, better use pasdoc.

Why ;)? Indeed, if you want generated docs from comments, better use pasdoc.

the source scanner used by fpDoc supports reading of comments for quite some time; but as I already told you (or was it Mattias?), the final support in fpDoc is still missing.
If there is really interest in this feature, I will have a look at it. (And no, I didn't inspect the sent patch yet.)
Any more opinions? Important, not so important?

- Sebastian

I think comments will be useful and important for developer versions of the documentation. Users may not care about the comments in the source code, but it will be really useful for a "developer version" of the docs. Many times I write comments in the code describing what the code does, so this comment feature in FPDOC would help us make developer documentation clearer (users reading the docs, may not care about comments so much).

Kind of unrelated, but I'll be working on a CGI program that taps on top of the FPDOC generated HTML files and allows users to make notes and comments via their web browser underneath the help documents. The way to get users do more work in writing documentation, is to have a comment system right up live on the website. Even the PHP manual does this ;-)

Even though I'm not a fan of XML in many situations, I find FPDOC is a really useful and an awesome tool - this time XML fits the job well since the tags are sparse (lots of data between the tags).

yeah the accuracy of said information leaves a LOT to be desired though

imo if this is done someone needs to be resposible for looking at the comments and checking they are factually accurate.

For sure. The comments are in a different color than the actual "fixed" documentation. It will be clearly stated that "these comments are from users and are not necessarily correct. Users make their best effort to make accurate comments, but occasionally there may be an error".

When an major and important comment from a user is submitted, the docs are recompiled with the new changes. This way you get a fixed factual style documentation, along with user contributed comments. The main problem with FPDOC the way it is now, is that no FPC user in their right mind is going to spend 15 minutes - 3 hours recompiling the entire FPDOCS just to make a small spelling mistake change or add a small and useful comment.

And you think the FPC user is actually going to mail the mailing list with a patch to the docs? Go to all that work and spend hours of his time figuring out how to make and send a patch? People are lazy.. they want to update the documentation right inside little Internet Explorer, Opera, or Konquerer, or ultimately a thin client ;-). I've not actually started working on this project but it's called LufDoc, and I've got all the framework/basics laid out of what the system is, what it will do, and how it will work. I just have too many other things to do right now... I think I will work on this at some point when I'm done fiddling with Syn text editor and PSP a bit more.

Please make sure that the fpdoc commenting logic is clearly separated from the CGI logic. This way your changes can maybe be incorporates in the FPC sources and website.

The end goal is a CGI system which creates HTML on the fly straight from sources and XML documentation.

Even though I'm not a fan of XML in many situations, I find FPDOC is a really useful and an awesome tool - this time XML fits the job well since the tags are sparse (lots of data between the tags).

We also like to think so ;-)

Michael.

I just looked into pasdoc and it looks promising, I'm testing it at the moment.

Mark

Please make sure that the fpdoc commenting logic is clearly separated from the CGI logic. This way your changes can maybe be incorporates in the FPC sources and website.

Yup that's what I planned on doing to modularize development.. A separate database of user comments will be "included" below the permanent FPDOC HTML documentation. The permanent documentation (or at least compiled, not exactly permanent) will exist separately from the database of user comments. This way none of the existing FPDOC source code needs to be changed. Only the CGI program gets installed on a server and it includes each FPDOC HTML page as if it were a PHP include file or a php Read(). Of course I'm not using PHP, so in Pascal terms.. WebFileOut().

We can have documentation mirrors via XML feeds.. but since I don't like XML so much I'd actually consider spitting out an SQL dump or an SDS (simple data storage) dump, or a CSV (comma delimitted) dump of the user comments. The user comments could be parsed by freepascal.org by getting the CSV dump or SQL dump just like an RSS feed does. In addition to live dumps, just a download of the current database dump will be available.

Op Sun, 4 Dec 2005, schreef L505:

Did you miss something?

On the FPC homepage:
- Click "on-line documentation"
- Click "documentation table of contents with comments"
- Click "Add a comment"

Daniël

I think we went over this before. I was talking about the FPDOC "online reference" documents, actually. I think you are talking about the "online documentation" which is different than the online reference? I usually read the FPDOC documents, not the "Online-documentation" Tex generated ones. I do read the "Online" Tex generated ones sometimes, but most of the time I'm running back and forth to the actual FPDOC "unit references".

In any case, the "online document" comment system doesn't work optimally the way it currently is on those online documents you speak of, either.. because all the mirrors out there usually have a higher page rank on google, and the mirrors don't have any comment system. So I end up reading the documentation at another domain name, where there are no option for me to add comments quickly. We need a syndication system anyway, where universities and other mirrors can parse User comments from a database or Rss feed.

It doesn't really matter right now at this moment, though. I've talked about this for ages and I never seem to get my point across fully. What I'll do is run this system I speak of on Z505.com domain, and you'll see how it works there. I won't suggest that freepascal.org take a look into it until I have a real world working example to show you what I mean. I will also be documenting other things like the entire Windows.pas file, which freepascal.org does not document for good reasons. That's the Windows API reference project for Delphi and Freepascal programmers. I have the server space and bandwidth for thousands of documents so I have no problem hosting all of this. Again, I don't want to sound all talk and no action here.. so I think I'll save discussing my ideas until proven on Z505.

For now I switched to pasdoc, since it fulfills my shortterm needs. But I still would be interested to see this option in fpDoc.

Mark de Wever

Op Sun, 4 Dec 2005, schreef L505:

We have only "Online documentation". Some of it is generared from Tex, some from fpdoc. I guess you refer to the RTL documentation, which is the portion generated by fpdoc and the comment system is active on it. You may be confused that the URL looks like a normal html file (which they are on disk), but the comments are automatically added by the static pages module that is responsible for the comments. It can be switched on and off for any html page, and we can hide/modify/delete any comment.

The purpose of a mirror is that it reduces the load on the main site. If they access a database of the main site, or an RSS feed, you are putting load on the main site. So you would need to do off-line synchronisation, it sounds very complicated to me and needs to be set up by people who are not necessarily be willing (or don't even have the knowledge) to spend a lot of time in setting up complicated stuff.

It is quite likely the FPC webpages will become less static html in the future. We could help mirrors to install dynamic stuff, but my experience is mirror maintainers simply want to install a bunch of html files, and nothing else.

Well, if you are pointing at the PHP manuals I can say we have 100% of that functionality right now. If you want to write such a system in Pascal, go ahead, I won't stop you, the more Pascal code the better.

Daniël

Yes I know...
I have quite concrete plans in mind for a kind of 'next generation fpDoc' (some nice and cute extensions, e.g. for online editing...), but I have to finish some other things first.

- Sebastian

I think I finally figured out your little comment system for the units generated with FPDOC that I seemed to magically find today:

http://community.freepascal.org:10000/docs-html/rtl/index.html

The comment system *is* (and has been, for how long I don't know) in place - even if it took me 50 years to find. The major problem is no one reads those documents, or can find them easily. People read what is indexed by google: http://www.freepascal.org/docs-html/rtl/

I think the reason I've never landed on a comment document page is because google treats them as duplicates and doesn't index them. That, and as I said before, the fact that we have so many FPC mirrors out there with the exact same content makes google think there is no need to index the documents with comments.

I'd force the comments onto people - they can't do any harm. Why offer the docs without comments? It'd be better for google, but not necessarily better for those people who don't like comments under the documents (who wouldn't?).

Sorry if I couldn't find them - but if I can't find them, who can? (unless I'm a clutz, which is highly possible).

The author, for one :-)

The commenting system puts extra load on the server which I don't want.

Michael.

Amazon.com has a patent on one click shopping, I believe. I think I know why.

Well, with the FindPart function, back 7 months ago.. I found an error in the docs regarding the Result/Return value. I reported it - but was too lazy to submit a patch. And guess what, the findpart error in the documentation is still there today, 7 months later.

Wait a minute - *lazy* is actually the wrong word. Forget I said lazy. I'm far from lazy. I'm a hard worker. And yet my animal instinct still tells me that making a doc patch via the current setup, or adding a comment via the current setup, is not natural. My instinct, as an animal, is to leave the error in the docs and move on to other things. It's not one click shopping.

My instinct, as an animal, when I arrive at the PHP website, is to correct the docs if I see an error. It's one click shopping.

But if you only leave a comment, it still isn't fixed in the source (of the documentation). This means next release still will contain, because the comments are not part of the distributed docs.

Vincent.

Amazon is a company which can add FPC servers are paid out of our own pockets, so things as 'load' etc. form a big restriction.

If we had a separate server 'docs.freepascal.org' then there was no problem. But we don't, so 'one click shopping' is not an option at this point.

Michael.

Michael Van Canneyt wrote

Amazon is a company which can add servers at will. The FPC servers are paid out of our own pockets, so things as 'load' etc. form a big restriction.

By the way I think this is missing a lot on Free Pascal.

You guys could start calling enterprises to support the project. Have a meeting, present the project and then ask for hardware / money to pay development. I know many project witch greatly benefited from this.

I have some experience with this kind of thing and I can tell you that this ins´t as hard as it sounds.

Felipe

Felipe Monteiro de Carvalho wrote

You guys could start calling enterprises to support the project. Have a meeting, present the project and then ask for hardware / money to pay development. I know many project witch greatly benefited from this.

And I know that most (if not all) of us simply don't have the time to invest into that. I also don't think any of us would be able to quit his day job and get paid full time to work on FPC. I for one wouldn't even want that, it would stop being fun...

Jonas

It's not so much the 'hard' that is the problem.

As with the PR thing: The core developers really don't have time for this. It takes a lot of effort: prepare, go there (costs again money), follow- up. You need some kind of legal entity etc etc etc.

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...

Michael.

Would they like to have time for this?

Look at my experience. I work for the University of São Paulo. I am not developing the Virtual Magnifying Glass
(http://www.braillevirtual.fe.usp.br/temporario/magnifier.png) as a hobby, althought it is so much fun that I would. I am a *paid open source developer*.

One of the guys that work with me called Microsoft and one of their directors went to where we work to talk about another project we develop. We didn´t even had to go there. We did not prepare a formal presentation, we only had a reunion. He even offered software / hardware to sponsor us! The same with Macromedia.

Companies like to have their names on projects with big visibility, and that´s where the marketing thing comes.

You need to find companies interested in Pascal and companies interested in Open Source and then ask them for support.

I would start with IBM. Many companies support open source. Google does. HP does. Apache, the linux kernel, all started as free time projects and ended up with paid developers.

If you guys wouldn´t like to code for Free Pascal as your main activity perhaps you can ask the enterprises to hire someone else to help. Similar to this is:

* Sending a propolsal for Google "Summer of Code" for them to pay someone to help develop Free Pascal.

* Send a propolsal for IBM to pay propaganda for you as part of the Linux on Power project http://www.linuxonpower.com/

etc, etc, etc, etc

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 can even send propolsas for IBM / Google / etc for them on those projects (althought I need you guys to formally support this things), but reunions and things like that have to be done by someone from "inside". You can´t just say: I like free pascal and I would like you to sponsor it. You have to be a developer to ask for that.

Felipe Monteiro de Carvalho wrote

* Send a propolsal for IBM to pay propaganda for you as part of the Linux on Power project http://www.linuxonpower.com/

That already happened, and thanks to that we now have a ppc64 version of the compiler.

Jonas

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.

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.

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.

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).

> 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.

I've looked at people in charge many times, but I've never seen those in charge sticking their head out telling me directly, with real instructions how I can help, along with my
SVN password, what the rule are with what I'm allowed to help with, etc.

All I've (we've) seen so far is the people in charge criticising any incoming suggestions or concepts. I'm no lazy man, I'm a grunt worker. I stick my neck in when I have precise directions on how to and what I'm allowed to. I think there are more conflicts here going on then just people not sticking their neck in. Constantly critisizing people for not sticking their neck in won't really help. Sending them an email questioning what they would like to help, where their svn password is, under what conditions , etc. will help.

At times I find the responses of the FPC lists negative rather than encouraging.

Let's have collabritive discussion with precise directions on where I and others can help, in what programming languages, with what restrictions - rather than arguments and quick judgements such as "ahh, he won't help, otherwise he would have uploaded it already".

Uploaded where? Under what circumstances? With what password? With what language? I'm sorry, but it's not just as simple as a patch, with this documentation system. With a compiler change, it is sometimes as simple as a patch. This is not a compiler change, this one. This isn't a patch. Plus, I dont' see any way to make patches to the PHP code anyway - as stated in previous mail regarding only seeing HTML on svn. Plus, even if a patch were possible, I don't think it would be allowed in anyway - because my suggestions have been determined as no-goes already. So if our discussion has led us to the conclusion that we won't be implementing what I thought up, why bother me doing any grunt work anyway? You see, you do have to have discussions before doing grunt work - because if I would have done the grunt work, the patch of mine would have been disregarded anyway!

You probably did. The main site is indeed a static site.

Only the directories html/bugs and html/contrib contain PHP code. They are scheduled for rewriting in FPC. (in fact, you'll see the code for the pre-PHP cgi website in those directories as wel)

Michael.

Op Wed, 21 Dec 2005, schreef L:

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.

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.

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.

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

Op Wed, 21 Dec 2005, schreef L:

Our policy is that we give people SVN access after they have contributed code a few times. Perhaps it is a bit annoying, but we need to be a bit conservative here to prevent too many people messing with FPC's code. However, it is not very hard to gain SVN access, usually we are quite open to it.

All I've (we've) seen so far is the people in charge criticising any incoming suggestions or concepts.

We need to, not everything that can be done should be done, and a lot of proposals are about "let's start from scratch and do it better".

That is way too sceptical. Yes, you need to have discussions, if it is a good idea. However, if your proposal is to write an enchancement to the site, or a cleanup, or whatever it won't be taken so skeptically. Proposing features that already exist, like a commenting system, makes people skeptical, though.

Daniël