I normally build Lazarus from svn, targeting bigide, so I'm not sure that instructions that tell me to download prebuilt binary .chm files are relevant to me. However, if I could ask two questions here about the mechanics:

a) Assuming that ChmHelpPkg is loaded but lhelp is not compiled. Since the new version of Lazarus might not yet have been run, is there an idiot-proof way of telling lazbuild what Lazarus directory etc. is to be used when building lhelp.lpi?

b) What is the easiest way of integrating .chm files for the RTL etc., to the extent that context-sensitive help works for things like Format()? Again, if I'm building FPC from source I presume it makes more sense to generate these locally (unless it expects lots of Latex handling or equivalent).

Finally, if I just want to add a few lines of plain text as context-sensitive help for a control or form, with the main documentation having been prepared by e.g. Lyx and saved as a .pdf, what's the way to do this?

Mark Morgan Lloyd wrote

I normally build Lazarus from svn, targeting bigide, so I'm not sure that instructions that tell me to download prebuilt binary .chm files are relevant to me.

I may be wrong, but as far as I know doing a 'make bigide' will not build the help files, just the LCL and IDE. Well that is how it works here with 0.9.30.x - I don't know if Lazarus Trunk has changed this.

b) What is the easiest way of integrating .chm files for the RTL etc., to the extent that context-sensitive help works for things like Format()?

See, that is where CHM help lags behind, and why I mentioned INF some time back. The way DocView integrates in the IDE (via the External Tools menu, and not as a compiled in help-interface to the IDE), I can get Object Pascal language help no problem. The CHM help (and the other compiled help-interface addons to Lazarus IDE) only works well for class / API help. The built-in Indexing and Full Text Search of INF help makes in a no-brainer to find the correct help topic from a keyword search.

You must remember that there is a difference between FPC's Language Syntax help (built from LaTex and primarily targets PDF output) and the Class / API help (built from XML files).

Finally, if I just want to add a few lines of plain text as context-sensitive help for a control or form, with the main documentation

Which one is it? Control or Form? If it's a Control, then it falls under the Class / API help, which means XML files must be edited. If it is a Form (as in application help describing a dialog in your application), then it's something else. For the latter case, I don't actually know what is the recommendation for application help with LCL based applications. For fpGUI based applications, it is an IPF plain-text file (the help source which gets compiled into binary INF help).

If you are referring to the help viewer, then again, that is where LHelp lags behind. DocView allows you to annotate (add inline comments) any INF files. Those annotations are stored in a separate file (<helpfile>.notes), which you can move around or copy with the INF file to a new computer if you want. LHelp has no such functionality.

You're right, but "bigide" explicitly includes ChmHelpPkg (i.e., if I understand things correctly, the various viewers) while "all" doesn't.

Right, so stop crowing about it FFS and just say HOW TO DO IT. Then somebody else can come along and demonstrate that a .chm is no more difficult.

So presumably that's where the (Lazarus) IDE's FPDoc editor comes into it?

Noted, but I'm using Lazarus (and this /is/ the Lazarus mailing list, so please don't act all surprised :-)

Hi,

Mark Morgan Lloyd wrote

You're right, but "bigide" explicitly includes ChmHelpPkg (i.e., if I understand things correctly, the various viewers) while "all" doesn't.

As far as I understand it, that simply registers CHM help with the IDE, and gives the IDE a default location of where to find LHelp. And with newer Lazarus IDE versions, the IDE will automatically try to compile LHelp if the executable doesn't exist. This still doesn't compile/generate any of the CHM help files themselves.

Right, so stop crowing about it FFS and just say HOW TO DO IT. Then somebody else can come along and demonstrate that a .chm is no more difficult.

:-) I've explained this many times before, and then created a web page to stop repeating myself.

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

I have to add that when DocView does a keyword search, it uses an advanced search result algorithm and rating system, to try and make a "best match". It even does spelling variations to the keyword. So I believe this helps a lot in the result DocView gives after pressing F1.

So presumably that's where the (Lazarus) IDE's FPDoc editor comes into it?

Correct. But remember, that when you add comments, they become part of the documentation. You cannot disable or switch off "user added comments" at a later date.

Noted, but I'm using Lazarus (and this /is/ the Lazarus mailing list, so please don't act all surprised :-)

I know that all too well. :)

My question still stands though. I don't know what is the recommendation for "application help" with LCL based applications. eg: I create a new project which is a new Programming Editor. I want to supply a end-user help file with my binary - like all good software does. What help file format do I use (as the developer of that product), and how do I create/edit that help file?

Now if you tell me CHM, that means I need to ship LHelp with my product because Linux & Mac users don't have CHM help viewers out of the box. But what is the source help format for CHM, and what tools (help editor) do I use to edit that source format, and what tool do I use to "compile" that source help format into the end result CHM file? Also, how does my product know where to find LHelp (or whatever CHM viewer I want to use)?

make bigide does not include chmhelppkg. You have to pass OPT=-dUseCHMHelp to do that.

Correct.
The docs have references to the RTL+FCL docs, which are outside the Lazarus sources and have references to programmers guide, which requires latex. The whole doc build chain has too many dependencies and need several minutes to build. That's not feasible for a simple make command.

There is a feature request to hide comments when there is an fpdoc entry.
And there is a feature request to support the new fpdoc notes. I don't know the state of the annotation system.

I can't help you there.
Same for what image format to use, what installer to use, what version control system or what upgrade system.

Mattias

Agreed, and the various wiki pages etc. do appear to stress that the final conversion of files to .chm is still work-in-progress (with caveats on alignment etc.).

Relevance noted, will revisit. In that pretty pictcha of yours, should FPCHELP be decorated with a $ to indicate it's a shell variable?

[Nod] I suspect that we're not the only people asking for guidance.

Now if you tell me CHM, that means I need to ship LHelp with my product because Linux & Mac users don't have CHM help viewers out of the box.

Good point. But at the same time most unix-style OSes can't read .inf, so one would need to bundle docview or whatever. Which I think suggests that an important point is having a flexible and foolproof document generation process, which can produce .inf, .chm or whatever... basically, any format where a viewer can jump straight to the relevant section (which specifically excludes .pdf, for this role).

[Nod] I suspect that we're not the only people asking for guidance.

Hello,

fpc has chm "compiler" classes to make CHM files.
TChmProject is in chmfilewriter unit and TChmWriter is in chmwriter unit (both in packages\chm\src\).
And there even is a GUI app to make chm files somewhere in Lazarus or fpc examples :) I don't remember where exactly, because I did make my own chm help maker application (it took about a day using existing chm writing functionality) before I discovered that existing one. BTW I posted my chm maker (app with sources) about two years ago on this (or fpc) list ;)

Regarding LHelp - I myself package LHelp executable with the main app and help files so I know that LHelp is besides main app. You can register your help format system-wide and install LHelp in a different place from your app - as with any other file viewer your app may need :)

Regards,
?ilvinas

On reflection, in both cases I think I mean context-sensitive help in the context of an app. In other words: either F1 on say a toolbar button or an edit field, or a button labeled "Help" which describes a form. I'm definitely not thinking about documentation for a new control, to be displayed in the IDE.

I think .chm can be generated from DocBook (hence from e.g. Lyx), but one is rapidly getting to the point where there is more documentation software than development software on your computer. I've seen mention of something called DITA Open Tools but again it appears pretty heavy.

I made using bigide, and the package was in the installed list. I still had to build lhelp manually.

So what's best to do here: download them as binaries and install where/how?

Mattias Gaertner wrote

And there is a feature request to support the new fpdoc notes. I don't know the state of the annotation system.

I personally thing that is tackling the problem from the wrong end. I definitely don't want other peoples annotations in my help documents. Such functionality needs to be added at runtime by the docs viewer. Just my 2c.

I can't help you there. Same for what image format to use, what installer to use, what version control system or what upgrade system.

OK, then forget about me. :) What help do you use in your applications
- what help format and help editor do you use?

See ide/lazarus.pp
Maybe you are confusing "installed" lists?

I still had to build lhelp manually.

Check if you have local modifications. In trunk the makefile target bigide includes lhelp.

Download the chm files and put them into "yourlazarus/docs/chm/".

Mattias

Hi Mark,

Mark Morgan Lloyd wrote

Relevance noted, will revisit. In that pretty pictcha of yours, should FPCHELP be decorated with a $ to indicate it's a shell variable?

No, DocView will handle that automatically. DocView can handle many types of parameters and all are tested when DocView starts up. eg: It queries the environment variables defined on your system for a match. Yes/No. Query if it is a directory? Yes/No. Query if it is a one or more help files without the .inf extension (in which case it then uses a predefined help directory/directories specified by the BOOKSHELF environment variable)? Yes/No. Query if it is a full path to a .inf (with the .inf extension). Yes/No. If still nothing, simply start up with no help file loaded.

DocView comes with its own extensive docview.inf application help file, which explains all this and much more.

[Nod] I suspect that we're not the only people asking for guidance.

And it seems everybody is reluctant to give an answer. I guess LCL based applications simply don't ship with help? Well, for the few LCL based apps I have tried (excluding Lazarus IDE), that sure was the case.

I just remembered form years ago when I still used Delphi 5 & 7, we used to use a product called HelpScribble to author our .HLP help files. HelpScribble now supports .CHM authoring too. So I guess that answers my own question. You need to purchase a proprietary CHM help authoring tool to generate your own CHM help, and you'll probably be limited to author those help files under Windows only.

I'm still fuzzy on how LCL based applications know which CHM help viewer to use though. This is especially important under Linux & MacOS because the free CHM help viewers available on those platforms have vastly different features and functionality. Some don't support searching, some don't have Index support, some don't support CSS etc etc. And I'm 100% sure they have different parameter options, so the LCL app needs to know what it can and can't pass the the CHM help viewer.

Good point. But at the same time most unix-style OSes can't read .inf, so one would need to bundle docview or whatever.

