<rant>
I use php, c / c++, vala, java, actionscript, python, javascript and of course pascal.

When I was introduce to pascal it was Delphi, but then I ran into Free pascal and a tiny bit of the pascal community, this mailing list. One of the biggest problems I am having with pascal is learning the libraries. There are plenty of resource to learn how to make procedures, classes, objects, etc, but almost nothing on using the libraries. Not so much the libraries others make (SDL for example) but the ones baked into FPC.

Great example:
"TFPObjectHashTable" has docs, great but no use case or draw backs using this. I searched google, google code and github not a single code example of it being used. How can a library put in place with no demo? Is there not even a unit test case to look at?

You know what fine, I know how to program, So I can read the docs. However here is the kicker, the current state of the docs doesn't really have an ability to just throw up revisions. Instead there is the Wiki, so my true value of this post is...

I am more then willing to provide a better doc, but should it be done in the wiki or should I just span off into my own little world onto my website? An example of what I think a good doc would look like would probably be alone the lines of:
http://gorilla3d.com/v8/wiki/doku.php?id=mysqli_db (self promotion I know) but its very php.net like. Not just here are the parameters and their descriptions but how to used each function in the entire scheme of things.

In the end I think automated documentation is bad, and thats really what I see with the current state of FPC docs. It might allow better ability to stay sync with the current release but not allowing _easy_ social interaction to expand those docs, I think it is a big mistake. </rant>

Is this in response to removing the direct link to unit reference docs with comments at http://www.hu.freepascal.org:10000, that was not really used?

Vincent

Vincent,

Never even knew that existed. It is a big problem with just slapping commenting ability to docs. If its not being used its because there isn't incentive for it. When you see the entire documentation blank of comments would you be so inclined to add it? Documentation is so important and as few barriers should be present to let people contribute. Even more so when you give those powers to the public there still needs to be a much larger drive to those running it to do much of the work up front. They should be putting the comments up in the first place.

Another issue is you need to monitor freshness. I.E http://www.freepascal.org/contrib/db.php3?category=File%20Handling The lot of units in there are broken links, no order of naming, and just all together badly organized. This is in no way FPCs fault, they make the compiler, a damn good one at that, but the comminuty behind this is lack luster. Seems like the FPC team is trying to centralize everything on their ends but doesn't have the resources. Although this is a big rant on my part I will be more then happy to help with anything.

Joseph, Vincent,

<+1>

Add me to the list here.

I also offer to help, especially for writing UML diagrams to help people visualize, including use cases, class diagrams and scenarios. Every component I publish has unit testing and UML diagrams, if only a few.

Thierry

Okay,

Since there hasn't been a clear response on this I've started my own website, to start documenting more of the use of each library. However doing so I am finding some clear issues, and that is some of these units are not finished all the way. Is there some list of missing functionality somewhere for these units? Knowing this would help contributers figure out what units need help.

http://fpc-docs.gorilla3d.com/built-in-units

fcl-image - Ability to write text on canvas has 'NotImplemented" So trying to use any text operations will fail, but there is place holders on type type fonts.

sqlite - Every single query has "Testing: (Query)" outputted in the console. I looked in the unit and found its clearly there with WriteLn(). I also trying to figure out what the second parameter of Query does, Its a TStrings... maybe a prepared statement. I have to read the source code a bit more to find out. I find it weird that both 2.2 and 2.4 have this test print. Does anyone use the unit sqlite included with FPC?

Joseph Montanez wrote

Since there hasn't been a clear response on this I've started my own website, to start documenting more of the use of each library.

The class documentation generated by fpdoc has support for examples. FPC's policy is to only publish documentation on units that have been fully documented. Your mileage my vary on what "fully documented" means. ;-) This is different to the documentation style of for example Lazarus LCL, where automated "template" documentation is generated for all units - most being undocumented.

Looking at your website, that is exactly the kind of code examples that should be included with the official documentation. I think the preferred location should be with the existing RTL and FCL documentation. I don't see a benefit in having fragmented documentation over various websites and locations. This makes it near impossible for a end-user to find help.

