I've made some progress with getting fpdoc up to speed, and here is an initial snapshot:

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

Known issues:
- The class trees are not complete/corrupted where they span packages borders (so often ends with an unclickable TComponent with (?) next to it)
- Most fpdoc generated files are smaller (in the magnitude of 5-10%)

If you notice anything different compared to the previous set, please don't hesitate to reply.

Thanks Marco.

Were you going to tackle the dotted unit name and Delphi style generic declaration problems in the bug tracker? I've been testing documentation generation tools and editing together a nice style with a tree view feature (I'm working on adding an index feature).

Here is an example if you want some inspiration:
http://codebot.org/bare/default.html
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20130420/1cd508ba/attachment.html>

Anthony Walter wrote

Were you going to tackle the dotted unit name

Certainly not.

and Delphi style generic declaration problems in the bug tracker?

That is more interesting, and closer to my heart, but a bit beyond me atm, I'm afraid.

I'm just doing regular debugging stints with fpdoc just to get the docs through, that is it. Usually in sync with FPC releases.

I don't like the treeview (as it is currently). It seems to have a really deep hierarchy, and clicking a link in the right window, doesn't synchronize the left, so you are constantly folding and unfolding the treeview

The toplevel "class" lemma is nearly defunct. It doesn't really provide links to the class (need treeview for that), and doesn't contain much other info.

I also don't like showing methods etc in a table. I like the current situation more (more compact _AND_ more information)

If I recall correctly, docview also suffered from this.

Anthony Walter wrote

Here is an example if you want some inspiration: http://codebot.org/bare/default.html

Problem with web based documentation is that they are very slow, requires online access, and lacks lots of feature that make dedicated documentation viewers a much better choice.