Correct, and I don't have a problem with that. What I was getting at is that different CHM help viewers support different features, and there command line parameters will differ too. So how does LCL based apps know how to tell each of those CHM help viewers that they must display Help Topic Index 1234, or Help Topic String 'MyDialog1', from the CHM help file of application X.

These are the most basic things that need to be address for an application help to have working application help. Amazing no LCL developer has come across this yet. Maybe the little bit I know of LCL is just too little. ;-)

Hi Mark,

Mark Morgan Lloyd wrote

On reflection, in both cases I think I mean context-sensitive help in the context of an app. In other words: either F1 on say a toolbar button or an

OK, then we are thinking of the same thing. :) Context sensitive help used in our own developed applications.

The subject of "context sensitive help" gets a bit confusing when it comes to something like an IDE, because in such a case you have "application help" describing the dialogs of the IDE, and you have Framework / API help for the programming language you are writing using the IDE.

I agree with the locality. The IDE is not a science project or critical apparatus. Annotations of the LCL docs and probably all packages in the Lazarus sources should be local.
I don't understand what you mean with "that is tackling the problem from the wrong end".

So far my other applications never needed an extensive offline help and therefore I do not dare to give an advice. I leave this to others.

Mattias

Hi,

Yes, annotations are a personal thing. I might annotate a help topic I struggle with, where somebody else could well have thought it pretty obvious, and needed no further explanation.

I don't understand what you mean with "that is tackling the problem from the wrong end".

I meant, in is not really the fpdoc XML files that need annotation support, it is the Help Viewers than need the support. The Help Viewers must be able to add annotations at runtime, store them locally, and separate from the original help files.

The other problems I can see that will happen with the Lazarus IDE's FPDoc Editor supporting annotations, is that if those annotations are stored in the same fpdoc XML files as the LCL, then somebody might submit those changes with actual LCL documentation fixes. Then the burden will fall on the Lazarus core team to make sure they don't accidentally commit such a contribution (somebody's personal annotations mixed with legit documentation bug fixes) to the repository.

So far my other applications never needed an extensive offline help

Lucky you! :)

Hmm. While I personally agree, that DocView in many aspects has a lot advantages, referring to the *big* discussion on that we had in this forum, I had the impression, that the "powers" decided, that - if any work is dedicated to improving the help system - that should be done for a (rather new) method that allows to use (online) Wikis as a source for offline files providing the advantage that there is a rather standardized and commonly accepted and ubiquitously available way to have users improve the help content.

I don't know how far this idea is advanced (e.g. regarding providing search capability across multiple help "chapters") right now and which and how offline help content files can already generated that way.

-Michael

I mean in the sense of the "If you are using Lazarus from Subversion" in the
http://wiki.freepascal.org/Installing_Help_in_the_IDE#Installing_CHM_Help_for_The_RTL.2C_FCL_and_LCL_in_the_Lazarus_IDE page which is cited by the trunk IDE's Help -> Online Help page: the instructions are accurate (it's only page and link organisation that I've been querying).

> I still had to build lhelp manually. Check if you have local modifications. In trunk the makefile target bigide includes lhelp.

Same applies.

OK, so I get
ftp://freepascal.stack.nl/pub/fpc/dist/2.6.0/docs/doc-chm.zip and unpack. The .txt file says copy the files to docs/html which I'm assuming is wrong, so I end up with .chm (etc.) files in /usr/local/share/lazarus-trunk/docs/chm and the Lazarus IDE picks them up automatically.

Congratulations and thanks to everybody who's worked hard to get the IDE to this point (and who's put up with my occasionally bull-headed questions).

I didn't make a note of the URL, but I noticed a Debian bugtracker entry yesterday where somebody was requesting that chmcmd/chmls be packaged separately since they're the only free tools that do the job.

The bottom line appears to be: generate either XML or HTML files, make a list of their names, and run the lot through chmcmd to produce a single indexed file. In principle, it should be possible to postprocess something like a .pdf to generate very simple context help entries (take any heading prefixed by e.g. ? as a help keyword, and the following paragraph as the associated text).

It is true that the chmhelppkg was included with some binaries and therefore many users had it preinstalled. But afaik it was never enabled by default in target bigide.

Try this:
make clean bigide
./lazarus --pcp=testconfig

If you don't have a components/chmhelp/lhelp/lhelp after doing a "make bigide", then please report the bug.

Yes, the paths are a little bit confusing.

Historically the default search path for chm files was docs/html. But this is a source directory. Mixing svn files and downloaded files is confusing. It is cleaner to put all downloaded files into a directory if its own (docs/chm).
The docs/html directory is still in the search path for compatibility.

Congratulations and thanks to everybody who's worked hard to get the IDE to this point (and who's put up with my occasionally bull-headed questions).

:)

Mattias

I'll revisit that on a clean system as soon as I'm able.

I've been working through this several times with the intention of putting Lazarus docs build (from source) plus FPC docs copy (from binaries) into my usual build/installation scripts, but am finding that the FPC (RTL etc.) stuff is only picked up intermittently. Is there a cache to be cleared somewhere or something comparable?

I see from the .txt file that RTL etc. help is supposed to not work in the Lazarus it doesn't not work all the time, on a couple of occasions it's been fine but I can't pin down the conditions.

OK, I can extract marked text from (plaintext derived from) a .pdf, save entries as individual html files with a title tag in the header, and build a .chm. Running chmls on the .chm produces sensible output.

So how do I integrate the .chm with a minimal Lazarus project to prove it works?

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

Just put the fcl, rtl, prog, ... chm files into docs/chm and lhelp will open them. Even links between them should work.

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

No idea...

Ludo's and my tool fpcup put the binary FPC docs chms and compile the Lazarus chms in the old location (lazarus\docs\html) which seems to work fine...
As (IIRC) Mattias explains elsewhere, using the CHM directory for chm files is a relatively new addition to Lazarus and the html location is also searched for compatibility's sake; our fpcup was running before that ;) (We might look into changing that for consistency.)

There is of course the settings on where to find the chm files in Lazarus tools/options/help options, CHM Help Viewer, HelpFilesPath. I suppose if you don't set this, Lazarus will look in html and chm; don't know if it also searches in chm and help you set this to a different location.

I see from the .txt file that RTL etc. help is supposed to not work in the Lazarus it doesn't not work all the time, on a couple of occasions it's been fine but I can't pin down the conditions.

You mean this text file:
lazarus\docs\html\readmechm.txt
Can't seem to find that, only this:
"Note that Lazarus does not load ref.* at this moment, so (CHM) help on keywords does not work yet."

BTW: perhaps that readme needs an update? It mentions various viewers for chm files which is nice to know if you want to have alternatives, but doesn't seem to mention lhelp at all - which should be available on all Lazarus platforms and be the default chm viewer for Lazarus anyway, right?