I would suggest you checkout the latest copy of the documentation SubVersion repository:

http://svn.freepascal.org/svn/fpcdocs/trunk

Then submit code examples for the various units.

Here is an example of fpdoc documentation generated with images and examples, for another open source project I work on, called tiOPF (Object Persistent Framework).

http://opensoft.homeip.net/tiopf/core/titokenlibrary/index.html http://opensoft.homeip.net/tiopf/core/titokenlibrary/ttokens.html

Image support inside fpdoc was added a few months ago, but I don't think RTL or FCL docs take advantage of it yet. This could be useful for UML or Class diagrams as well - being part of the official documentation.

I'm sure I am speaking for the whole FPC community, that it is great to see people other than Michael van Canneyt help out with the documentation. But I still think we must try to keep documentation together and part of the official documentation as much as possible. The end-users and developers using FPC which find it [the help with examples] easier and be more helpful in the long run.

I don't see a benefit in having fragmented documentation over various websites and locations. This makes it near impossible for a end-user to find help.

The language itself is even worst, this is the biggest pitfall of Pascal in general. I can't tell you how hard it is to find anything on google, and I do mean anything.

http://community.freepascal.org:10000/search/search?q=list+of+strings&t=Search <-- big fail why is everything highlighted (gah!) it gave me a function but nothing on how to use it.
Lets use google, freepascal.org has nothing useful: "free pascal string list" <-- nothing useful
"free pascal list of strings" <-- nothing useful
"free pascal array of strings" <-- nothing useful
"free pascal array of strings" <-- nothing useful
"pascal array of strings" <-- getting closer, but there has to be something on TStringList, right?
"delphi tstringlist" <-- PERFECT

Pascal's presents on Google is piss poor because you have to guess which dialect to use, Pascal, Free Pascal, Delphi, Object Pascal, for searches.

Are you seriously want everyone that wants to help out be forced into SVN and learn FPDoc syntax, submit patches, wait for integration? I'll be more then happy to move my work onto Free Pascal Wiki, but I think its a bad idea to funnel anyone that wants to add to docs even if its a typo change into that sort of process. At least in a wiki if someone wanted to make a quick change they could sign in and make it.

You look at something like http://zendframework.com/manual/en/ were most of the time I don't know what functions I need, but I do know basic topic. I.E I need to implement OAuth, it will walk me through the entire process. Their OAuth example is a bit poor since that will fit into an "Overview" of FPDoc, but their others are a greater example more of a walk through. Code examples are the most important but there is a LOT more that make documentation great. So the last thing you want is a tall wall in front before you can even help out.

On the one hand, Graeme is probably right, in that putting it in the docs is the *best* thing to do. On the other hand, Joseph has a point - I have worked out most bits of FPC over the course of a few years, but the documentation system is certainly a notable exception. After several reasonably serious attempts to understand it, I still have not got the faintest notion *.

However, I do really agree that the last thing to do is to put it on yet another site. My suggestion would be to just put it on the Lazarus wiki, if you are comfortable with wikis. I did that with some database documentation I wrote, not realising at that stage that it really applied to FPC RTL rather than Lazarus. Not one deleted it, no one - sorry, only one person - was rude, and I think a few people have used it since. Significantly, the people who REALLY need it probably won't have worked out that it is technically in the wrong place (under Lazarus instead of FPC) because it seems to take most people a little while to get the difference sorted out anyway.

* If anything is in need of some user level documentation, it is the documentation system it self. I suspect that all the details are documented, but no-one has written the overview, because the people who wrote it knew it so well, they did not see the need. Or perhaps I just have not ever found it.

cheers
John Sunderland

I would suggest you checkout the latest copy of the documentation SubVersion repository: http://svn.freepascal.org/svn/fpcdocs/trunk

No git mirror ;)? I think the docs are one of the fpc related repositories where using a dvcs might be useful. The entry barrier to make changes is a lot lower than for fpc sources itself, final reviewing is done only by one person, a merge does not require a lot of testing, there is no fixes branches which requires proper tracking of changesets being rejected from a merge etc.

