I've never got into the habit of using Lazarus help, but have just revisited it because of an extra user here who's asking "awkward questions" :-)

At a minimum, please could somebody review what I have done since I've made a couple of minor edits to the Wiki page which is referenced by the Lazarus IDE Help -> Online Help menu entry.

I've edited the Wiki page
http://wiki.freepascal.org/Installing_Help_in_the_IDE adding text that explicitly notes that adding Kylix helpfiles or additional .inf files are options. This was discussed in this list several months ago, and I believe that it was agreed that any suggestion that Lazarus /requires/ Kylix helpfiles is unwise.

I note that the final link from the IDE goes straight to installing help for fpgui. Is this really appropriate, and if it is why aren't there links there to comparable instructions for GTK etc.?

I suggest that the Kylix-related stuff in
http://wiki.freepascal.org/Installing_Help_in_the_IDE would actually be better on a page of its own, or moved right to the bottom of that one. What somebody ending up on that wiki page needs to see is getting local help for the RTL/FCL/LCL etc. working, not a screed on how to repurpose somebody else's files that's non-portable since it relies on proprietary software (HyperHelp).

Finally, and particularly if somebody doesn't like my changes, I suggest that while having the IDE point to a Wiki page is reasonable it would probably be wise to protect it from casual editing: Lazarus help is a sufficiently contentious issue without having new users confused because somebody has broken a link.

Hi Mark,

Mark Morgan Lloyd wrote

that it was agreed that any suggestion that Lazarus /requires/ Kylix helpfiles is unwise.

Such a suggestion was NEVER made! It was said that Kylix help _could_ also be used with Lazarus IDE and serve as Language Reference or VCL help (the latter being very similar to LCL, so was deemed useful at the time of writing).

I note that the final link from the IDE goes straight to installing help for fpgui. Is this really appropriate, and if it is why aren't there links there to comparable instructions for GTK etc.?

Feel free to add GTK help instructions to that page, if you think it would be useful.

I suggest that the Kylix-related stuff in http://wiki.freepascal.org/Installing_Help_in_the_IDE would actually be better on a page of its own, or moved right to the bottom of that one.

I think you are confusing the topic of that wiki page. It doesn't say FPC or LCL specific help, it says installing "help in the IDE" - thus any help files that the developer would find useful.

Some developers prefer Kylix help files, because they are actually a lot more detailed and useful than LCL help, plus they cover the Object Pascal Language Reference help too. Some find the INF help files much more convenient and faster. Some like CHM, and others like HTML. That wiki page is meant to describe how to install any such help file support in the Lazarus IDE.

I think the current focus on the CHM help files primarily - as the lhelp viewer is now included in the Lazarus bigide build - makes sense.

While that may be true, a focus in the page on installing FPC+LCL help does make sense as that is the help for the Lazarus IDE and programming language.

Yes, sections on how to install additional help packages could add value but should not be as prominently displayed, IMO.

IIRC, you asked Lazarus developers a good question some months ago: is there a standard help format and help viewer?
Again, IIRC, at that time the answer was: no, you can choose whichever viewer you want.
Meanwhile, lhelp has been included in the bigide build - tacitly answering your question now with "the default help is lhelp/chm".

