[fpc-devel] [RFC] fpdoc output comment from the source

[Daniël Mantione]

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

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.

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

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.

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

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