In our previous episode, Florian Klaempfl said:

Indeed it does fit the workflow better. And it would be a real life pilot project, not risking the main svn on vague principal viewpoints and bullet lists

But does this mean you have decided to pursue GIT if there is a DVCS to be used at all? What about Mercurial, GNU Arch ???

But does this mean you have decided to pursue GIT if there is a DVCS to be used at all?

No. Git was just an example.

Joseph Montanez het geskryf:

The language itself is even worst, this is the biggest pitfall of Pascal in general. I can't tell you how hard it is to find anything on google, and I do mean anything.

Free Pascal is based on Delphi's Object Pascal language. There are lots of documentation for Delphi, and you can often use Kylix or Delphi help to code for FPC.

Websites like:
http://www.delphibasics.co.uk/
http://delphi.wikia.com/wiki/Delphi_Wiki
http://www.martinstoeckli.ch/delphi/delphi.html
http://www.efg2.com/Lab/Library/Delphi/Strings/index.html ...1000's more by simply searching Google: delphi help

That said, it is no excuse for FPC not to have its own quality documentation and maybe include features specific to FPC. Michael van Cannet has done an excellent job creating the PDFs, but I guess there is always place for improvements... eg: help for people completely new to FPC or Object Pascal, or easily searchable help for developers.

The latter part is something I am tackling head-on. PDFs are great if you want to print them, but they do not work for me as a offline help file format. They are slow to open, search and you don't have context sensitive help support. I want something I can search while offline, make annotations (notes), bookmark topics, search directories of help files etc..

Hence the reason I started the fpGUI DocView project (part of fpGUI Toolkit project). It's a documentation viewer, which views the INF file format (IBM's OS/2 help file format). The INF format is very compact, very fast, and with DocView, it is now accessible across platforms.

I've modified fpdoc to generate newer format of IPF output. IPF is the documentation source you use to generate INF files. So I have INF files for RTL, FCL. LCL and fpGUI. I am also busy rewriting (manually because automated converters did not work well enough) the FPC Language Reference in IPF (end result being binary INF).

The screenshots below are what I have, and I did quick searches using the keywords you mentioned in your previous mail. Now if the RTL and FCL has source code examples, those would be searchable (and viewable as well). Hence the reason I really think such example code should be added with the official documentation.

http://opensoft.homeip.net/~graemeg/docs_screenshot1.png http://opensoft.homeip.net/~graemeg/docs_screenshot2.png http://opensoft.homeip.net/~graemeg/docs_screenshot3.png

I can make the latest binaries of DocView available for download. I can also make the latest INF documents I use available for download. Let me know if you are interested. DocView is not 100% feature complete, I still have many things I want to improve and add, but already it is the only documentation viewer I use while working with FPC, and INF being the only help files I use.

Integrating DocView (via External Tools feature) in IDEs like Lazarus, MSEide or fpgIDE is rather easy. So you will have context sensitive help as well.

As for editing fpdoc-style (XML) documentation, it is rather easy. There is NO need to edit the XML files directly. FPC includes a fpdoc editor (based on GTK2), but the FPDoc Editor included with Lazarus IDE seem much better these days, and allows you to edit documentation while you are busy coding (all part of the IDE). Open the FPDoc Editor (View > FPDoc Editor), then simply place the edit cursor on a unit name, class name, method etc. and type whatever documentation you want it plain clear English in the FPDoc Editor window.

Simply checking out the fpc docs repository is rather simple, then after you added some docs, simply generate a patch and submit it to Mantis. Michael or others are quick in committing documentation updates. For me, this is no more effort than editing a wiki. The downside of the wiki, is that you must be online while editing docs, wiki pages are a spaghetti mess (no structure) etc.. I much prefer offline, search documentation like INF.

Regards,
- Graeme -

John het geskryf:

On the one hand, Graeme is probably right, in that putting it in the docs is the *best* thing to do.

Definately!

On the other hand, Joseph has a point - I have worked out most bits of FPC over the course of a few years, but

