[fpc-pascal] State of FPC docs.rant

[Graeme Geldenhuys]

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 -

-- 
fpGUI Toolkit - a cross-platform GUI toolkit using Free Pascal
http://opensoft.homeip.net/fpgui/