lhelp will open them manually, but keyword help in the IDE (e.g. F1 on begin or {$i) doesn't. I get IDE popups like 'Help keyword "FPCKeyword_begin" not found.

lazarus-trunk$ find . -iname '*chm'
./components/wiki/chm
./docs/chm
./docs/chm/toc.chm
./docs/chm/user.chm
./docs/chm/fpdoc.chm
./docs/chm/prog.chm
./docs/chm/fcl.chm
./docs/chm/rtl.chm
./docs/chm/ref.chm
./docs/html/lcl/lcl.chm

Add the ref.kwd file too.

Mattias

It's already there, I was only showing *chm to illustrate the overall layout. The complete list of files is

docs/chm/fcl.chm
docs/chm/fcl.xct
docs/chm/fpdoc.chm
docs/chm/prog.chm
docs/chm/readmechm.txt
docs/chm/ref.chm
docs/chm/ref.kwd
docs/chm/rtl.chm
docs/chm/rtl.xct
docs/chm/toc.chm
docs/chm/user.chm

docs/html/build_chm.bat
docs/html/build_chm.sh
docs/html/build_gtkintf_html.sh
docs/html/build_html.bat
docs/html/build_html.sh
docs/html/build_lazutils_html.sh
docs/html/build_lcl_chm.sh
docs/html/build_lcl_docs
docs/html/build_lcl_docs.compiled
docs/html/build_lcl_docs.lpi
docs/html/build_lcl_docs.lpr
docs/html/build_lcl_docs.o
docs/html/build_lcl_html.sh
docs/html/fpdoc.css
docs/html/libpbuild_lcl_docs.a
docs/html/localfclfooter.xml
docs/html/locallclfooter.xml
docs/html/localrtlfooter.xml
docs/html/Makefile
docs/html/README.txt
docs/html/sourceforgefooter.xml

docs/html/lcl:
inputfile.txt
lcl.chm
lcl.xct

Please try the files from here:
http://www.stack.nl/~marcov/doc-chm.zip

Mattias

RTL etc. keywords only work if Lazarus is started from the .chm directory. LCL always OK.

I've added a few lines to
http://wiki.lazarus.freepascal.org/chm_backend_for_fpdoc about where a list of options that may appear in a .hhp file may be found, and an example of a minimal .hhp and .hhc TOC file. Together, that should be enough for anybody determined to use chmcmd tp "roll his own" documentation from an obscure documentation format or CMS repository.

Am I correct in that there isn't yet a .chm viewer that can be integrated with a user-written app?

Should I Mantis this to make sure it's not overlooked?

Help on "begin" works fine under Linux.

Can it find ref.chm? (See debug log)
If not, what search paths do you see?

Mattias

Well it doesn't work reliably here. Debian x86 Linux, ablutions-standard system.

Can it find ref.chm? (See debug log) If not, what search paths do you see?

My test code fragment (with line numbers):

42 {$R *.res}
43
44 begin
45 Application.Initialize;

Hitting F1 on 'Application' console shows:

TIDEHelpManager.ShowHelpForSourcePosition A
Filename=/usr/local/src/heavywethers/trunk/HeavyWethers.lpr x=6,y=45 TIDEHelpManager.ShowHelpForSourcePosition B Success 1 TIDEHelpManager.ShowHelpForSourcePosition C
/usr/local/share/lazarus-trunk/lcl/forms.pp X=3 Y=1706 TIDEHelpManager.ShowHelpForSourcePosition D PascalHelpContextLists.Count=1 THelpDatabase.GetNodesForPascalContexts C
FileItem.ClassName=THelpDBISourceDirectory
Filename=/usr/local/share/lazarus-trunk/lcl/forms.pp 1 TFPDocHTMLHelpDatabase.ShowHelp A Unitname=forms NewNode.HelpType=1 NewNode.Title=LCL - Lazarus Component Library Units NewNode.URL=file://index.html
TFPDocHTMLHelpDatabase.ShowHelp Filename="application." UnitName="forms" TFPDocHTMLHelpDatabase.ShowHelp BaseURL of Node.URL="" TFPDocHTMLHelpDatabase.ShowHelp GetEffectiveBaseURL="lcl.chm://" THTMLHelpDatabase.ShowURL B URL=lcl.chm://forms/application.html URLType=lcl.chm URLPath=forms/application.html URLParams= TChmHelpViewer.ShowNode Filename="lcl.chm"
SearchPath="/usr/local/share/lazarus-trunk/docs/html/lcl" Found="/usr/local/share/lazarus-trunk/docs/html/lcl/lcl.chm" Xlib: extension "RANDR" missing on display "localhost:10.0".

Without killing lhelp, moving up to 'begin' and hitting F1:

TIDEHelpManager.ShowHelpForSourcePosition A
Filename=/usr/local/src/heavywethers/trunk/HeavyWethers.lpr x=3,y=44

The left pane on lhelp is only showing the lcl entries.

Killing Lazarus and starting in /usr/local/share/lazarus-trunk/docs/chm which contains

-rw-r--r-- 1 markMLl markMLl 19177753 Jul 14 12:45 doc-chm.zip -rw-rw-r-- 1 root root 1645513 Dec 28 2011 fcl.chm -rw-rw-r-- 1 root root 129232 Dec 28 2011 fcl.xct -rw-rw-r-- 1 root root 100171 Dec 28 2011 fpdoc.chm -rw-rw-r-- 1 root root 678206 Dec 29 2011 lazutils.chm -rw-rw-r-- 1 root root 100665 Dec 29 2011 lazutils.xct -rw-rw-r-- 1 root root 12740179 Dec 29 2011 lcl.chm -rw-rw-r-- 1 root root 1275258 Dec 29 2011 lcl.xct -rw-rw-r-- 1 root root 385677 Dec 28 2011 prog.chm -rw-rw-r-- 1 root root 3854 Dec 29 2011 readmechm.txt -rw-rw-r-- 1 root root 617137 Dec 28 2011 ref.chm -rw-rw-r-- 1 root root 5501 Dec 28 2011 ref.kwd -rw-rw-r-- 1 root root 3121967 Dec 28 2011 rtl.chm -rw-rw-r-- 1 root root 344321 Dec 28 2011 rtl.xct -rw-rw-r-- 1 root root 6907 Dec 28 2011 toc.chm -rw-rw-r-- 1 root root 631049 Dec 28 2011 user.chm

On 'Application':

TIDEHelpManager.ShowHelpForSourcePosition A
Filename=/usr/local/src/heavywethers/trunk/HeavyWethers.lpr x=9,y=45 TIDEHelpManager.ShowHelpForSourcePosition B Success 1 TIDEHelpManager.ShowHelpForSourcePosition C
/usr/local/share/lazarus-trunk/lcl/forms.pp X=3 Y=1706 TIDEHelpManager.ShowHelpForSourcePosition D PascalHelpContextLists.Count=1 THelpDatabase.GetNodesForPascalContexts C
FileItem.ClassName=THelpDBISourceDirectory
Filename=/usr/local/share/lazarus-trunk/lcl/forms.pp 1 TFPDocHTMLHelpDatabase.ShowHelp A Unitname=forms NewNode.HelpType=1 NewNode.Title=LCL - Lazarus Component Library Units NewNode.URL=file://index.html
TFPDocHTMLHelpDatabase.ShowHelp Filename="application." UnitName="forms" TFPDocHTMLHelpDatabase.ShowHelp BaseURL of Node.URL="" TFPDocHTMLHelpDatabase.ShowHelp GetEffectiveBaseURL="lcl.chm://" THTMLHelpDatabase.ShowURL B URL=lcl.chm://forms/application.html URLType=lcl.chm URLPath=forms/application.html URLParams= TChmHelpViewer.ShowNode Filename="lcl.chm"
SearchPath="/usr/local/share/lazarus-trunk/docs/html/lcl" Found="/usr/local/share/lazarus-trunk/docs/chm/lcl.chm" Xlib: extension "RANDR" missing on display "localhost:10.0".

Moving up to 'begin' and hitting F1, lhelp gains a reference guide section and displays appropriate info, debug shows:

TIDEHelpManager.ShowHelpForSourcePosition A
Filename=/usr/local/src/heavywethers/trunk/HeavyWethers.lpr x=3,y=44 TChmHelpViewer.ShowNode Filename="ref.chm"
SearchPath="/usr/local/share/lazarus-trunk/docs/html/lcl" Found="/usr/local/share/lazarus-trunk/docs/chm/ref.chm"

It searched lcl identifier "Application.Initialize" and found lcl.chm. Good.

It searched keyword "begin" and found ref.chm. Good.

What do you expect?

Mattias

THAT IT WORKS!!! You've skipped the bit where after hitting F1 on "Application" (which worked) I moved the cursor up one line and hit it on "begin" which didn't, because during the first run I'd started from ~ rather than from the directory that contained the files I've listed.

OK, maybe I've been ambiguous. Go back to my earlier posting and read the middle bit like

-----8<-----
Found="/usr/local/share/lazarus-trunk/docs/html/lcl/lcl.chm" Xlib: extension "RANDR" missing on display "localhost:10.0".

THAT WORKED, I'M HAPPY.

Without killing lhelp, moving up to 'begin' and hitting F1:

TIDEHelpManager.ShowHelpForSourcePosition A
Filename=/usr/local/src/heavywethers/trunk/HeavyWethers.lpr x=3,y=44

THAT *DID* *NOT* WORK AND I'M NOT HAPPY.

The left pane on lhelp is only showing the lcl entries.

Killing Lazarus and starting in /usr/local/share/lazarus-trunk/docs/chm which contains

-rw-r--r-- 1 markMLl markMLl 19177753 Jul 14 12:45 doc-chm.zip ----->8-----

So the question boils down to: where do I give a path to either the IDE or to lhelp, so it knows where to find ref.chm etc.?

On a second thought: not good.
It should be

SearchPath="/usr/local/share/lazarus-trunk/docs/html;/usr/local/share/lazarus-trunk/docs/html/lcl;/usr/local/share/lazarus-trunk/docs/chm"

Please check Tools / Options / Help / Help Options / Viewers / CHM Help Viewer / HelpFilesPath.
It should be empty to use the default or contain $(LazarusDir)/docs/chm.

Mattias

It's set to /usr/local/share/lazarus-trunk/docs/html/lcl/. Setting it blank enables access to help for begin, $R etc. Thanks for that.

I'm sorry for getting slightly irritable but I spent a lot of time at the end of last week trying to find what I was doing wrong with my build scripts- it was only a day later that I realised that I'd had several ssh sessions open and set to different directories.

However, the really annoying thing is that
http://wiki.freepascal.org/Installing_Help_in_the_IDE in the section "If you are using Lazarus from Subversion"- which if course I am- explicitly says '"HelpFilesPath" should be, where you put the CHM files': nothing at all about the fact that in at least some cases it's better to leave it blank because the IDE will "do the right thing".

ref.kwd shouldn't be needed anymore since 2.4.2, since then the ref.kwd has been processed into the ref.chm index.

Since linux doesn't guarantee any helpsystem, any solution is going to be a compromise.

Now if you tell me CHM, that means I need to ship LHelp with my product because Linux & Mac users don't have CHM help viewers out of the box.

Both have several chm viewers available (kchmviewer, gnochm, xchm). If you were so worried about that, I wonder why you didn't work towards integrating them into lazarus and/or its applications.

Instead you created another solution .inf with the same problem (docview) and a few extra (no compiler, and not even a non integrated helpfile).

Somehow your actions and problems don't seem to match :-)

But what is the source help format for CHM, and what tools (help editor) do I use to edit that source format, and what tool do I use to "compile" that source help format into the end result CHM file?

The last time this came up, Michael said there was support in fpdoc for general helpfiles. But afaik there are no examples.

In theory CHM files can be created with any html tool, can be organized with normal MS html workshop, and then compiled using FPC's chmcmd (2.4.4 in theory, but 2.6.0's is better)

Also, how does my product know where to find LHelp (or whatever CHM viewer I want to use)?

That's a *nix/Linux, not a Lazarus problem. If the OS is braindead and doesn't support this, what's other option is there then to do it yourself?

Hi Marco,

Nice chatting to an old friend again. ;-)

Marco van de Voort wrote

Since linux doesn't guarantee any helpsystem, any solution is going to be a compromise.

It's not about Linux not having a dedicated help system, it is about what works with LCL-based applications. And more specifically about context sensitive help in those applications. eg: I don't want my users to press F1 and then be taken to the start page of the help (this is how most Linux Gnome/KDE apps currently work, and that is totally braindead!). I mean like the focus is in an edit field, and F1 will give help about that specific edit field, or fall-back to help about that specific dialog. That is context sensitive help in applications, and how help is supposed to work.

Incidentally, this is how all my fpGUI based apps work too, but I simply couldn't find similar information or solutions for LCL-based applications, hence my question here.