Granted that the bulk of FPC's documentation is simply Class or API documentation. A more "new developer" friendly help is needed. If memory serves me well, Michael van Canneyt did say his wants to (or is busy) writing such "newbie" documentation. Included in that will be a section on Object Oriented Programming.

another site. My suggestion would be to just put it on the Lazarus wiki,

The Lazarus wiki is now a combined FPC and Lazarus wiki.

Regards,
- Graeme -

Florian Klaempfl het geskryf:

No git mirror ;)? I think the docs are one of the fpc related repositories where using a dvcs might be useful.

Apparently I am banned for life mentioning the "product that may not be named" in FPC or Lazarus mailing lists. :-)

As for moving to such a DVCS... why bother? I think I can count on two hands the amount of commits per year. As for it being a "pilot" of a DVCS - that would be a pointless exercise with such a slow moving repository.

Regards,
- Graeme -

I would love to contribute to the documentation -- I fancy myself good at writing, explaining, and making examples -- but as noted earlier in the thread, the barrier to entry is quite high.

I'm far more comfortable using git than svn, and if there was such a repo it would help lower the barrier to entry for lack of a simple tutorial on how to add to the documentation still remains a significant barrier, however.

Graeme, I have to ask... on the one hand, you noted that having fragmented documentations over various locations is unhelpful; and on the other hand, I've heard you talk quite a bit about your DocView / INF project; I note in particular that you mentioned rewriting the FPC language reference in IPF. How is this not an example of the fragmentation you refer to?

Don't get me wrong -- based on your explanations, I think DocView is a great idea, and I have been looking forward to trying it out, but I continue to wonder how well it will integrate with the present doc system and if it might lower the barrier to entry for contributing to the documentation.

Cheers,
David

David Emerson wrote

I'm far more comfortable using git than svn

Me too, and it didn't take long either.

OK, maybe you guys don't fully understand what I am doing. I'm not creating a new documentation system or documentation format. I'm only creating a more useful cross-platform documentation viewer, and a help file format that is optimised for size and search speed.

I am still using fpdoc like everybody else, but instead of generating PDF or HTML or CHM output, I improved the very outdated IPF output writer of fpdoc. As I mentioned, IPF is the documentation source code used to generate binary INF help files.