Obviously, now Lazarus should be set up to take advantage of the inclusion of lhelp and provide chm help set up out of the box (as I'm sure people are working on).

I agree with your sentiments on different users wanting different things.... but:

Until we have built in working help (i.e. lhelp+CHM content), I think this page should be kept as straightforward as possible in order not to confuse new users. This means that getting CHM help content working with the default Lazarus help viewer, lhelp, should be the primary objective.

Besides that, it can mention how to get other forms of help going, but less prominently.

My 2 cents...

Reinier Olislagers wrote

Yes, sections on how to install additional help packages could add value but should not be as prominently displayed, IMO.

Sure, then keep the CHM install instructions as the first topic on that page, just don't loose the objective of that wiki page, and don't delete or talk down the other topics.

Meanwhile, lhelp has been included in the bigide build - tacitly answering your question now with "the default help is lhelp/chm".

Still no clear answer to me, but I get where they are going with that. Maybe in the next release they will announce it as "official". Still sad that the core team couldn't make a decisive decision in 10 years.

confuse new users. This means that getting CHM help content working with the default Lazarus help viewer, lhelp, should be the primary objective.

Yes, and also remember that there are many types of developers out there. I might use the Lazarus IDE, but I do not develop LCL applications. I also don't use CHM help formats. So the current information on that specific wiki page is very relevant to me. Also consider OS/2 users. There is no OS/2 API help in CHM format, *only* INF. So to anybody working on OS/2 or eComStation, the other information is relevant. Same could be said about the GTK remark earlier. If somebody has information on how to integrate GTK2 or Qt help formats into Lazarus IDE, because they use Lazarus IDE and Object Pascal to develop there GTK2 or Qt apps talking directly to those frameworks (not via LCL), then such information is also relevant to that wiki page.

The wiki page in question is all about "installing help files in the Lazarus IDE". If you want some "dummies guide" to getting LCL development going, then create a LCL dummies guide tutorial on the wiki and link the relevant information in.

Reinier Olislagers hat am 10. Juli 2012 um 12:27
geschrieben:

The Kylix help files are not available to every one. IMO the items available to every one should come first.

> [...]Some find the INF help files much > more convenient and faster. Some like CHM, and others like HTML. That > wiki page is meant to describe how to install any such help file > support in the Lazarus IDE.

True.

About standard help format:
For sources fpdoc is currently pretty much the standard. Nowadays it supports topics.

Meanwhile, lhelp has been included in the bigide build - tacitly answering your question now with "the default help is lhelp/chm".

lhelp has the lowest dependencies. It needs only one lazbuild call. I improved a few things in chmhelppkg to make it more user friendly.

Obviously, now Lazarus should be set up to take advantage of the inclusion of lhelp and provide chm help set up out of the box (as I'm sure people are working on).

It is still difficult to build all chm files. To be more exact: building the chm files is easy, building the input for the chm files is difficult. I guess the inf files have the same problem.
The next rpm/deb packages will contain lhelp and some chm files.

Mattias

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120710/c88974ab/attachment.html>

You are aware that this was meant more in the direction of

CHM vs. HTML vs. INF

?

All those can be generated using fpdoc ;)

Regards,
Sven

It's highly relevant on the wiki page, I'd suggest, or at least prominently linked. However it's not necessarily relevant on the IDE's Help -> Online Help page (in the section "Offline help"), and neither is a direct link on that page- which is a local file distributed as part of the IDE- to fpgui.

I want to stress what I'm talking about here (with the caveat that somebody might have updated trunk since my version). The trunk IDE menu entry Help -> Online Help opens a browser page to
/usr/local/share/lazarus-trunk//docs/index.html which has links to the FPC, LCL etc. docs that we all love. Somebody's added a section below that "Offline help" with two links, the first is
http://wiki.freepascal.org/Installing_Help_in_the_IDE#Installing_CHM_Help_for_The_RTL.2C_FCL_and_LCL_in_the_Lazarus_IDE which I think everybody agrees is relevant (even if it needs work), the second is a direct link to
http://fpgui.sourceforge.net/docview_ide_integration.shtml which- as part of a completely different project- isn't.

Just my 2d worth :-)

On 10/07/2012 09:59, Mark Morgan Lloyd wrote:

[my 3p]

+1 to have more prominent link to the
http://wiki.freepascal.org/Installing_Help_in_the_IDE page - my proposition : right below the DOWNLOADS link on home page, and have lhelp point to it when it can't find the help files.

+1 to include a mention of other help formats on that page

plus my own propositions :
++ provide cross-links to documentation packages across SourceForge download area, version-related to the appropriate install package, also
either
++ have a self-extracting exe that installs the [chm or html or inf] files in the path where lhelp expects them (on windows) or
++ include the help files of whatever choice, in the installation package (for windows)
and/or
++ have them packaged in rpm/deb/whatever for the linux distro of choice to be able to find main and doc updates automatically.

(reason : am I the only one that downloads and runs whatever the pre-packaged installable version is, rather than svn/git ???)

L.

Sven Barth hat am 10. Juli 2012 um 13:37
geschrieben:

Yes. :)

My point is that sources have almost a standard format, but that is not true for the rest.
The FPC docs uses latex, which is hard to refer to by fpdoc. The wiki and fpdoc can easily refer to each other, although there is currently no help editor that supports both, so you have to set the links manually. pasdoc does not seem to be used much.

The fpc messages are in a special format, that afaik can only be shown by fpc and the IDE. References are not possible.

latex can be converted to some degree to html, chm and inf.

fpdoc can be converted to html, chm, inf or shown directly. At the moment the fpdoc parser has problems with some FPC sources (nested types).

The wiki can be downloaded and converted to some degree to html and chm or shown directly.

All the above is very abbreviated and there are a lot of detail problems to solve.

Mattias
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120710/7236d15f/attachment-0001.html>

Mark Morgan Lloyd hat am 10. Juli 2012 um
13:44 geschrieben:

yes

the > second is a direct link to

http://fpgui.sourceforge.net/docview_ide_integration.shtml which- as part of a completely different project- isn't.

No, docview can show most of the stuff and has some nice features, which lhelp lacks.

It would be nice if the page would give more details how to create the inf files for RTL, FCL, LCL and all the other packages.

Mattias

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120710/e9d0b632/attachment.html>

Lukasz Sokol hat am 10. Juli 2012 um 14:17 geschrieben:

You are not the only one. I would even say, most people downloading the installers want some help files.
Most people also prefer one download instead of multiple downloads. So the help files should be included in the normal installers.

Mattias
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120710/22732a0d/attachment.html>

Hi,

The Kylix help files are not available to every one. IMO the items available to every one should come first.

I guess I don't understand your reply - what is the point your are trying to make? Are you just reiterating the fact that it is already like that on the wiki. CHM is already the first topic on that page, Kylix help is second from the bottom. When I added the INF information to that page, I simply added it to the bottom of the topic list. Somebody else since then added the Kylix info and so on.

The next rpm/deb packages will contain lhelp and some chm files.

That should help a lot of developers. For some time now I have also supplied pre-built binaries of DocView and INF help files on SourceForge. Many found it easier to simply download pre-built INF help files for FPC's Lang Ref, RTL, FCL etc than to get the sources and build their own.

Hi,

Ah, ok, now I understand what you are talking about - though I'm using an old version of Lazarus IDE, so I don't see what you see. Well, I don't have commit access to SVN, so don't guess some Lazarus developer thought the DocView + INF solution could be useful to somebody, so it was worth mentioning it. After all, I went through the trouble of building lcl.inf and making it available for download from the fpGUI file downloads section on SourceForge - and I don't even use LCL. I guess it's a simple case of "I scratch your back, you scratch my back". ;-)

Hi,

Mattias Gaertner wrote

It would be nice if the page would give more details how to create the inf files for RTL, FCL, LCL and all the other packages.

I'll see what I can add to that page, or maybe create a new page describing building of docs, then simply link to it from the IDE integration page. But as I mention earlier, most people seem to prefer downloading pre-built binaries and docs, and there is already a link to that.

Graeme Geldenhuys hat am 10. Juli 2012 um 14:54
geschrieben:

Yes.
Just in case someone wants to reorder the page or split it up. It's a community wiki - every one can do that.

CHM is already the first topic on that page,> Kylix help is second from the bottom. When I added the INF information to that page, I simply added it to the bottom of the topic list. Somebody else since then added the Kylix info and so on.

Yes. This is how open source works. :)

Can you build the inf files for the current FCL+RTL? I get some parser errors because of nested types.

Mattias
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120710/be64b37a/attachment.html>

Le 10/07/2012 14:30, Mattias Gaertner a ?crit :

+1
Yep,

Antonio.

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120710/c2c73ed5/attachment-0001.html>

Hi,

Mattias Gaertner wrote

Just in case someone wants to reorder the page or split it up. It's a

OK - I also think it is already good as-is. All related topics on one page and in a sane order.

Somebody else must have thought the same, because the original "Kylix help integration" wik page doesn't exist any more. All that information was merged with the single "Installing help in the IDE" page. It was a good idea.

Yes. This is how open source works. :)