Maybe you should take a look at DocView (fpGUI's documentation viewer) and the highly optimised INF help file format.

DocView starts up in <1s even with multiple large INF files, allows help file concatenation at runtime, advanced searching in and across INF files, annotation support, bookmark support, font customisation, image support etc. It is also very easy to integrate with any IDE or programmer editor.

http://fpgui.sourceforge.net/screenshots_apps.shtml http://fpgui.sourceforge.net/docview_ide_integration.shtml

fpdoc also support the output of IPF, which is the source form of compiled INF help files.

If you want to give DocView a try, pre-built binaries are available for download from SourceForge. There are also pre-built INF help files for fpGUI Class docs, Free Pascal's Language Reference (manually converted to look much better than auto-conversions), FPC's RTL and FCL docs. All in all, a 1.9Mb download for the lot.

http://sourceforge.net/projects/fpgui/files/fpGUI/1.0/ http://sourceforge.net/projects/fpgui/files/fpGUI/Documentation/

Regards,
- Graeme -

The benefit of online docs ...

Anyone can access them without installing a thing (assuming people have a web browser, which everyone does). This allows people to peruse/browse before they try, which is what most people do, read the web and google search stuff.

Since online docs are online, they become easily queryable via everyone default search tool (google, or bing or whatever).

Online docs can be updated/corrected/added to without sending needing to download updates/patches. Even when I add all my units and sources for download, I will most certainly add tutorials/how-to's to help (which are cross referenced inside the help) after the fact. With web help people will automatically see that stuff the next time they visit help, again without the need to distribute a bunch of updates.

And for people that are offline some of the time, you can always offer the ability to download the help to a folder, and they can favorite the default document in their browser to read offline.

Sure I like offline help and dedicated help programs as well, but with all the benefits I outlined above, not putting first class help online is a bonehead maneuver.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20130420/8903d60a/attachment.html>

All true. But that is a reason to _ALSO_ have online docs.

The primary use of SDK information is to access them using context information from within the IDE. In the matching version of course.

It's scary to admit it, but in sofar I agree with Graeme.

Online docs can be updated/corrected/added to without sending needing to download updates/patches.

While true, it is rarely exercised. Docs mostly follow the software release cycle. .... and that is not just for FPC/Lazarus.

Of course, when you get to be the size of an Apple or Microsoft, you can have a continuous team updating it, but that is an exception, rather than the rule.

Maybe you can make online help leading, but then it has to be a lot better than what you posted (for reasons Graeme already said, the interface is too poor).

But whatever route is chosen, I think a development tool (which might be used for a long, long time) should come with documentation. Since the disappearance of online help (or a mere move or change of hosting) would make older versions of the tool unusable, otherwise.

... And something that is totally inaccessible.
So please, please, no something "proprietary". Use widely used formats like HTML, or PDF if you absolutely must.
D?a 20. 4. 2013 20:32 Graeme Geldenhuys wrote / nap?sal(a):

Lubos Pintes wrote

... And something that is totally inaccessible. So please, please, no something "proprietary". Use widely used formats like HTML, or PDF if you absolutely must.

Considering that IBM is not developing/improving the IPF/INF format anymore, the fact that Graeme has developed a fully Pascal open source viewer and that fpdoc contains an open source reader looks like enough reason to support it. Also PDF is propritary as well (maybe even more than IPF/INF).

Regards,
Sven

That reminds me, what is the current status of the INF compiler ?

Lubos Pintes wrote

... And something that is totally inaccessible.

As Sven said, I have implemented a open source pure Pascal viewer that currently runs on Linux (even 10 year old distros), Windows 95-8, FreeBSD, Solaris, Raspberry Pi, WinCE and other Linux ARM Embedded devices. OS/2 and eComStation obviously also can read INF file because it is the native help format on those platforms. There are also INF-to-HTML converters (even IBM has some of there docs currently online like that). I'm also already working on extending DocView to have a PDF export function. Exporting a whole INF document, or selected topics to PDF - thus making it consumable by the select few platforms I don't yet support.

The INF format has been well documented by myself and prior developers - the layout document is included in fpGUI's repository. So you are free to study it, and implement another viewer if you want.

I'm also investigating iOS and Android viewers.

The IPF Compiler (used to generate INF binary help files) is also open source - currently implement in OpenWatcom C/C++. I am busy implementing a 100% pascal compiler too.

So "totally inaccessible" is grossly overstated.

So please, please, no something "proprietary".

ps:
CHM is proprietary too, so is the old Microsoft HLP format, and so too is PDF. Doesn't stop anybody from using those.

I studied for months various help systems and help formats. INF was superior for the task I wanted. It is very compact (the same help content is much smaller using INF, compared to PDF, HTML or even CHM), has Indexing support, Full Text Search, Image Support, simple markup language etc. Is self contained too - as single file. And most importantly, it can be integrated with applications so you can do context sensitive help.

Regards,
- Graeme -

The snapshot above was updated. Most interpackage hyperlinks work again, and the inheritance subpages
(the [properties (by name)] links on each class page) are now filled again.

There might be still errors left, but if there are, they are magnitudes less frequent than the ones now fixed. If you notice a regression, please don't hesitate to contact me.

The old link doc-chm.zip was originally actually meant for fpc only help, (the textmode IDE) and in time I plan to use it for that again.

Please update all links to doc-chm.zip to doc-chm_with_lcl.zip for that purpose.

P.s. I used script build_lcl_chm.sh, not buildchm.sh

Graeme Geldenhuys wrote

On 2013-04-20 20:21, Lubos Pintes wrote: > ... And something that is totally inaccessible. So "totally inaccessible" is grossly overstated.

I don't know. Does DocView work nicely with screen readers? I think that is what ubos meant.

> So please, please, no something "proprietary".

Note: fpdoc can also generate plain html files from the fpdoc sources if told to do so, so you can generate not only CHM,PDF,INF but also HTML and I believe TeX.

Reinier Olislagers wrote

I don't know. Does DocView work nicely with screen readers? I think that is what ubos meant.

Screen Reader support is on my fpGUI to do list, but just not a high priority (unfortunately).

Note: fpdoc can also generate plain html files from the fpdoc sources if told to do so, so you can generate not only CHM,PDF,INF but also HTML and I believe TeX.

Yes, and TXT, RTF (another proprietary format), MAN, XML and Delphi XML. So by just using fpdoc, you have a world of choice.

Regards,
- Graeme -

Anthony Walter wrote

The benefit of online docs ... Anyone can access them without installing a thing (assuming people have a web browser, which everyone does).

Unless your internet goes down... like what happened to me on Thursday. And I live in a first world country (finally) - but not even such countries are immune to internet outages.

This allows people to peruse/browse before they try, which is what most people do,

I supply pre-built binary downloads of DocView and some INF help files - for just that reason. They can download the source code of fpGUI and built everything themselves, but I save them the trouble. And DocView has no installation - just run the executable.

Also the docview resource usage is a fraction of what is needed by these bloated web browsers these days.

Since online docs are online, they become easily queryable via everyone default search tool (google, or bing or whatever).

And they are only has "up to date" as the last time Google or Bing indexed the "whole site". If you update the documentation now, you have on idea when Google will index your site again. It could be a day, it could be a month or more. So searching support is dependant on an external entity that doesn't care about you.

Online docs can be updated/corrected/added to without sending needing to download updates/patches.

Macro replied to that, and I agree with him.

download, I will most certainly add tutorials/how-to's to help (which are cross referenced inside the help) after the fact.

Cross-referencing between INF files are supported since the inception of the INF format. The RTL and fpGUI INF files also have "additional" non-API topics in the help - already supported by fpdoc. INF is like a combination of a Help Format + eBook, and works perfectly in both context.

And for people that are offline some of the time, you can always offer the ability to download the help to a folder,

And then can't search - which programmers do often in help files.

Either way, my major grip with online help is that it lacks lots of functionality I need. Speed, advanced searching with match ranking (and word match highlighting), indexing, bookmarks, context aware, and especially annotation (adding personal notes), I have a lot of personal inline notes added to INF help files, especially the FPC's RTL docs. These notes are stored in a separate file, but DocView embeds them into the help topics as I read.

See the first screenshot on this page. The yellow text is highlighted search matches, the green text is personal notes/annotations embedded into the help text.

http://fpgui.sourceforge.net/screenshots_apps.shtml

Anyway, the URL you posted looks pretty. That's all great, but there isn't much point if documentation looks pretty, but is slow and lacks vital functionality. That is my main argument. Luckily fpdoc supports lots of output formats, so I guess end users could generate whatever format they prefer (if they go to all the trouble).

Regards,
- Graeme -

Marco van de Voort wrote

P.s. I used script build_lcl_chm.sh, not buildchm.sh

So what did you change? fpdoc and the *.lpr in Lazarus repository (docs/html/ directory)? As noted in a message a few days ago, I couldn't build any LCL docs. I wanted to supply and INF version of LCL, but couldn't.

Regards,
- Graeme -

Marco van de Voort wrote

The primary use of SDK information is to access them using context information from within the IDE. In the matching version of course.

"matching version" is a very good point. Currently Lazarus totally fails that point. You can download a 0.9.30.4 version, but have NO related documentation, because the wiki and HTML help is constantly moving. This is a problem for the IDE help and the LCL help.

One can't stress enough the importance of good help - especially in large applications or frameworks. Just look at the mess Embarcadero Delphi help is in. I installed Delphi XE the other day, and included the help option, yet searching for anything returns no results, yet manually navigating to the topic does reveal help - but often outdated. The last good and up-to-date help for Delphi was Delphi v7 - under Borland's control. There online wiki help is not much better.

Since the disappearance of online help (or a mere move or change of hosting) would make older versions of the tool unusable, otherwise.

Another very good point. I often use "The Wayback Machine" to try and find information which disappeared on the internet. Sometimes you are lucky, sometimes not.

Regards,
- Graeme -

Maybe there is a bit of misunderstanding.
By accessibility I meant usage with screen reader. HTML can be read in browser. Contrary to totally graphical viewer
I thought about this situation: There was documentation in HTML for years. Now something "bad" happens and one will be totally dependent on something pure graphical. Thus documentation becomes inaccessible by screen reader user.
I didn't want to be offensive. Orto criticize someone's work. And now when I am thinking about it more, I probably made incorrect assumption that HTML will no more be available?
So yet another sorry if I offended someone.
Currently I am perceiving this thread as a discussion. But just to be sure...
D?a 20. 4. 2013 22:57 Graeme Geldenhuys wrote / nap?sal(a):

@Lubos: I think I understood you :)