As I told somebody in a earlier reply, I don't mind shipping the help viewer - that is not a just don't want to leave it up to chance... eg: maybe no CHM help viewer is installed, so then application help doesn't work. Or, as is currently the case under Linux, each CHM help viewer has vastly different features and performance. I'd much rather use a specific help viewer, and know what experience my end-users will have.

The last time this came up, Michael said there was support in fpdoc for general helpfiles. But afaik there are no examples.

And I'll say that that is absolute rubbish. fpdoc was designed as a source code documentation tool, and that is what it is good at. It definitely doesn't have the design or features required for application help.

In theory CHM files can be created with any html tool, can be organized with normal MS html workshop, and then compiled using FPC's chmcmd (2.4.4 in theory, but 2.6.0's is better)

So where do you define the TOC or Index items? Inside the HTML files? Is there documentation or a wiki page on the usage of chmcmd?

I searched the wiki and would these two useless pages:

http://wiki.freepascal.org/htmlhelp_compiler
http://wiki.freepascal.org/chmcmd

Neither describes how to actually create application help, define a TOC or setup Index entries.

And this URL...
http://wiki.freepascal.org/Add_Help_to_Your_Application ...explains a bit more, but uses plain HTML files located in a folder. Still no TOC, Index or Search support, because they are simple HTML files that will be viewer with a web browser, and not CHM help.

As I mentioned in a earlier post too. I remember using HelpScribble, which is a commercial Windows product that we used in the Delphi 7 days to author application help. It now (for some time I guess) supports CHM too, but the help source is in a proprietary format, and magically generates a CHM file from that. You define the TOC and Index items from within HelpScribble. What is the equivalent for LCL application developers (eg: cross-platform application developers)? HelpScribble is a Windows only tool, and uses the Microsoft help compiler - but I guess it could possibly run under Linux WINE, but I haven't tried.

What are you talking about? Of course it is a Lazarus problem! How do you tell your LCL program where to find the help viewer? How do you tell LHelp (or any other CHM viewer) to load a specific CHM file, and then display a specific help topic (like in the case of context sensitive help)? Lazarus IDE does this for the RTL, FCL and LCL, but how would you do this in LCL applications? In the IDE you have the chmhelp package, you have a Help configuration dialog etc Must you design and build the same functionality into your LCL based apps, or is there already something like that in LCL that developers can use?

eg:
In fpGUI it has a default location and file name it looks for to find docview (the recommended help viewer). The developer can override the helpviewer executable name and path. The fpGUI framework knows what parameters docview supports, so knows how to call docview to display specific help topics. The fpgApplication instance has a HelpFile property to specify where an applications specific INF help file is, but docview also has a predefined location that it searches for help files - again user configurable. To create your own INF help, one simply needs to edit a single plain-text file, with very easy markup, which is much less verbose than HTML or XML. The markup language is mnemonic, making it easy to associate them with their functions.The TOC and Index items are define inside the single plain-text file. Then simply compile the help source file with the supplied WIPFC help compiler executable, and you have application help in the INF format.

Simple, easy and configurable. And this process is well documented in the docview.inf file - supplied with DocView.

In seems LCL application help creation is just the opposite. The Lazarus IDE is slowly but surely getting a help system working, but none of that functionality translates to LCL based applications. LCL application developers are still left behind - 10+ years into the Lazarus project.

So maybe you can shed some light on this topic, seeing that you are the creator of CHM tools in FPC & Lazarus. How do you add context sensitive help in your LCL based application? Or do you simply not ship help with your
Regards,
- Graeme -

_______________________________________________
fpGUI - a cross-platform Free Pascal GUI toolkit
http://fpgui.sourceforge.net

Graeme Geldenhuys wrote

Hi Marco, Nice chatting to an old friend again. ;-)

So lets all try to keep this friendly and constructive, without launching into a "my IDE's better than yours" exercise :-)

I'm writing this from the position of an outsider, so am happy to be corrected by Marco, Andrew et al. However if I there are areas that I haven't been able to "get my head round" after several days scouring the Wiki and Google, it's going to be far worse for a tyro. If somebody thinks I've got things wrong, I suggest that exploring /why/ I've got it wrong and what can be improved is in order.

The current situation- and this is with Lazarus trunk, not stable- appears to be that HTML keyword-based application help works well provided that you're prepared to tolerate browser startup time. However, even worse than the startup delay is the fact that in the general case neither the IDE nor general apps can tell an existing browser to change the page it's displaying: I believe there's a backdoor for this sort of thing in IE on Windows but on unix you can end up with multiple browser instances that don't go away when the program's shut down.

I very much look forward to the CHM reader being made available for apps rather than just for the IDE, I'm starting to code what could be my magnum opus and I'd like the opportunity to exercise it.

The end user is entitled to have all files of a particular type (chm in the current case) look and handled the same, but I'm not sure it should be the developer's choice which program is opened for a given file type, unless he is prepared to take full responsibility for things going wrong in other apps.

As a general point, current desktops (including KDE and Gnome) have a standardised set of programs for opening files by extension (xdg-open etc.), and to be quite honest I think it's not to the credit of anybody who tries to open a browser or viewer without reference to these.

..

I added a section to that page on adding a TOC yesterday and how to find what options are supported by chmcmd. I didn't want to be too verbose since it's hardly my area of expertise, but I felt it needed to be documented somewhere.

The canonical tool appears to still be the Microsoft Help Workshop (or some similar name), and almost everything else appears to be based on this in some way: chmcmd is pretty much unique, to the extent that I've seen a Debian bug report asking why it's not packaged separately because of it's general usefulness. The Wiki page above mentions a product/project to convert Tex to chm which I've not investigated, I'm now able to convert Lyx source or PDF to HTML hence to a .chm including semi-automatic TOC (single-level) but it doubtless needs more work and I'm not sure what the situation is regarding integrating CHM in an app.

Got to go, sorry if anything above is incomplete or unchecked.

Totally agreed.

<snip>

1. document the IPC mechanism used for communication between IDE and lhelp so application developers can use it
2. compile and distribute lhelp with your application... should be possible already, shouldn't it?
3. in application: start lhelp and pass messages using 1.

- I don't know intercepting e.g. an F1 keypress from being sent to system wide help would take special action... perhaps it doesn't.
- Perhaps there is some Linux standard or GNOME or KDE standard that indicates how to do *keyword sensitive help* with chm files. In that case the approach above could be a fallback mechanism... or this approach could be a fallback mechanism depending on programmer's preference.

I'd lean to this conclusion as well.

I don't think changing the system wide association between the .chm file type and the executable to open that is what Mark or I would have in mind. In any case, I agree that is bad.
However, given my solution above, this step would not be necessary at all.

As a general point, current desktops (including KDE and Gnome) have a standardised set of programs for opening files by extension (xdg-open etc.), and to be quite honest I think it's not to the credit of anybody who tries to open a browser or viewer without reference to these.

In general, agreed, but:
If that standard allows keyword lookup etc.. I'm all for it. Also, the number of standards must be manageable ;)
Finally, quite probably not *all* desktops support this (saw your "current" up there)... so a fallback mechanism would be needed if others are supported, too.
It may just be too much effort to support all of it... unless this effort can be moved into some kind of cross-platform application help framework to be included in say... Lazarus ;)

The canonical tool appears to still be the Microsoft Help Workshop (or some similar name),

Microsoft HTML Help Workshop, if I've got the right one installed here. Yes.

Agreed, or tentatively "componentize" the relevant classes (TLclChmHelpDatabase and TChmHelpViewer?).

No, the tools are strictly for handling file and mime types:

-----8<-----
xdg-desktop-icon (1) - command line tool for (un)installing icons to the desktop
xdg-desktop-menu (1) - command line tool for (un)installing desktop menu items
xdg-email (1) - command line tool for sending mail using the users preferred e-mail composer
xdg-icon-resource (1) - command line tool for (un)installing icon resources xdg-mime (1) - command line tool for querying information about file type handling and adding descriptions for new file types xdg-open (1) - opens a file or URL in the users preferred application
xdg-screensaver (1) - command line tool for controlling the screensaver xdg-settings (1) - get various settings from the desktop environment ----->8-----

Finally, quite probably not *all* desktops support this (saw your "current" up there)... so a fallback mechanism would be needed if others are supported, too.

I agree about the fallback, but the xdg stuff has been in most if not all Linux distreaux for around five years (doesn't appear to be in Solaris 10 which is 5+ years old now, don't have a newer version to check). The important point is that the xdg command lines are standardised, the implementations are platform-specific.

Ok, this would mean the xdg-open tools don't allow context-sensitive help... and end of discussion on that front as far as LCL application help is concerned, I suppose.
Unless
a. I'm misinterpreting things
b. there are other APIs/standards that address this

Given the above this wouldn't really matter anymore, would it?

The only relevance is that this- in my opinion at least- should be the primary way that a program tries to locate subsidiary file viewers etc. It's the unix answer to ShellOpenEx() (or whataver the Windows API's function is).

<snip>

The only relevance is that this- in my opinion at least- should be the primary way that a program tries to locate subsidiary file viewers etc. It's the unix answer to ShellOpenEx() (or whataver the Windows API's function is).

Ah, ok.

AFAIU, LCLIntf.OpenDocument('thedocument.chm'); would open the CHM file with the system viewer (if present) in a cross-platform way. On Windows (sysenvapis_win.inc) it uses ShellExecute/ShellExecuteW.

On Unix, Linux (sysenvapis_unix.inc), it looks for xdg-open, kfmclient, gnome-open and tries those.

On OSX (sysenvapis_mac.inc), it runs
RunCmdFromPath('open',ResultingPath);
too lazy to look up what that does.

There seems to be an implementation for Android customdrawn as well.

Thanks for that- I'd missed that the xdg stuff had (finally :-) been added.