I know. :)

Can you build the inf files for the current FCL+RTL? I get some parser errors because of nested types.

I haven't tried for a couple of months. I'll get the latest code and help source and try again. But if you do have problems with those, then it's probably an issue with fpdoc or more specific, the source code parser in FCL that is lagging behind FPC language features.

And believe me, we all appreciate your hard work :-)

One thing does occur to me, and that is that it would probably be appropriate if the Lazarus developers set up the .../docs/index.html page so that all Wiki links were to individual pages (even if the Wiki subsequently redirected these). That would ensure that minor changes to the Wiki, even though self-consistent, couldn't screw up the Lazarus IDE... after all they're separate projects so should have well-defined interfaces.

Point of information: you're obviously correct in pointing out that .inf files were used by OS/2, but IBM also used them for later versions of PC-DOS. I've also noticed recently that datasets with the same extension have a comparable function in at least some versions of IBM's CMS operating system: I've made no attempt to determine if the formats are remotely compatible (remote being the operative term, since the CMS ones are obviously EBCDIC :-)

Well, I didn't dare to propose this for 3 reasons :
- chm package is 16.3MB, adding to already heavy 78.8MB lazarus installer exe, not cool for some people who are bandwidth-challenged; If the plain-text html is the same content, that could be included by default, possibly.

- documentation updates - may they happen in between releases ? if so, it is easier to download docs as separate exe and just launch (under windows) or run 'sudo apt-get upgrade' (under *buntu for example) which happens automatically if set up so (not everybody has a taste or time for RSS updates ...)

- packaging / splitting requirements of different distros (you may heard of them)... requiring somebody to create a meta-package with correct dependencies (and maintaining it)

Oh and one more p from me :
++ default windows (xp) system installation does not include a program that can open .tar.bz2, please consider adding other options...?

Kind Regards,
L.

Hi,

Mark Morgan Lloyd wrote

That would ensure that minor changes to the Wiki, even though self-consistent, couldn't screw up the Lazarus IDE...

What do you mean my "screw up"? Meaning the wiki help which might describe the details of an IDE dialog (what I refer to as application help) doesn't exist any more? I can't say I have ever heard of a case where this has happened.

I don't know if it is possible. Some installers on windows do ask for options like this, and if selected download the required files.

Hi,

You raise some valid points, which might still be a concern today. I still get annoyed when I need to setup a Windows development machine. I would like a Lazarus binary release, but without FPC, because I prefer to keep my FPC source on par with the FPC Fixes branch. So I don't need the outdated FPC that is included with the Lazarus installer.

I was one of those poor souls that had limited bandwidth per month. That is why I offered the INF help and DocView to the Lazarus community. INF files + DocView binary is a mere 2.3MB download - and the INF help files contain all the same information as the other formats. Oh, and it is supplied in the ZIP format. ;-)

- documentation updates - may they happen in between releases ? if so, it is

As far as I know, documentation for LCL only follows Lazarus Trunk, so as soon as a release is made, the help for that release is cast in stone.

No, I'm looking at one, very specific, case. The Lazarus IDE includes an HTML file- I've already said which one several times. That is unarguably part of the IDE, it is not part of the Wiki which is in effect a separate project.

If somebody changes the headings in the Wiki page referred to by this one file, it effectively breaks the IDE. Now I know that some people will argue that point, but if a prospective user or- $deity help us- a journalist can't get to help information we all know who carries the can: it's seen as a shortcoming of the IDE, even if the change was elsewhere.

+1 (as they say), but in my case because I regularly find myself having to update e.g. the compiler on a SPARC system because of a CG change and then find that only a limited range of Lazarus builds are compatible.

/However/, I think a fair question at this point is whether an svn update has a higher or lower bandwidth and per-Mb cost than downloading a binary snapshot, and whether this changes as the number of development systems increase (specifically, because the same binary can be used for all machines with the same architecture but a directory under svn control has limited tolerance of being moved between systems).

Lukasz Sokol wrote

Oh and one more p from me : ++ default windows (xp) system installation does not include a program that can open .tar.bz2, please consider adding other options...?

And/or making sure that an up-to-date tar is available with MingW. I fairly regularly find myself repackaging archives to move between systems.