Lubos Pintes wrote

Maybe there is a bit of misunderstanding. By accessibility I meant usage with screen reader. HTML can be read in browser. Contrary to totally graphical viewer

Understood.

I didn't want to be offensive. Orto criticize someone's work.

You didn't AFAIC (of course, I only submitted patches to fpdoc, I didn't write it, so my emotional interest is not that big).

And now when I am thinking about it more, I probably made incorrect assumption that HTML will no more be available?

That is indeed an incorrect assumption as indicated by Graeme's and my posts a while ago. The thing is that you have to generate these documents.

Had a look at the sourceforge site for Lazarus but couldn't find any pregenerated HTML docs... except old ones for Laz 0.9.30.4: http://sourceforge.net/projects/lazarus/files/Lazarus%20Documentation/Old%20releases/Lazarus%200.9.30.4/fpc-lazarus-doc-html-0.9.30.4.tar.bz2/download

Currently I am perceiving this thread as a discussion. But just to be sure...

Sure, no hard feelings ;)

Thanks, that looks much better than the Laz 1.0 docs. Index/searching seems improved.

Lubos Pintes wrote

Maybe there is a bit of misunderstanding.

No problem, I didn't know by "totally inaccessible" you meant for screen readers. fpdoc supports many output formats, so in no way are you limited to just INF, PDF etc.