i pointed this out previously several months back when we were having the big help installation discussion... i couldn't get it to work and then suddenly it started... about that time someone wrote in here to fill in that field with the path... i checked mine and is was empty so i responded that i didn't have anything in mine and it was now working... i had thought that you might have picked up on that post of mine because your help install started working per your report...

now, the only thing left for me/us is to find the rest of the chm files... there's more than three of them ;)

This has all been rehashed umpteen times. The bottom line: It's a work in progress, people seem to start competing projects instead of chipping in.

Recent progress is slow or has stalled.

The current situation- and this is with Lazarus trunk, not stable- appears to be that HTML keyword-based application help works well provided that you're prepared to tolerate browser startup time.

Decompress a zip with the html help on an ARM with SD or something else slow. Then the browser startup isn't the worst bit anymore. (I've seen the FPC installer do over 30 minutes of decompression on dos, and that was when the docs were far smaller. The rest of FPC installed in 2 minutes)

It's not really IE. It is simply true browser instrumentation vs cheap and easy fire and forget browser launching.

I very much look forward to the CHM reader being made available for apps rather than just for the IDE, I'm starting to code what could be my magnum opus and I'd like the opportunity to exercise it.

I don't know if Andrew is still actively working on lview. I never worked on the visual part. That's because I originally came to work on CHM from the textmode IDE side, not Lazarus.

This is too vague and generic. "look and handled the same" from where? From the explorer, I agree, that is the users choice.

But the help is lauched from the app, not the explorer, and thus the app developer's responsibility.

We all would like it otherwise, but on *nix it has been that way for a while, and it doesn't look like it is going to change soon.

As a general point, current desktops (including KDE and Gnome) have a standardised set of programs for opening files by extension (xdg-open etc.), and to be quite honest I think it's not to the credit of anybody who tries to open a browser or viewer without reference to these.

xdg-open is opening a document (and even then only the gnome-KDE lowest common denomitor only. I'm pretty sure KDE apps don't call their help or instrument eachother via xdg-open)

I'm instrumenting an application, for which there is no standarized set. KDE and Gnome afaik both have separate instrumentation (ORB like) systems, which often change on major releases.

The canonical tool appears to still be the Microsoft Help Workshop (or some similar name), and almost everything else appears to be based on this in some way

Be careful. That Workshop consists out of two tools, both equally horrid. One is a simple editor for help projects, and one is the compiler.

You can do without an editor (just generating a hhp project from some other source), and chmcmd is rougly equivalent with to the compiler.

Most "CHM" authoring tools call the MS compiler in the end. With some crafting you can simply use commercial authoring tools and then export it to a hhp project (or rescue that from %TEMP% while compiling).

Or just create html, and use the DOM tool

chmcmd is rough, but I have gotten reports of people using it ON WINDOWS to workaround bugs with the MS tool (which seems to have problems with big files) :_)

Being able to enable the multi-core compression which is in CHM, but not stable would be another really big boon.

Anyway, the chmcmd compiler should work for most basic projects. A simple editor that allows you to add html to a project, scan it for labels and/or outlines should be easy, as long as you control where the html is coming from.

: chmcmd is pretty much unique, to the extent that I've

seen a Debian bug report asking why it's not packaged separately because of it's general usefulness.

Well I expanded chmcmd a bit in the last few releases to become a .hhp compiler (before it was only rudimentary access to the chm writer class, I basically added the same, but to/from the .hhp ini like format, implemented recursive scanning for additional files).

But the real virtue is the CHM writer in general. chmcmd only instruments it. Credit for that mostly goes to Andrew Haines. Sergei did some good work debugging the HTML modules of fcl-xml too btw.

The latex chms (ref,user,prog) are generated much the same way. See the latexcompile or something program in the fpcdocs repo. (the documentation sources). The cherry on the cake is the folding of the keyword index into ref.chm.

Be warned though. It is ad-hoc code, probably not 2.7.1 compatible (due ot unicode changes), and works around fcl-xml bugs probably resolved now.

Graeme Geldenhuys wrote

And I'll say that that is absolute rubbish. fpdoc was designed as a source code documentation tool, and that is what it is good at. It definitely doesn't have the design or features required for application hel

I remember from our discussion some months ago that there was an announcement that hopefully a tool will be crated, that somehow unifies the help information generated by updating the Wiki and by using (e.g.) fpdoc. Do you know the state of that project ? I suppose before deciding about any other improvement for the help system - that of course needs to be based on some common central help source repository - a decision on this (if doable, seemingly very advantageous) project should be done.

-Michael

Graeme Geldenhuys wrote

And this URL... http://wiki.freepascal.org/Add_Help_to_Your_Application ...explains a bit more, but uses plain HTML files located in a folder. Still no TOC, Index or Search support,

In fact search features (including "F1" fast search) are especially essential to the usability of a help system.

As discussed some months ago: When e.g. Wiki is used to have users crate/updates help information, I suppose some special definitions need to be defined on top of the usual Wiki stuff to allow for search support and for cross references to help information that is generated by other tools.

-Michael

Michael Schnell hat am 18. Juli 2012 um 11:54 geschrieben:

Can you give an example?

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

I don't remember the details of what has been discussed at that time. I just seem to remember that the said tool should be able to use as well the user-updateable Wiki(s) as the (existing expert-updateable) files (e.g. xmls managed by fpdoc) as a combined repository for the help files. (Maybe this is done by converting the xmls in wikis, but I don't remember and don't have a suggestion or opinion on how this might be best done, I only feel that it would be a good thing.)

In fact if there are multiple wikis and/or XMLs, the wikis would need to be equipped with keywords accessible by search functions, "F1" and maybe usable as targets on other pages. I don't know if the Wiki database format provides that out of the box. Independently of how the combination with the existing XML files is accomplished, cross-references seem to be necessary.

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

Hi,

Michael Schnell wrote

Do you know the state of that project ? I suppose before deciding about any

I know Mattias started work on a tool that extracts the help content directly from the wiki pages. I have not followed that project so I have no clue as to the status of it, but I would guess it is somewhere inside the Lazarus project if you want to take a look.

other improvement for the help system - that of course needs to be based on

Please note, that the discussion some months back was about help for the RTL, FCL, LCL, FPC Language Reference etc to be used by the Lazarus IDE - to help developers with programming and API information. What I was talking about in this message thread is "application help". Integrating CHM help into your own applications, giving your end-users context sensitive help for your product. So far I have heard that integrating CHM help into your own LCL-based applications are not possible, and that nobody here actually seems to ship help files with their own applications. I guess I'm the only exception to that rule.

The following URL is exactly what I am talking about, but as I said, it only describes HTML help (lots of HTML files located in a folder), and has limited help abilities.

http://wiki.freepascal.org/Add_Help_to_Your_Application

I had a look at the chmhelp package include with Lazarus, to see if I could follow the same guideline as mentioned in the above wiki page. But the chmhelp package depends on the IDE (CodeTools, IDEInterface etc), so as far as I can see, it can't be used in general LCL-based applications.

Graeme Geldenhuys wrote

What I was talking about in this message thread is "application help".

I see, but as the IDE _is_ an application, I feel that - if Lazarus is supposed to provide means for application programmers to integrate a help system in their apps and fill it with appropriate information - it would be a good idea to do both with the same tools, leveraging both the amount of work that needs to be done by those creating the system(s) that allow for inputting and displaying the help content, and the learning curve for those that as well use and help improving Lazarus (a big plus for an open source project as Lazarus is).

-Michael

Graeme Geldenhuys wrote

What I was talking about in this message thread is "application help". Integrating CHM help into your own applications, giving your end-users context sensitive help for your product. So far I have heard that

I agree that it's a distinction that has to be made.

integrating CHM help into your own LCL-based applications are not possible, and that nobody here actually seems to ship help files with their own applications. I guess I'm the only exception to that rule.

I think it was Reinier who yesterday said that if the socket interface used by lhelp was published (or at least if somebody could give us a pointer to the location of the information) it would be a big step forwards.

As I wrote yesterday, I've added a brief section to that page on generating arbitrary .chm files.

I think you might mean this page?
http://wiki.freepascal.org/chm_backend_for_fpdoc

See Mark's and my thread on what to do to actually get things working and Graeme's investigation into the chm help package (haven't looked at that yet, myself).

I'm sorry but it seems so much more constructive to discuss actual ways forward to solve things based on what we have now, even if it is step by step, than to keep talking about abstract concepts.

We have a lot of components already there: a tool that can generate chm files (even if it has limitations), a cross-platform viewer for chm help (lhelp), a communication mechanism between application and help viewer that tells the viewer what to show.

1. CHM context-sensitive help
We'd need to document the protocol used by the IDE to instruct the help viewer to display certain help

2. Other help viewers
If we get the communication protocol documented, even other help viewers like Graeme's docview could get adapted. This would mean more choice in the help document format you use and the tools that can be used to author help.

3. Ease of use
If we get the communication protocol "packaged up" as a Lazarus component, it will make it easier for developers to add context sensitive help.

4. HTML help
This page: http://wiki.freepascal.org/Add_Help_to_Your_Application would indicate application help using HTML files is possible but lacks context-sensitive help, i.e. directing the viewer to a specific keyword or chapter.

Is this a direction that you would support?

Reinier

Mark Morgan Lloyd wrote

> http://wiki.freepascal.org/Add_Help_to_Your_Application As I wrote yesterday, I've added a brief section to that page on generating arbitrary .chm files.

Strange, as I see no such amendment. There is no mention of CHM files, and the line at the bottom of the page footer says "This page was last modified on 15 April 2012, at 11:44."

Maybe you amended some other wiki page?

Reinier Olislagers wrote

I'm sorry but it seems so much more constructive to discuss actual ways forward to solve things based on what we have now, even if it is step by step, than to keep talking about abstract concepts.

While I do see your point, I of course don't agree.

To me it does make sense to decide whether I want to drink tee or beer, before opening either the cupboard or the fridge. ;-)

-Michael