The page is a start page to give the user some hints where to start looking for help.
If you think the links are not persistent enough and you have some better links please post them so I can change them.

Mattias

The chms are basically the compressed html files.
The offline help was requested for users with limited bandwidth.

- documentation updates - may they happen in between releases ? if so, it is easier to download docs as separate exe and just launch (under windows) or run 'sudo apt-get upgrade' (under *buntu for example) which happens automatically if set up so (not everybody has a taste or time for RSS updates ...)

There are no plans for documentation upgrades for releases.

- packaging / splitting requirements of different distros (you may heard of them)... requiring somebody to create a meta-package with correct dependencies (and maintaining it)

AFAIK debian does that.
But the packages on the official download site (sourceforge) should be only a few files to download. Ideally: only one per platform.

Oh and one more p from me : ++ default windows (xp) system installation does not include a program that can open .tar.bz2, please consider adding other options...?

Yes, that should be zip.

Mattias

If people in this list could work something out, could the managers of the FP/Laz wiki (Vincent? Marco?) lock down the name(s) of one or more entry pages? In other words, even such that if somebody in the Wiki project edited content the IDE would still have intact links to jump to.

I've spotted at least one place in the IDE where F1 goes to a non-existent web page, which apart from anything else introduces an annoying delay while a browser loads etc.

I'll try to go through at least the more obvious parts of the IDE finding things like this, and then will raise it on Mantis.

If the point of CHM is that they use less disk space than unpacked HTML, (yeah, I see the point : lcl.chm 11.577MB, fcl.chm 1.968MB, vs unpacked HTML files that use 187MB) then I'd include this information somewhere on the wiki...

(e.g. see my latest edits to the 'Installing Help in the IDE page' - I wanted it to have some short and clear even if it does repeat itself, )

[...]

There are no plans for documentation upgrades for releases.

OK, so that's one less point of hesitation.

Yeah, debian/ubuntu among others. We don't want to miss being included in Debian do we ;) by not complying to their policies :J

Thanks :)

Mattias

(how do you insert footnotes within wiki section...)

Lukasz.

Well I am much less adventurous :J
this is the IT_industry-age-old debate of 'is worse better'.

To you developers of the tool, worse is indeed better. To users who use the tool, they need something that produces /stable/ results and behaves predictably, even if it's limited.

(I admire the process Linus T. has created for Linux kernel reg. stable releases : I keep wondering why more software projects don't jump the bandwagon ;) even thou you get 'go download a newer kernel will ya' thrown at if you ask them about kernel 2.6.24 :J )

Yeah I thought I saw the p^W^Wyou mentioning it.
I grew up on a 115200 symmetric link ;) and on a 56k modem before that. http://pl.wikipedia.org/wiki/HIS (sorry it's in polish - this solution was used probably nowhere else in the world according to this page ;) even the Russians knew better :J )

Well I am not disk challenged, and I don't like to wait ;) html suits me (and if anything, I don't need external programs, ff will do ;)

L.

On Wed, Jul 11, 2012 at 09:53:59AM +0100, Lukasz Sokol wrote:

( very old message, ran into it by accident while searching for something else)

If the point of CHM is that they use less disk space than unpacked HTML, (yeah, I see the point : lcl.chm 11.577MB, fcl.chm 1.968MB, vs unpacked HTML files that use 187MB) then I'd include this information somewhere on the wiki...

There are multiple ways in which chms are superior to the raw material:

- Primarily they are compressed, and can be used as such (html decompression on plain dos can take hours)
- Indexing, TOC and search is better.
- cross package hyperlinking is file position independent. IOW FPC and LCL helpfiles don't have to be in the same directory to link to eachother (plain html simply does ../<packagename> for all unresolved links)
- The code to use the helpfile is filesystem independent. In the past quite often subtle filesystem related bugs (like wrong directory separator) came to light only after release(*)

(*) specially on Dos. Dos-under-Windows is more lenient than standalone dos.

Note that the html inside the CHM is 99% the same, but not entirely. Using one base html for both is not really practical atm. All references between packages would break.

ACK, thanks for the info.

Lukasz