Make no mistake, I do see the usefulness of online documentation - I supply fpGUI docs online too
[http://fpgui.sourceforge.net/apidocs/index.html]. I just don't see it as my primary source for help - more as a [maybe useful] addition. When I work with documentation I require much more functionality than what online HTML docs can provide.

Regards,
- Graeme -

Reinier Olislagers wrote

Had a look at the sourceforge site for Lazarus but couldn't find any pregenerated HTML docs... except old ones for Laz 0.9.30.4:

With fpGUI you have the generated INF files for each release. There is also online HTML versions for each release.

http://fpgui.sourceforge.net/apidocs/index.html

The 'apidocs' link always points to the latest released version (I'm generating the v1.0 release docs for the website now).

There are also release specific ones online.

http://fpgui.sourceforge.net/docs-0.4/
http://fpgui.sourceforge.net/docs-0.7/
http://fpgui.sourceforge.net/docs-0.8/

Regards,
- Graeme -

First world? I thought you were in England? **

Leaving aside the performance issues, I think that the one area in which online docs are pretty much indispensable is that in principle they allow user annotation. However I think a big question is the extent to useful contributions could be folded back into the original XML (or whatever) without an inordinate load on the maintainers.

Apart from that, I do wish that you'd stop going on about .inf and its superiority: Lazarus doesn't use it so this isn't the place to discuss it. And I also wish you'd stop mentioning OS/2, at least when people might be eating :-)

** BT's backbone, which most ISPs use for ADSL, is susceptible to overnight outages. Be, which some use as an alternative, is more susceptible to outages of a minute or so at random times. Yer pays yer money and makes yer choice.

Location has nothing to do with it. For work, I visit a lot of factories, and while some might have some wireless in office area, the workfloor has none. And even if they have, if one only visits occasionally, getting credentials is usually too bureacratic.

Mobile internet reception is also flakely (usually have to go outside to get some signal due to steel in the structure, if you are permitted to take a phone into the factory begin with. Since the advent of camera phones, wanting that marks you as an industrial spy it seems).

Don't get me wrong, for serious cases we always manage to get connected, but it requires effort and time. (permissions, going outside etc) It is not something you do to look up what %xxx to use in a format() argument string that you might not use everyday.

Moreover in general as a small western country, the Netherlands is considered as quite decently connected, specially wrt mobile coverage.

Since both CHM and INF viewers are under our control, it is not a real problem to begin with.

Anyway, can we _please_ all agree that we need both online and offline docs. I think the proponents of online docs better work on improving the online experience, rather than declare it perfect ex ante.

Reinier Olislagers wrote

>> So please, please, no something "proprietary". Note: fpdoc can also generate plain html files from the fpdoc sources if told to do so, so you can generate not only CHM,PDF,INF but also HTML and I believe TeX.

Of course, that is a main use (for the FPC and Lazarus online docs, and in the past, before CHM, also for the textmode IDE).

The CHM support is basically the html support that overrides the html class how references are rendered, and keeps some extra administration to generate the additional structures.

The main reason to do CHM was that the loose HTML was a burden to support on end-user computers.

Probably if you extract the CHM it is nearly 1:1 with the online docs except that cross-package links are different (ms-its://package.chm/ vs ../packagename/) and the extra XMLs for the CHM functionality. (some CHM minor functionality is binary, and thus not extractable)

Marco van de Voort wrote

Anyway, can we _please_ all agree that we need both online and offline docs. I think the proponents of online docs better work on improving the online experience, rather than declare it perfect ex ante.

Only if we also agree that the Lazarus default offline docs format is chm (not inf), and we also work on the improvement of offline docs; e.g. bugs
23410 No context-sensitive help for control on form 22880 LCL.CHM: Application.Terminate shows empty page 22765 Lhelp: clicking on hyperlink doesn't do anything despite hand cursor icon
22763 Lhelp: Search can't find GetPart while it is in Index 22754 Context-senstive help for 'result' gives 'No help found for this topic'

I mostly checked the html backend for regressions since the last major build (just before the 2.6.0 release, fpdoc sources december 2011). Quite a lot was merged in after that. I did a similar session last summer too (for 2.6.2RC1), but that lead to acceptable docs, not perfect docs.

I don't understand how Michael was able to generate the 2.6.2 online docs fully linked, unless he also used something known good fpdoc (from dec 2011 or so).

Anyway, what I did in detail.

- First, don't start with the LCL, but with the FCL.
1) it is much smaller (and thus quicker) and easier to debug
2) it still has external dependencies (to rtl)