I do indeed. And there was I thinking that a certain party never listened to anything anybody said... :-)

Well... have you decided whether you want to have tea or beer? If so, why?

In other words, if you see another possible architecture/solution, please share, as I'm sure that will help choose the best one.

As Reinier points out, I was thinking of
http://wiki.freepascal.org/chm_backend_for_fpdoc Mea culpa.

But first you have to identify the need: that you're thirsty :-)

I think Reinier and I are saying that the need in the current case is how to intercept F1 and recover an associated keyword, and how to pass that keyword to lhelp.

Reinier Olislagers wrote

Well... have you decided whether you want to have tea or beer? If so, why?

Nope.

I just intended to provide a hint so that those that are inclined to do some work on that behalf might consider this and might be able to do the decision on an even broader base of information.

In other words, if you see another possible architecture/solution, please share

I think I did exactly this:

My suggestion is, that the help system (displaying and help in a user application and creating help content) Lazarus offers for it's users should be the same that the IDE uses to provide help for the application programmers and that enables Lazarus-contributors to create/update Lazarus help content.

-Michael

Mark Morgan Lloyd wrote

But first you have to identify the need: that you're thirsty :-)

Yep. Seemingly both are: The application programmers that want to provid3e a help system to their users, and the application programmers that want to use a help system when working with Lazarus. Moreover those willing to provide/update content to the Lazarus help system are thirsty, too.

I think Reinier and I are saying that the need in the current case is how to intercept F1 and recover an associated keyword, and how to pass that keyword to lhelp.

Of course you are right. This is one aspect of the functionality that might be provided by the Lazarus LCL to have the application programmers provide a "help" functionality to their users. Other aspects of this functionality is launching a help viewer (or providing an internal one) and allowing the programmer to create the help files in a decent way.

Beer: _When_ all this is resolved in a perfect way for the IDE, any application programmer can just use it for his own product. Tee: some unrelated system might be integrated in the LCL that is usable for the application programmers' product. Same supposedly will use some 3rd party help writing tool.

-Michael

I'm sorry. You can't have your cake and eat it.
The high level idea you write above was already posted by e.g. Mark. You (IIRC later) then wrote the same idea.
Then Mark & I proposed a way to implement it, Graeme did additional research and I asked for your comments on that, and it turns out you don't have any.
I still don't see the added value of your posts, and will leave it at that.

Michael Schnell wrote

Tee: some unrelated system might be integrated in the LCL that is usable for the application programmers' product. Same supposedly will use some 3rd party help writing tool.

Sorry, perhaps we're talking at cross-purposes which may explain some of the confusion.

Your tea option: having another help viewer integrated is *exactly* what has already been proposed: the IDElhelp communication protocol could be used for third party help viewers, whatever file format that viewer wants to use, and whatever tools that can be used to generate that file format.

I do know.

With my contribution I just wanted to say that I think that this option should not be put aside just because there are some difficulties assigned to it (e.g it has been stated that fpdoc is not perfectly suited for the task of creating such help content. So my hint was that in the past there has been suggestions for improvements.

Sorry for being a troll (again).
-Michael

Hi,

I think Reinier and I are saying that the need in the current case is how to intercept F1 and recover an associated keyword, and how to pass that keyword to lhelp.

Surely the "capturing of the F1 key press" functionality already exists in LCL? I also see TControl.HelpType, TControl.HelpContext, TControl.HelpKeyword and Application.HelpFile properties... Are they just for show (not functional yet)?

Another problem I spotted was with the Application.HelpCommand() signature. It's got the signature designed by Borland Delphi v1 (somewhere around then) for the use with the very old WinHelp help viewer and the long discontinued .HLP files. I've already raised this issue some years back, but received my usual answer that it will not be changed - go figure. Anyway, a more sane signature for Application.HelpCommand() would be like Delphi & Kylix defined it for the CLX framework. As a matter of fact, the help system for CLX was designed to be cross-platform and uses Interfaces to be very flexible. It is probably the cleanest help system design I have ever seen, and it supports multiple help viewers too. Kylix even came with two reference implementations - a Man Page viewer and a HyperHelp viewer.

For more interesting discussions on Lazarus help system ideas, see this message thread from way back in May 2006...

http:/msg07364.html

May 2006 was a busy month for talk about help systems and help formats. If the archives would be easier to view, it would help a lot. I found some links though, but they don't all start at the beginning of each message thread.

http:/msg07274.html
http:/msg07368.html

Of course they work- in the context of the HTML help components. But if you'd been paying attention you'd have seen that what Reinier raised was how to use lhelp's (socket?) interface to get it to display a named page, and that's not very much use unless you can get the appropriate keyword to the other end of the communication connection (i.e. get F1 to behave properly).

Now I presume that the existing HTML help components tell the LCL that they want F1 when they auto-register, but in the absence of comparable components for CHM we need to know how to do it.

Hi,

Thanks, those steps were really helpful. That gave me a good starting point, and I'll Google .hhp files further.

I don't think an application call makes should be IPC (dbus) like, to avoid multiple instances, and to avoid having agree with this. fpGUI currently uses TProcess to start up DocView,

but that was just step 1 to get the help system going. I'm working on step 2 now, which is the IPC communications.

IOW an IPC call to register helpfiles at startup (and start a small daemon if necessary), and then just fire the "show help" or "give me index" commands.

Yes, that is how I understood it too. The dbugintf.pas unit and the various "debug server" apps around are good working examples of this.

> specific help topics. The fpgApplication instance has a HelpFile > property to specify where an applications specific INF help file is, (Only one helpfile per app?)

No, you can concatenate multiple help files, specify a help directory (instead of a file), specify an environment variable etc... DocView is very flexible with this.

I don't ship Lazarus applications.

:-/ Time to speak to your boss then.

At work I use Delphi, but I don't ship help with those either. (though I have in previous jobs). We ship latex generated manuals in PDF format for

You guys have it way to easy! :) All our apps must ship with help files, and we have a separate installation PDF. Our end-users are not the most computer literate, but they know everything about Maths and Science.

This is a bit like the argument about whether code should be commented or properly-written. I normally argue for copious comments in source, but at the same time I think I favour properly-designed forms and components which don't need on-screen help.

Having a decent manual, possibly with weak linkage to the app so that it opens on the right page (something that PDF is bad at) is a different issue.

Graeme Geldenhuys hat am 18. Juli 2012 um 19:53
geschrieben:

They do work.
See here an example with HTML pages:
http://wiki.lazarus.freepascal.org/Add_Help_to_Your_Application

There are:

function HelpCommand(Command: Word; Data: PtrInt): Boolean;
function HelpContext(Context: THelpContext): Boolean;
function HelpKeyword(const Keyword: String): Boolean;

The Keyword can be an arbitrary string. In the HTML viewer it is the path behind the BaseURL.

The current help system knows viewers and databases (= sources). It's not clx compatible though.

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

Reinier Olislagers wrote

On 17-7-2012 10:15, Mark Morgan Lloyd wrote: >From another outsider's view, wouldn't this be a solution: 1. document the IPC mechanism used for communication between IDE and lhelp so application developers can use it

Added some notes on
http://wiki.freepascal.org/IDE_Development#Working_8 Although that page says: "This page contains notes for lazarus core developers about ongoing development." it seems like it can serve as documentation of realized development as well.

See lazarus\components\chmhelp\democontrol for a project that demonstrates IPC communication.

The source code
(lazarus\components\chmhelp\packages\help\lhelpcontrol.pas) is quite legible... even for me ;)
While I've submitted some more comments in issue 22467, I think it can serve very well as documentation for the protocol. AFAIU it could be used as-is in applications, perhaps aided by taking inspiration from the code in
lazarus\components\chmhelp\packages\idehelp\lazchmhelp.pas

Creating a component that includes lhelpcontrol added with some functionality from chmhelppkg should be quite doable.

I can't seem to find any license info for these packages though. Is it modified LGPL?

2. compile and distribute lhelp with your application... should be possible already, shouldn't it? 3. in application: start lhelp and pass messages using 1.

Mark Morgan Lloyd wrote

the same time I think I favour properly-designed forms and components which don't need on-screen help.

Some of our apps have advanced features. eg: Dynamic views that the user can customise, thus changing what they see, and how the data is presented. We supply some default views, which they can use to base there views on, or create new views from scratch. The "what is a view", and "how to create your own views" are things that appear in the application help. Then we also have some help and transaction examples in our accounting section of the application. People learn best by example - thus, that is in the application help. We don't display detailed help per widget, but rather an overview of each dialog, and what is is for. And more detailed help for things like the two examples I listed above.

Having a decent manual, possibly with weak linkage to the app so that it opens on the right page (something that PDF is bad at) is a different issue.

We even have one-to-one training sessions on our applications and business practices (we are a franchise business)... and amazingly we still get phone calls about certain things. :)

Reinier Olislagers hat am 19. Juli 2012 um 10:06
geschrieben:

I can't seem to find any license info for these packages though. Is it modified LGPL?

Modified LGPL 2, same as the LCL.
I added the note in the package.

> 2. compile and distribute lhelp with your application... should be > possible already, shouldn't it?

yes

> 3. in application: start lhelp and pass messages using 1.

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

LOL ;)

<cynical>As always, it's a careful balance between providing help[1] that nobody reads versus not providing any help which users can then complain about ;)</cynical

[1] And the advanced version: help that actually helps vs help where some keywords are thrown together in order to give the appearance of having made the effort...

I was working through stuff last night and could see where it was based on SimpleIPC, with the socket name passed as a parameter to the lhelp program. So provided that an app can grab F1 it doesn't look too bad.

> I don't ship Lazarus applications. :-/ Time to speak to your boss then.

It's mostly my call. There is nothing much to gain there.

Well, the pdf manuals are on average 100-150 pages, but sometimes 300 pages, 40-60% of which is custom per project. Then on top of that, blueprints and BOMs of all mechanical parts.

