[Lazarus] Building help files: the nitty-gritty

classic Classic list List threaded Threaded
111 messages Options
123456
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Building help files: the nitty-gritty

Mark Morgan Lloyd
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.

> On 16 July 2012 20:14, Marco van de Voort <[hidden email]> 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.

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.

> As I told somebody in a earlier reply, I don't mind shipping the help
> viewer - that is not a problem at all. I 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 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.

> 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?
..
> 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.

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.

> 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.

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.

--
Mark Morgan Lloyd
markMLl .AT. telemetry.co .DOT. uk

[Opinions above are the author's, not those of his employers or colleagues]

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Building help files: the nitty-gritty

Reinier Olislagers
On 17-7-2012 10:15, Mark Morgan Lloyd wrote:
> 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 :-)
Totally agreed.

>> On 16 July 2012 20:14, Marco van de Voort <[hidden email]> 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.
<snip>
> The current situation- and this is with Lazarus trunk, not stable-
> appears to be that HTML keyword-based application help works well
> provided <snip why HTML help might not be such a good idea>
> 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.
>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
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.


>> As I told somebody in a earlier reply, I don't mind shipping the help
>> viewer - that is not a problem at all. I 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.
I'd lean to this conclusion as well.

> 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.
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.

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Building help files: the nitty-gritty

Mark Morgan Lloyd
Reinier Olislagers wrote:

>> The current situation- and this is with Lazarus trunk, not stable-
>> appears to be that HTML keyword-based application help works well
>> provided <snip why HTML help might not be such a good idea>
>> 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.
 >
>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
> 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.

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

>> 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 ;)

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.

--
Mark Morgan Lloyd
markMLl .AT. telemetry.co .DOT. uk

[Opinions above are the author's, not those of his employers or colleagues]

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Building help files: the nitty-gritty

Reinier Olislagers
On 17-7-2012 10:55, Mark Morgan Lloyd wrote:

> Reinier Olislagers wrote:
>>> 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 ;)
>
> 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-----

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

>> 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.
Given the above this wouldn't really matter anymore, would it?



--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Building help files: the nitty-gritty

Mark Morgan Lloyd
Reinier Olislagers wrote:

> 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
>
>>> 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.
> 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).

--
Mark Morgan Lloyd
markMLl .AT. telemetry.co .DOT. uk

[Opinions above are the author's, not those of his employers or colleagues]

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Building help files: the nitty-gritty

Reinier Olislagers
On 17-7-2012 12:06, Mark Morgan Lloyd wrote:
> Reinier Olislagers wrote:
>
>> 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.
<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.

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Building help files: the nitty-gritty

Mark Morgan Lloyd
Reinier Olislagers wrote:

> On 17-7-2012 12:06, Mark Morgan Lloyd wrote:
>> Reinier Olislagers wrote:
>>
>>> 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.
> <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.

--
Mark Morgan Lloyd
markMLl .AT. telemetry.co .DOT. uk

[Opinions above are the author's, not those of his employers or colleagues]

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Building help files: the nitty-gritty

wkitty42
In reply to this post by Mark Morgan Lloyd
On 7/16/2012 13:20, Mark Morgan Lloyd wrote:
> 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".
>

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 ;)

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Building help files: the nitty-gritty

Marco van de Voort
In reply to this post by Mark Morgan Lloyd
On Tue, Jul 17, 2012 at 08:15:29AM +0000, Mark Morgan Lloyd wrote:

> 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.

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)

> 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.

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.
 
> 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.

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 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.
 
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.

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Building help files: the nitty-gritty

Michael Schnell
In reply to this post by Graeme Geldenhuys
On 07/17/2012 12:15 AM, 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

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Building help files: the nitty-gritty

Michael Schnell
In reply to this post by Graeme Geldenhuys
On 07/17/2012 12:15 AM, 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

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Building help files: the nitty-gritty

Mattias Gaertner


Michael Schnell <[hidden email]> hat am 18. Juli 2012 um 11:54 geschrieben:

> On 07/17/2012 12:15 AM, 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.

 

Can you give an example?

 

Mattias

 


--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Building help files: the nitty-gritty

Michael Schnell
On 07/18/2012 12:15 PM, Mattias Gaertner wrote:


 Can you give an example?


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

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Building help files: the nitty-gritty

Graeme Geldenhuys
In reply to this post by Michael Schnell
Hi,

On 18 July 2012 10:48, Michael Schnell <[hidden email]> 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.


--
Regards,
  - Graeme -


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

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Building help files: the nitty-gritty

Michael Schnell
On 07/18/2012 12:49 PM, 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

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Building help files: the nitty-gritty

Mark Morgan Lloyd
In reply to this post by Graeme Geldenhuys
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.

> 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

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

--
Mark Morgan Lloyd
markMLl .AT. telemetry.co .DOT. uk

[Opinions above are the author's, not those of his employers or colleagues]

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Building help files: the nitty-gritty

Reinier Olislagers
On 18-7-2012 13:18, Mark Morgan Lloyd wrote:
> Graeme Geldenhuys wrote:
>> 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
>
> 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


--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Building help files: the nitty-gritty

Reinier Olislagers
In reply to this post by Michael Schnell
On 18-7-2012 13:04, Michael Schnell wrote:

> On 07/18/2012 12:49 PM, 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).

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


--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Building help files: the nitty-gritty

Graeme Geldenhuys
In reply to this post by Mark Morgan Lloyd
On 18 July 2012 12:18, Mark Morgan Lloyd
<[hidden email]> 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?

--
Regards,
  - Graeme -


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

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Building help files: the nitty-gritty

Michael Schnell
In reply to this post by Reinier Olislagers
On 07/18/2012 01:41 PM, 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

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
123456