only when it compiles under gdb with all the debugoptions below enabled, AND sizeof(fcl)>= sizeof(last good fcl, dec2011) continue with lcl

- Compile FPC trunk and install it.

- Compile only the fpdoc parts (fcl-passrc and fpdoc) with as much runtime debug options as you can find
( I used " -Sa -gttt -CROriot -dHEAPTRC_EXTRA -gw2l -viwn -Sg -Cppentiumm -dinheritancewarnings" under freebsd/32)

- get the fpdoc commandline from running the script (the above build_lcl_chm.sh or fixdocs.sh in
FPCs case). In LCL's case we also reuse the output of this script (generated as docs/html/lcl/inputfile.txt )
- set up a ~/.gdbinit as follows:

file <path to binary fpdoc>
set language pascal
set args <fpdoc arguments>
b fpc_raiseexception

- In LCL's case, copy the fpcdoc content files (.xct) to docs/html infs too if the inf backend needs them present.
- Change to the correct directory (fpcdocs/ or docs/html/lcl (or lazautils)
- run gdb and go directly to (r)un.
- if exceptions pop up, do a backtrace(bt) and fix them. Not all exceptions are catastrophic (i.e. abort program), seems fpdoc writers like to open files without checking first and handling the exception if needed. I fixed some of those, and also in gettext. If you find non catastrophic exceptions, root them out, it will make debugging easier in the future.

The main reason to do it this way is that the runtime checks (specially -gttt and -CR) are more likely to cause it to happen nearer to where the problem is, as opposed to where the corruption causes an exception of its own. It is very, very powerful, and whoever implemented this (Jonas for -gttt I believe) did extremely good work. I would wish I had it in Delphi. It also makes unittesting much more worthwhile, since it also uncovers errors that generally make no problems.

In my case the problems were twofold:

- In fcl-pastree, classes have been separated into baseclasses and descendents. However the backend code still checks like aclass.classtype= TSomeClass, but TSomeClass now also has descendents. So it should be aclass.classtype.inheritsfrom(TSomeClass).
Check all TPasModule and TPasClasstype occurances not in declarations or casts.
- In some places the original class is now one of the baseclass descendents, but the whole family (baseclass+descendents) is still casted to the original class. In most cases this is no problem, but in some it access fields on in the descendent. The classtree code in particular suffered from this. (probably because it is the newest)

beside this there were common programming errors (like variables that are used unintialized in some codepaths) -gttt again....

There was also the already mentioned (on fpc-devel) weird non-error:

procedure xxx(out sss :someclass);
begin
 // sss not assigned.
end;
var t : someclass;
t:=someclass.create
xx(t);
// xx is now randomized due to -gttt while without it, it still points to t.

That's not for me to agree on, but I can say that my patience won't last forever. The same with the fact that the IDE docs are still only in wiki, and there is no progression there either.

IMHO the IDE docs should be taken offline (or readonly), and quickly reformed to some master format, and managed in SVN, versioned, like the rest of the docs.

I think that needs to happen anyway, even if online is kept leading, just to get proper versioning.

22754 is difficult. result is not a keyword, but a pseudo variable, and its existence depends on context. So you can't simply add it to the keywords (ref.kwd), and it is not declared in each function either.

I've no lhelp experience. I mainly did the CHM docs for the textmode IDE (since the html-only help was an hassle), and provide the LCL one as a courtesy.

Btw, I see I used lazarus 1.1 as a source for these docs. Should there be a 1.0.x version too? What is the branch?

Marco van de Voort wrote

On Sun, Apr 21, 2013 at 01:43:21PM +0200, Reinier Olislagers wrote: IMHO the IDE docs should be taken offline (or readonly), and quickly reformed to some master format, and managed in SVN, versioned, like the rest of the docs.

Good idea; as long as they can be as easily edited as on the wiki... but we already had this discussion, so let's not repeat ourselves ;)

I think that needs to happen anyway, even if online is kept leading, just to get proper versioning.

If you take versioning as matching a certain Laz version with a certain help document, I do agree, but that would need to be done for FPC as well, IIUC.
As for the version control interpretation of versioning (the one I think you mean): no comments except a reference to our earlier discussion on this point...

22754 is difficult. result is not a keyword, but a pseudo variable, and its existence depends on context. So you can't simply add it to the keywords (ref.kwd), and it is not declared in each function either.

What happens if you do add it to ref.kwd with the caution that it works only with objfpc & Delphi modes?

Ok, it will give false positives in procedures and TP code, but that may be better than not giving any help.
Anyway, I'll leave it up to you experts ;)

I've no lhelp experience. I mainly did the CHM docs for the textmode IDE (since the html-only help was an hassle), and provide the LCL one as a courtesy.

Neither did I before I got some patches in ;) Also, I wasn't singling you out here, just promoting these mantis issues hoping somebody is interested.... and showing that offline help also needs improvement.