Marco van de Voort wrote

Well, the pdf manuals are on average 100-150 pages, but sometimes 300 pages, 40-60% of which is custom per project. Then on top of that, blueprints and BOMs of all mechanical parts.

Do you ever have a situation where you need to index into a PDF, and if so how do you cope?

I'm looking at something where it would be beneficial to have a collection of electronics info, and I'd want immediate access to a given section. Allowing for the dominance of PDF in that industry, the best I can think of so far is to burst each PDF into pages, and then convert each page back to PDF.

Are you talking about PDFs with digital text or images with hidden text ("searchable PDFs" as they are sometimes called) as opposed to images only?

If so, extracting the text using e.g. pdftotext (e.g. page by page), finding the text etc and instructing a pdf reader to open at a certain page - if that reader supports it - may be helpful?? E.g. for the Sumatra PDF reader (IIRC, only available on Windows): sumatrapdf -page <pageno>

Depending on the reader, you could do more, see e.g.: https://code.google.com/p/sumatrapdf/wiki/CommandLineArguments

If the PDFs are images only, the only feasible way I'd see would be to extract the images, OCR them and deal with it then; e.g. rebuild the PDFs, adding the resulting text as hidden images, e.g. with the Linux hocr2pdf tool provided by the exactimage package:
http://www.exactcode.com/site/open_source/exactimage/

FYI, I'm actually in the process of building a fairly simple document scanning solution (for now on Linux) that:
- scans the document using sane, outputing tiff files
- performs optional cleanup, e.g. with the scantailor package
- recognizes text with tesseract, output layout/text info into hocr format
- combines the image and text into "searchable PDFs" using hocr2pdf
- adds metadata to the PDF
- adds the text to either a database or more probably some kind of full text search package
- registers the scan into a database
- provide a viewer to search for documents, print them etc; in future perhaps to be used for correcting OCR results

Not very far, but:
https://bitbucket.org/reiniero/papertiger/overview

For Dutch speaking readers: yes, the project name is intentional ;)

Reinier Olislagers wrote

For Dutch speaking readers: yes, the project name is intentional ;)

LOL

Bart

Any sort of PDF, including murky scans from Bitsavers.

Although highly non-portable. My thoughts were to have documentation on a server to be available to anybody using a specialist Lazarus app, the whole thing would be spoilt if as well as loading the app (tentatively, Borg-UI) and possibly lhelp and associated CHMs I required users to find a specific PDF reader and possibly integrate it with their browser.

Although even if the original wasn't a bitmap from Bitsavers, electronics stuff with lots of tabular material (control registers and the likes) is notoriously difficult to reformat. I /hope/ to be able to get the docs into a database (PostgreSQL handles binaries fairly well, which would simplify some of the replication/dissemination issues) even if they were saved as files local to each HTTP daemon.

I'm afraid I don't speak Dutch, although my mother used to quote "B?ter, brea, en griene tsiis" out of context every few months. But I like the palindrome :-)

Agreed. Any takers for adding PDF functionality to lhelp or docview ;) Note: viewers like SumatraPDF can be used without installation, so it becomes a matter of deployment with your application.

You'd still face issues with Linux/OSX of course.

Your idea of extracting the single relevant PDF page into a separate PDF and presenting that to the user could work, especially if you provide forward/back navigation buttons (in a Lazarus app or web browser+PDF plugin).
On Windows you might be able to embed some Activex PDF control, once again not portable...

Captain obvious: I'd balance ease of use for this solution versus distributing a portable PDF viewer and telling that to go to a certain page.

Yes, but I wasn't talking about reformatting, just pasting the invisible text "behind" the visible graphics (in another layer) in the PDF. Alternatively, you could store the retrieved text (and page numbers) somewhere else.

Of course, OCR itself may be crummy with these kinds of PDFs... which will lead to search misses/false positives.

If you have graphics-only PDFs and want to do text search you'd have to perform this step if you want to go to a certain spot based on a user search... unless you retype the text...

I /hope/ to be able to

get the docs into a database (PostgreSQL handles binaries fairly well, which would simplify some of the replication/dissemination issues) even if they were saved as files local to each HTTP daemon.

Sounds like a large system?
You'd be having multiple HTTP servers that serve up PDFs coming from the db? And viewing those with a web browser?
That does confuse me: what do you use the "specialist Lazarus app" for you talked about earlier?

Butter, bread and green cheese in Frisian? (Note: as the Frisians will insist on telling you, different language from Dutch... only reason I seem to understand the words is context and because it's close to both English and Dutch ;)

I'd rather not discuss the problem domains at the moment, but yes: a big system with a tree of database servers (PostgreSQL, with the option of Firebird at the leaves). I'm hoping to be able to use the same (or at least a very similar) app both at each analyst's client computer and to aggregate state at each node in the tree.

I'm hoping to be able to say more at some point, because apart from anything else making it open (or at least free-distribution) and applicable to some juicy problems would be the best way of testing that it scales.

She always used to use it to demonstrate the similarity between English and Friesian, but my more recent understanding is that it was also used as a shibboleth that only Friesians could pronounce properly. But she was Welsh, so you have to make allowances :-)

Reinier Olislagers wrote

> > Although highly non-portable. Agreed. Any takers for adding PDF functionality to lhelp or docview ;)

DocView will shortly have PDF support - but only in the form of saving help topics or selected topics to PDF, which could then later be printed (or emailed) if needed.

As for your whole idea of using PDF's as some form of application help system - that's just crazy. You are trying to fit a square into a round hole. Use a decent documentation system like DocView instead - which was designed for that purpose.

I don't agree it is crazy ?

I use PDF for application help. Works perfectly, F1 and all. It has all properties you expect from a help system (including hyperlinks), and can be used to print to boot.

Michael.

Michael Van Canneyt wrote

I use PDF for application help. Works perfectly, F1 and all. It has all

Yes, you told me that a long time ago. But I also remember you told me that it only works in Windows. Plus the "help" is at the mercy of the documentation writer.... by that I mean, there might not be a Index or a Table of Content, and Searching PDF's are damn slow. And while we are talking about slow - Acrobat Reader (installed by most users, especially under Windows) has the longest start-up time of any PDF reader.

Yup, still a crazy idea. ;-)

It's not as crazy as using a pseudo-standard such as one of the MS Word or Open/Libre Office formats, or the sanitized versions which IBM et al. are pushing in their attempts to prove to various governments that they are 100% behind open standards. But I remain very concerned about the level of support- i.e. with any reader on any platform- to jump to a predefined entry point in a PDF.

And quite frankly, when looking at a fairly wide range of OSes and CPUs, Adobe's reader is better than the alternatives particularly when there's a thousand or so pages in a document (like the IBM S/390 manual I'm using to put myself to sleep at night).

From the POV of the Lazarus IDE, /the/ important thing is rapid and correct loading of a page in response to F1. If the storage format that this dictates can be easily created and exploited by user-written programs- which (with the possible exception of F1 support) is pretty much where we are with .chm- then all the better, because it means that the maximum number of people are focusing on improving performance and reliability.

Make no mistake, Adobe Reader does good rendering, and performs better than other PDF readers when it comes to graphic intensive PDF's like "Linux Format Magazine" monthly editions etc. But I must say that Evince (Gnome default) and Okular (KDE default) has fantastic performance, and has much faster startup times than Adobe Reader. Evince and Okular also has no problems in opening the 1700+ page PDF of FPC's RTL for example.

No. We don't do help. Stronger even, I haven't really in past jobs either, since those were server apps.

So all my helpfile stuff is hobby, but that goes back a long time. I was already dabbling with helpfile systems in my topspeed days (before FPC)

Since I don't HAVE TO deploy anything, I only work on long term solutions. IMHO this is not one :-)

For the same reason, I don't like the constant Kylix help recommendations either. Fine for isolated cases, but shouldn't be promoted as general thing to do IMHO

Marco van de Voort wrote

For the same reason, I don't like the constant Kylix help recommendations either. Fine for isolated cases, but shouldn't be promoted as general thing to do IMHO

Strongly agreed. The ONLY case in which these might be applicable is when somebody is working on x86 Linux, in all other cases the fact that a closed-source reader is required detracts from Lazarus's claim to be cross-platform. Not to mention the copyright aspect.

Mark Morgan Lloyd wrote

Strongly agreed. The ONLY case in which these might be applicable is when

The reasoning for recommending Kylix Help to Lazarus users was simple. Only in the last year or so did the Lazarus LCL actually start getting help. Not to mention that Lazarus didn't even have a offline help system to compete with anything out there. I still feel to this day, the Kylix Help is still a lot more complete, detailed and useful, with working example code too.

As for the x86 Linux only comment.... Well, tough sh*t to the Windows and Mac users. I paid for Kylix Enterprise, so why the hell may I not reuse what I paid a fortune for! In any case, LCL is supposed to be a VCL clone (just like CLX), so the Delphi/Kylix help should be very appropriate to LCL - if not, then the Lazarus project didn't do a very good job cloning Delphi VCL.

It's also copyright, and you were very quick to point out the questionable status of somebody's contribution earlier in the day.

However I agree that Lazarus and FPC help still has some way to go.

You miss my point. The proprietary viewer is NBG on Linux running on ARM, MIPS, PPC, SPARC and so on. And it's NBG for Solaris and BSD on any CPU. Not to mention Windows, OS X, or minority operating systems such as OS/2.

So while I agree wholeheartedly that you (or anybody else who's paid for Kylix, and arguably anybody who's been given a legitimate free copy) should be able to use the help files even as an aid to migrating to another development environment, I don't think it's appropriate for them to be recommended for use in other contexts.

Hi,

Mark Morgan Lloyd wrote

It's also copyright, and you were very quick to point out the questionable status of somebody's contribution earlier in the day.

I NEVER implied that the Lazarus project must use the Kylix Help viewer as "the lazarus help viewer". I also NEVER implied that the Kylix Help must be copied or used verbatim as "the lazarus help". The suggestion was always meant as a "stop gap" option, while the Lazarus help was non-existent.

Not to mention that you could have received a copy of the Kylix Open Edition product - which was freely available as magazine cover CD's etc back in 2000-2004. Kylix Open Edition - for use for developing GPL software - is still available for download from various locations on the internet - it's just not supported by Embarcadero any more.

You miss my point. The proprietary viewer is NBG on Linux running on ARM,

Again, I NEVER said the Kylix Help Viewer must become the official Lazarus help viewer. You came up with that idea all by yourself.

I just noticed this (there is a lot of activity in the mailing list and i only browse it occasionally).

Personally i have written a custom help system:

http://badsector.github.com/lazhelp/

It is made up of a bunch of components that can either provide the help content from inside the program (f.e. from a resource or just a string list) or from an external file. The help can be displayed as a popup/tooltip, inside a panel using a custom control or a separate window with back, forward, home and other optional buttons (like introduction, tutorial, etc). It can also be registered as a help provider for LCL (so you can use HelpContext etc in controls).

The viewer is written with LCL so it should be portable (although there are some inconsistencies, especially regarding scrollbars). There aren't many things supported by the language (which has a simple syntax) but it should be enough for simple applications. For larger help sites, it probably needs more stuff (f.e. there is no table support).

I have used it for Runtime World, my 3D world editor:

http://chiselapp.com/user/badsector/repository/rtworld/

and for LILCard, a hypercard-like program:

https://github.com/badsector/lilcard

(the latter shows how the help system can become part of the executable itself since lilcard is a single executable in all platforms)

The reason i made it is, as you have said in other threads, i find Lazarus current help situation to be ,
i don't want to distribute a huge executable for viewing CHM files (in the case the user's computer do not have the ability to view CHM files) and i find the CHM viewer's user interface to be somewhat complex.