As for the FPC Language Reference. The original document is written using LaTeX (not fpdoc's XML). LaTeX can be quite complex to parse, and that was the case with the FPC documentation, so the INF output it generated was not idea. So I decided to "proof read" the FPC Language Ref doc (something I wanted to do for years), and then at the same time, manually translate it to IPF. By that I mean, I did not change the documentation as such, or add new sections etc. I simply reformatted the text to fit the INF document and viewer better. Improving things like cross-linking between various sections and a better Table Of Content and Index.

All my changes to fpdoc will be submitted as a patch when I am done. I have already submitted many Lang Ref fixes for the LaTeX version. And once done, I am submitting the IPF version to the repository as well, but I'll keep in in sync with the original ref.tex file.

So no, the documentation is not fragmented etc. I hope to keep everything in the same fpc docs repository, and I hope that the INF versions of RTL, FCL and Lang Ref can become official documentation as well (in combination with the existing PDF versions).

wonder how well it will integrate with the present doc system and if it might lower the barrier to entry for contributing to the documentation.

DocView is simply a INF help file viewer. It is not a fpdoc XML editor like the integrated FPDoc Editor included with Lazarus IDE. What DocView does allow, is much easier integration with existing IDEs (no need to install packages and recompile IDE's), offline help, very fast search, search across all help files at once, bookmarks and annotations, and small to distribute (1.3MB executable with no external dependencies). All of this is lacking in the PDF docs and the Lazarus lhelp viewer.

On 26/04/2010 11:52 PM, Graeme Geldenhuys wrote:
...

I think you missed my point. I don't need 'new developer' documentation for OOP. What I can't understand is how the documentation system itself works, ie, how to go about using it to contribute documentation. (Or even how to install it locally, for that matter - So I use what is on the web or trawl through the source code (at least we have that option ) )

So it is! I hadn't noticed that. The FPC wiki used only to have links to the pdfs, IIRC.

Regards, - Graeme -

cheers,
John

I just spent 2 hours on FPDoc's trying to get how to use it. Automatic documentation was dead easy but the whole XML integration part was a nightmare, so I gave up reading the docs on how to use the doc. Instead I figure "Hey there must be examples of this right?" ... *digs through source* ... 5 mins later figured it out.

Spent another hour making a pretty example, found out there was no CSS file generated, and made my own:
http://www.gorilla3d.com/fpdoc/animal/tanimal.talk.html

Here is everything I used to generate it:
http://www.gorilla3d.com/fpdoc/tanimal.zip

Now to think I am going dealing with XML isn't so bad, but the SVN interaction is painful, Git is no different. The reason I like the Wiki so much is that if I click "edit" I see the wiki source, change it and it compiles right there and then. I don't have to download the source code from SVN, recompile each time, submit a patch, etc.

Ideally if I could edit the very page
http://www.gorilla3d.com/fpdoc/animal/tanimal.create.html and only see the XML data for that segment, I would be in bliss. Problem is it wont work for building new docs. FPDoc requires a pascal unit (source code) to try to generate documentation, the part I *hate* about automated documentation. Pascal is one of the few language that you can look in the source code and really READ, so the automated part is of no help other then linking inheritance together and what not.

In the end if we start raiding the Wiki, it would allow anyone to contribute documentation which should be looked at, edited and put into the true documentation of FPC. A lot of administration work no one wants to do.

In our previous episode, Joseph Montanez said:

(You might also want to have a look at the fixdocs.sh script, it is what I use to generate the CHM docs:

http://www.stack.nl/~marcov/doc-chm.zip

)

John wrote

> I think you missed my point.  I don't need 'new developer' documentation for OOP.  What I can't understand is how the documentation system itself works, ie, how to go about using it to contribute documentation.

* Download 'fpdoc.pdf' or 'fpdoc.ps' and read all about tools lake 'makeskel', 'fpdoc' etc.
This is the documentation for the FPC Documentation tools.
* Checkout out the latest fpc docs repository.
* Now you can edit the XML documentents eg: classes.xml with any text editor. OR
You can use the integrated FPDoc Editor included with Lazarus IDE (if you are using
Lazarus).
* To tell Lazarus IDE where the XML documentation are on you hard drive. Add the path via: Environment > Options > FPDoc Editor To open the FPDoc Editor: View > FPDoc Editor

You you then see something like this:
http://wiki.freepascal.org/New_IDE_features_since#Integrated_Documentation_Editor

If you now make changes in the FPDoc Editor window. Most common formatting has toolbar buttons in the editor window. Once you done editing the text, generate a patch and submit to Mantis.

cd <path_to_fpcdocs_svn>
svn status -q
svn diff > my_changes.patch

I don't know if there is "official" documentation describing this process. There is another README.DOCS file inside the root directory of the checked out fpc docs repository.

I also remembered writing the following very basic instructions for the developers working on tiOPF. tiOPF also uses fpdoc-style documentation.

http://opensoft.homeip.net/wiki/wiki.cgi?p=fpdoc-usage-summary

Joseph Montanez wrote

Spent another hour making a pretty example, found out there was no CSS file generated, and made my own: http://www.gorilla3d.com/fpdoc/animal/tanimal.talk.html

Nice. I reported the missing CSS file issue years ago. I thought it was fixed - I guess not.

I'm far more comfortable using git than svn, and if there was such a repo it would help lower the barrier to entry for created a mercurial mirror: http://florianklaempfl.de:8000/fpcdocs/

You must include the freetype engine for this to work; that is why the base classes don't support it, because we want them to be independent of external libraries. Therefor it works using a plugin system.

so a simple 'uses ftfont' will add font support.

No, because: You should probably use the sqlite3 units instead. sqlite is for sqlite2, and that is WAY too old :-)

But I have removed the debug statements. Thanks for reporting it.

Michael.