Oh & thanks for the LCL.CHM ;)

Actually, location has a lot to do with it. The UK (Conservative) government made a political decision to force ISPs onto NGN (21CN), the UK (Labour) government manipulated things so that the business went to Cisco and Huawei rather than to Marconi who were supplying the existing telecoms infrastructure, and the UK government (Conservative) continues to turn a blind eye to the fact that the dominant network has no resilience since it was rolled out before any network management infrastructure was in place. Let's just say that we see a bit more detail on routing issues etc. than most users do...

So I sympathise with people who temporarily find themselves unable to use wireless etc. due to local management issues, but the "Internet going down", i.e. there being no connectivity to a site, is something different that, sadly, UK users have to live with. And that's why we pay for connections to three different networks.

Reinier Olislagers wrote

> IMHO the IDE docs should be taken offline (or readonly), and quickly > reformed to some master format, and managed in SVN, versioned, like the rest > of the docs. Good idea; as long as they can be as easily edited as on the wiki...

That's not possible in a reasonable timeframe.

FPC does so since forever, since it only uses the wiki as it should be: public writable dumping ground for the more esotheric and/or short-lived topics.

Every release comes with full offline docs in dist/<version>/docs/

True, it isn't versioned (branched) in SVN (and I like to see that change, for about a decade now), but that is a relative minor issue.

As for the version control interpretation of versioning (the one I think you mean): no comments except a reference to our earlier discussion on this point...

I mean both.

Any result identifier will point to this. Also when it is not an implicit returnvalue, but e.g. a fieldname.

Ok, it will give false positives in procedures and TP code, but that may be better than not giving any help.

It will also give false positives in other modes.

I've concatenated all warnings and errors in a log:

http://www.stack.nl/~marcov/docbuilderrors.txt

Some remarks:

- Some of it might be due 2.6.x <-> trunk issues though. (bytesof?)
- There seems to be a problem with enumtypes. Many errors are enum values
- Importing operators seems to go wrong, and generates a slew of errors for all that import the RTL contents file (FCL/lazutils/lcl)
- links are casesensitive afaik.

I'll be trying to fix some of them (most notably in rtl).

Mark Morgan Lloyd wrote

First world? I thought you were in England? ** ** BT's backbone, which most ISPs use for ADSL, is susceptible to overnight outages. Be, which some use as an alternative, is more

I am, and use VirginMedia. There uptime in my area has been pretty good
- considering what I am used to in South Africa. I've only had two outages in a year. In the first case it was for a morning, and the last one was for an hour.

Leaving aside the performance issues, I think that the one area in which online docs are pretty much indispensable is that in principle they allow user annotation.

Uh? I can't annotate any online docs... Also if they did give me access, why would somebody else want my personal notes? I add annotations to RTL to explain things better (for myself), list pitfals or gotchas, add extra code examples etc. Probably things other developers wouldn't find useful at all, so I wouldn't want those in a public site.

Lazarus doesn't use it so this isn't the place to discuss it.

I don't care what Lazarus (as a project) does, but DocView integration with Lazarus IDE, or any other IDE is very simple to accomplish. There is even a link to DocView integration documentation included with Lazarus as standard (Help -> Online Help, read the 'Offline Help' section). You may not find DocView useful, but many other developers do, especially considering how bad the wiki help (searching) is, or the terrible functionality of LHelp.

Anyway, this thread is straying now...

Regards,
- Graeme -

Mark Morgan Lloyd wrote

> And I live in a first world country (finally) - but not even such > countries are immune to internet outages. First world? I thought you were in England? **

I forgot to mention in my previous reply. No matter how reliable or unreliable your internet connection might be. Even if the average outage is just 30 minutes... If you wanted [online] help during that time, you are stuck (can't even email somebody either). With _any_ offline help system you continue working as normal.

Anyway, I agree with Marco here... Online help might have its uses, but it simply can't be the sole help system.

Regards,
- Graeme -

Reinier Olislagers wrote

Only if we also agree that the Lazarus default offline docs format is chm (not inf),

Can you please reference where it states that? ;-) As far as I know the Lazarus project is reluctant to decide on any offline help format. Lazarus (Help -> Online Help) also reference both CHM and INF help for offline usage).

I don't even use LCL, but at least I do supply LCL.inf docs for those that want to give that help format a try. Unfortunately I found it impossible to generate a newer version of LCL - the help build system is currently broken (at least last I tested - a week ago).

and we also work on the improvement of offline docs; e.g. bugs

I have a solution, but you are probably not going to like it... DocView ;-)

Regards,
- Graeme -

Marco van de Voort wrote

IMHO the IDE docs should be taken offline (or readonly), and quickly reformed to some master format, and managed in SVN, versioned, like the rest of the docs.

I can't agree more.

and provide the LCL one as a courtesy.

Same here. Also why I am curious how you managed to build the LCL docs yesterday.

Regards,
- Graeme -

Run e.g. the official Windows installer. Open Lazarus, go to a keyword, press F1; alternatively just click Help. See the results.

I know you think .INF/DocView is superior. Could be, but it's not the default Lazarus help format/viewer.

Lazarus (Help -> Online Help) also reference both CHM and INF help for offline usage).

Well yes, that's because you kept spamming that wiki page. Seriously, enumerating reasons why people should switch to .inf on a "how to install help" page strikes me as rather desperate.

Reinier Olislagers wrote

Run e.g. the official Windows installer. Open Lazarus, go to a keyword, press F1; alternatively just click Help. See the results.

just because some develop spammed the mailing list enough, that it now automatically builds LHelp. That solution only seem to work on Windows then, because it sure doesn't work here on FreeBSD. F1 takes me to the online help, and I use Lazarus 1.1. Also how old is the Lazarus project, and when did they finally notice that offline help could be useful (a year ago vs >10 year old project).

Anyway, lets just agree to disagree, on whatever it is we are supposed to be arguing about.

Regards,
- Graeme -

Disingenous? The default help format for Lazarus; but yes, let's agree to disagree ;)

It is Sunday, aren't you guys supposed to be enjoying yourselves and taking advantage of the intermittent sunshine. LOL.You'll learn to appreciate that better, Graeme !!

Frank Church wrote

advantage of the intermittent sunshine. LOL.You'll learn to appreciate that better, Graeme !!

Having kids one is up early every day. Already been out Trikking for an hour this morning, did some gardening, fixed the fish pond, help my son with home work... now it's time I relax and argue on the mailing list. ;-)

Regards,
- Graeme -

I found another problem. Seems that in the past TPasElement.GetModule walked the parent dependencies and delivered the module for any paselement. Not anymore.

This specially affects shortdescriptions, since they need the module to resolve, and is often called with .getmodule as argument.

So the (other) backends might need to be fixed for that too. I'll update the snapshot as soon as it finishes building.

Marco van de Voort wrote

This specially affects shortdescriptions, since they need the module to resolve, and is often called with .getmodule as argument.

I know the HTML backend has very different code to the Linear output writers (Latex, IPF, RTF etc). I don't have problems with resolving links, cross-linking or hierarchy generation in IPF output.

My issue was that fpdoc crashed while I tried to build the LCL docs (all output formats). I believe you found the cause - the build_lcl_docs.lpr which also iterated over fpmake.pp units. Was this fixed in the Lazarus repository?

Regards,
- Graeme -

I also don't understand why I constantly find such coarse errors everytime I dive into fpdoc. As said, I don't understand how Michael managed to generate the 2.6.2 output (which generally looks fine)

The html output is much richer though than the Latex output (and afaik also the IPF one the last time I checked).

The above shortdescrs are the texts after links in the see also section btw, and also used in other places.

My issue was that fpdoc crashed while I tried to build the LCL docs (all output formats). I believe you found the cause - the build_lcl_docs.lpr which also iterated over fpmake.pp units. Was this fixed in the Lazarus repository?

No. I still had problems later, and worked around it in the backend, by checking every use of xxx.interfacesection with assigned() first.

I just do "make alldist" ? I never do tweaking ?

The html output is much richer though than the Latex output (and afaik also the IPF one the last time I checked).

This is normal. Printed and Online docs should not look the same. I may need to do some efforts to improve PDF output, though.

Michael.

But with what fpdoc ? Did you generate 2.6.2 docs with trunk fpdoc ?

For me it was totally broken, and many, if not all, of those issues should also have touched html output. (read this branch of the thread back to see what I fixed, and that is only last weekend's session)

It's normal for Latex. It's one of the things I didn't like about IPF output the last time I checked though.

It was a bit as the html attempt of Mr Walter posted ( http://codebot.org/bare/default.html ), constantly having to switch between right window and left window to browse. That is counterintuitive.

Yes, I always do.

Michael.

Marco van de Voort wrote

But with what fpdoc ? Did you generate 2.6.2 docs with trunk fpdoc ?

I generated FPC 2.6.2 RTL and FCL docs about a week ago, using the fpdoc from trunk. It worked fine here. Just did the usual:

make rtl.chk fcl.chk HTMLFMT=ipf FPCSRCDIR=/path/to/fpc

Yes the HTMLFMT option is a bit weird, but my Makefiles skills are limited, and it was easier to tweak (years ago) the build process of HTML output.

I would much prefer fpdoc project files, even for RTL and FCL. They work really well for fpGUI docs.

The IPF output has slightly more linking and different look to the Latex output - even though the IPF output is based on the Linear writer. I don't want the look of CHM though (standard HTML converted to CHM doesn't work) - I find that a bit over crowded, and lots of the links have no meaning in CHM (though it suits HTML with popup windows). The Latex output is very neat, and I wanted to keep that style with IPF (which I consider a type of eBook).

Curious, when last did you look at DocView and say rtl.inf? I just uploaded new binaries of both onto SourceForge.

Regards,
- Graeme -

Graeme Geldenhuys wrote

Curious, when last did you look at DocView and say rtl.inf? I just uploaded new binaries of both onto SourceForge.

It has been a while, which is why I added "last time I checked", probably in the 2.6.0 run up. I don't follow the docview stuff closely, since frankly, I don't see the point of it.

It was just that Mr. Walter's page reminded me of a certain behaviour that I associated with my last .INF tests, namely that you can't browse e.g. an unit or a class without constantly changing lemmas in the treeview/index pane.

IOW I like that a lemma is browsable internally, without going to other windows. It should be to test that assumption for current .INFs yourself.

I'm pretty much flabbergasted. Here it didn't even run through without exception (in the FCL docs), and when those were fixed, the input was less that 75% of the 2.6.0 iteration.