Kostas "Bad Sector" Michalopoulos

I flatly refuse to get into a querulous, nitpicking quibble about who wrote what and with what intention. But

Graeme Geldenhuys wrote

> You miss my point. The proprietary viewer is NBG on Linux running on ARM, Again, I NEVER said the Kylix Help Viewer must become the official Lazarus help viewer. You came up with that idea all by yourself.

I'd point out that when I wrote

"...the fact that a closed-source reader is required detracts from Lazarus's claim to be cross-platform."

you countered with

"As for the x86 Linux only comment.... Well, tough sh*t to the Windows and Mac users."

I really don't know where you got this "the Kylix Help Viewer must become the official Lazarus help viewer" thing from, I've certainly neither suggested it nor said that you've suggested it. I /have/ pointed out that having the Kylix helpfiles is no substitute to having Lazarus-specific ones because of the former's limited portability, which is hardly the same thing.

I suggest that we just drop this subthread, before it gets excessively tedious to the rest of the community. After all, we've all got things to get on with that are more suited to our skills, like writing code that doesn't involve reasoned public argument :-)

Seems to be a good project.

Could someone from LazCore make a test on it?

I think it should be a step foward to a Lazarus' Embedded Help System

2012/7/28 Kostas Michalopoulos

About the name "lazhelp":
I'm not a great namer myself, and tend to use technical names as well, so I understand your choice for the name.
But I fear the name "lazhelp" has become confusingly ambiguous.

To avoid name clashes with third parties the Lazarus developers prefix/postfix all new units, for example with "laz". If third parties use the same prefixes, we have a problem. ;)
So I ask anyone kindly to be more innovative when creating new projects.

Nice.

Huh?
The chm viewer "lhelp" has only "home", "backward", "forward" and a menu to open and close chm files. If I understood your above text correct, this is less than your viewer.

The reason for a separate executable is that the help viewer should be usable independent of any modal forms, mdi, hints or docking of the application.
Of course it would be nice to have a LCL control
to view chm files in applications. It should not be that hard to write.

Mattias

Mattias Gaertner wrote

Huh? The chm viewer "lhelp" has only "home", "backward", "forward" and a menu to open and close chm files. If I understood your above text correct, this is less than your viewer

You are right, i just found and compiled the viewer in my Lazarus. Actually it is the same as with my viewer, except that lhelp uses icons while i use text (also there is no menu but lhelp needs that since it is a standalone viewer).

I'm not sure i've ever encountered this program tbh. I remember some other program that was almost a clone of Microsoft's CHM viewer.

Kostas "Bad Sector" Michalopoulos

Yes, it should definitely be mentioned on

http://wiki.lazarus.freepascal.org/Add_Help_to_Your_Application

I recommend to put the package and the examples into separate directories.

Mattias

Isn't Kylix Help free now, with openKylix?

As for the x86 Linux only comment.... Well, tough sh*t to the Windows and Mac users. I paid for Kylix Enterprise, so why the hell may I not reuse what I paid a fortune for!

You are allowed to use it, but not to distribute it.

In any case, LCL is supposed to be a VCL clone (just like CLX), so the Delphi/Kylix help should be very appropriate to LCL - if not, then the Lazarus project didn't do a very good job cloning Delphi VCL.

In fact the LCL should have been based on the CLX, where many cross-platform issues have been removed - but the CLX was published only much later. Then FPC and Lazarus were extended with every new Delphi version, and some homebrew features have been added, but the really hard problems never have been solved properly.

I already suggested an native Win32 widgetset, fully VCL compatible, with limited availability on other platforms. This would make all those happy which want to move from Delphi to Lazarus, because all their projects would work almost immediately. And it could have been implemented in a fraction of the time spent with the LCL. Cross-plattform projects never have been covered by Delphi/VCL, so that it's not hard to tell people that such projects require a different GUI/widgetset (CLX, LCL...).

Furthermore I'm convinced that a portable GUI, based on a mix of native controls, is a beast and a waste of time. Either the controls should have native look and feel (skins!...), or the exact look and feel of some (Win32...) platform. I had preferred to use fpGUI or mseGUI instead of the LCL, but the according frameworks (IDE...) didn't match my expectations. Now I'm using a Lazarus IDE, tweaked to fit my needs, and stay away from projects with a sophisticated GUI or cross-platform ambitions.

DoDi

Hi,

Hans-Peter Diettrich wrote

Isn't Kylix Help free now, with openKylix?

Kylix Open Edition was available for free since 2001 when Kylix 1 was release. Every edition and version of Kylix included the help files as standard.

You are allowed to use it, but not to distribute it.

Yes.

In fact the LCL should have been based on the CLX, where many cross-platform issues have been removed

I agree 100% here.

- but the CLX was published only much later.

I don't know the exact timings... When did Lazarus start? I have heard 10 years ago, so that would have made it the same time as what Kylix 1 was released.

Furthermore I'm convinced that a portable GUI, based on a mix of native controls, is a beast and a waste of time.

+1
Each native widgetset has different features, do things differently, looks different etc. So there is no way you can get a 100% single source project based on such diversity - unless you only stick with the lowest common denominator - thus crippling your "cross platform" toolkit extensively. It's amazing LCL has gotten as far as it did - but also explains why it only attracts hobbyist programmer projects.

I had preferred to use fpGUI or mseGUI instead of the LCL, but the according frameworks (IDE...) didn't match my expectations.

fpGUI doesn't dictate what IDE you must use. I use both Lazarus IDE & MSEide to develop fpGUI or my fpGUI-based applications. You are free to even use Notepad, if you think that will make you more productive. :-)

Anyway, we are getting a bit sidetracked here.

Lazarus already exists since 1999.
AFAIR I came to Lazarus a year before Kylix was released, the Kylix IDE required wine to run, qt was far less free than nowadays and it was ugly windowish. There was no doubt to continue Lazarus.

Mattias

There is no cross platform helproduct, so that way you are fcked.

Now if you tell me CHM, that means I need to ship LHelp with my product because Linux & Mac users don't have CHM help viewers out of the box.

They have no decent help system out of the box. Seems the lowest common denomitor is plain html, which I would avoid.

The best route would be to create some fphttpserver that serves up chm content, but I don't know the FPC webcomponents enough for that.

But what is the source help format for CHM

For non API chms ? html + some index and project files.

and what tools (help editor) do I use to edit that source format

It is called an "html editor". Some people rough it though, and use a "text" editor. Holy wars have been fought

and what tool do I use to "compile" that source help format into the end result CHM file?

chmcmd, included with FPC since 2.2.x

Also, how does my product know where to find LHelp (or whatever CHM viewer I want to use)?

As said, that is not a CHM issue, but a "state of linux help" issue.

Marco van de Voort wrote

On Tue, Jul 10, 2012 at 05:39:05PM +0100, Graeme Geldenhuys wrote:

^^^^^^^^^^^

Well, that happens, when you try to be modern, and read your mail with mutt instead of elm :-)

FWIW your post made me realize i have a few uncommitted changes (including a very important one - outlines
https://coinsh.red/p/2018-08-30_20_27_48-Help_-_Welcome.png) for LazHelp :-P. I'm not working on it much though, it is mainly on life support with the rare addition of new stuff (mainly needed because i made it a target for a document preparation system i work on and needed some features from it).

On Sat, Aug 18, 2018 at 7:11 PM Marco van de Voort via Lazarus <

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus-ide.org/pipermail/lazarus/attachments/20180830/4c4cc4e1/attachment.html>

I only work on the non visual (CHM reader/writer) parts.

Recently there were some new bugreports from people that use chmcmd with Sphinx (a tool like fpdoc for .NET).

Sphinx is Python, not .NET.

I tried for 2 days to get read-the-docs (a web front-end for sphinx) to work. Never again ! The python dependencies are a complete disaster. Almost as bad as npm...

Michael.

hahaha... I was about to comment on dredging up such and *old* thread. The solution to the original question has been solved since a long time... DocView of course with the help source in IPF format. ;-)

Regards,
Graeme