On Sun, 1 Jul 2018, Jim Lee wrote:
On 07/01/18 12:28, Michael Van Canneyt wrote:
The documentation is brought up to date at every release: all new
identifiers are documented and the documentation regenerated.
If you look in the bugtracker, you will see that I regularly fix
documentation issues.
Thanks. The user's guide, programmer's guide, and language reference
manual all say they are for version 3.0.2. Perhaps the current version
didn't require any documentation changes?
Seems I forgot to update the symlink when we released. I fixed that. Thanks
for pointing it out.
If you think it is too terse in places, please report them in the
bugtracker. I will always fix all such reports.
That really wasn't my point. From the point of view of someone just
coming to fpc, the documentation is the "face" of the product. If that
face is ugly or hard to navigate, they are likely to just walk away.
Getting involved in the bugtracker is for people already invested in
fpc, and familiar enough with it to not *need* the documentation.
I consider this an error in your reasoning.
The bugtracker is very lowlevel, and should be usable and familiar for all.
Many of the documentation bugreports are from one-time users, people I never
have heard from.
It is all there, user's guide, language reference, programmer's guide,
Reference to *all* rtl units. What do you think is missing ?
See https://www.freepascal.org/docs.var
Perhaps the rtl is more complete than the rest - I'll take your word for
it. I know it's a tremendous amount of work!
The class library chart on that page is nice, but it's 11 years old
(dated 2007).
This is known. I better remove it, it does more damage than good now.
index:
RTL: https://www.freepascal.org/docs-html/current/rtl/index-8.html
FCL: https://www.freepascal.org/docs-html/current/fcl/index-8.html
An auto-generated index of all identifiers used across all modules is
useful, if you know what you're looking for. Say I was looking for
something like a Timer class - where do I start? Would it be in the
rtl, the fcl, or somewhere else? Would it be named Timer, TTimer, or
something else? I can't find an index that has an entry for "timer" and
points to all the timer-related things.
In the absence of a search mechanism:
You would get a long way if go to the FCL page, press ctrl-f and type timer
in the search box of your browser..
The 4th hit on the page gives you fptimer, the unit that contains a
timer.
But most of the time when I search for something, I just enter google, type
"free pascal timer". The third hit is the same as the one I mention above.
You can't beat google for ease of use and accuracy.
Packages are another story. I checked the packages. There are roughly
16.000 classes.
I didn't count methods/functions, but they surely are a multiple of that.
There is 1 documenter: me.
Pardon my ignorance, but I take it that "packages" is more like an
un-curated repository of contributions rather than an official part of
the fpc distribution? If so, I wasn't aware of that. It would explain
a big part of my frustration.
FPC's "packages" are not uncurated. They are mostly import units, allowing you
to
work with all kinds of open source libraries. On top of these e.g. the data
acces
units are built.
But I know that search is an issue, hence my question "what is the problem
with the documentation _besides_ search".
Contrary to what it may seem it is not so easy to make a search engine for
the documentation. I've had several shots at it, but have not yet come up
with a good mechanism. The last mechanism I tried ended up indexing more
than 24 hours before I killed it.
Contributions or ideas welcome.
Michael.
_______________________________________________
fpc-pascal maillist - fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal
