Hi, I have been experimenting with chromium embedded and the power is endless. It's like being able to write CGI programs but on the desktop with no server needing to be installed.

I was thinking documentation for software could benefit from having a chromium embedded (or firefox embedded) system.

The issue with static plain html documents is that they aren't really powerful like a full fledged .CHM system or .hlp system. But even chm and .hlp files are primitive, they are just basic, and 1990's technology.

With chromium embedded it seems you can literally do anything you want: combine lazarus widgets with a web server like program, but without requiring a web server. I.e. you can output to the web browser just like a cgi program can, but no server side needed, it's all done on the client.

To me this seems like the perfect help system tool as you'll get something far more powerful than a PDF file... you can highlight text using lazarus code and callback back to the browser, whereas PDF files are not so programmable and controllable with code. I don't even know if pdf is scriptable.

The biggest issue with help documents is they are usually either static PDF files that are not in any way searchable like an online documentation on a web server.... or they are static html files without any power added to them, or they are chm files which are simple but not so powerful.

It seems there is almost a mismatch where people want a PDF file but also want to use google for help. This leads to the help files not really being integrated into the app and people just end up using google to find help on their program. The way I see it is if there was a chromium embedded or firefox embedded help system you wouldn't need google as much, as you would have the documents on your client like in the old days with Delphi 5 and 6 when you just pressed F1 and it took you to the page. F1 local client help just like delphi could in fact be automated with chromium embedded the same way delphi had it with the old documentation system from the 1990's... but with chromium embedded, you get rich html help documents, not old html document style from 1990's..

As much as I love CHM/HLP file systems from Ms Winblows it seems that one could even develop a more powerful one with chromium embedded and callbacks back and forth to the component....

Now I haven't much looked into the current Lazarus help system or what people use for help systems in popular lazarus apps, but I'm posting this to the mailing list as an idea for anyone who wants to make a rich help system with a rich integrated help system.

The issue with opening an html file in a browser for help, is that the person has to leave their application and then alt tab back to it, whereas a chromium embedded help system could be put right into the software itself not a separate browser application. And the issue with chm files as I see it, is they are a simple format from the 1990's with limitations (As much as I respect simple formats from long ago.. some help systems need to be richer)

PDF files are indeed very rich documents but they lack programmability. For example F1 online (or rather offline local client) help like in Delphi 5 seems not possible, even though delphi 5 help is 1990's technology and pdf files are modern.

There seems to be a mismatch here where you have fragmented help systems on modern software, and people end up basically abandoning help systems and instead just go on google and search. Maybe the old delphi 5 style F1 help system could be brought back, but with a modern flare: chromium html pages, with javascript possible too if absolutely necessary, to make them richer. But the cool thing about chromium embedded is you can avoid javascript by using fpc/lazarus code as callbacks instead of relying just on clunky javascript.. i.e. you can mix modern pascal code in with HTML to render, search, display, etc.

So I'm not talking about just a help system for lazarus (the current one may be just fine) but a help system architecture for all software apps released in the future! Apps developed with lazarus, not just lazarus itself.. and apps developed with delphi and other tools.

Lars wrote

powerful like a full fledged .CHM system or .hlp system. But even chm and .hlp files are primitive, they are just basic, and 1990's technology.

One thing you are overlooking is that most help authors don't use any of the advanced features of the existing help systems.

For example:
OS/2 INF/HLP help system has by default 2-way communication support. This is an excellent way to incorporate step-by-step tutorial help. In all my years of using OS/2, I've *never* seen anybody use that feature - except IBM. IBM did it very well, in where the help window tells the use what to do, a overlay appeared over the application window highlighting what the help is referring too. The user does what was instructed, and the help window automatically updates to the next step so so forth. Brilliantly useful, but nobody used it.

With chromium embedded it seems you can literally do anything you want:

The down side being you need to have a 80-250MB application (full Firefox or Chrome or Chromium browsers and all dependencies) installed just to view some help contents.

Also what happens if you don't use Firefox or Chrome?

Also starting up those web browsers, even in an embedded environment is a slow process and they are huge and memory hungly!

A decade ago I researched all of these things for a client of mine. We wanted offline help, must be searchable, help must load instantly (even a 1 second loading time is too slow), the help contents must be easy to author and no large supporting libraries/runtimes etc. My client also wanted context sensitive help down to the widget on a form level. It is atrocious that applications don't supply good offline help (if any help is even supplied) these days.

It was surprisingly hard to find a solution, especially something cross-platform. In the end I researched help formats with the goal to implement our own help viewer. We looked at Microsoft's HLP, CHM formats, IBM's INF, OpenOffice's help, Gnome's help sytem and a few others.

Long story short, in the end we decided on the IBM created INF help format, and I implemented a cross-platform help viewer that ticks all the requirements listed above and more.

fpGUI's DocView help viewer was born. A 1MB help viewer that can load and parse not just one, but multiple INF files, and display the requested help topic in under a second. If multiple INF files were loaded their TOC get merged into a single TOC treeview. If they supply Index details, those too get get merged into a single Index view, or a Index can be has advanced search features,
hyperlink support, the usual rich text display features, bookmark support, user defined inline annotation support and DocView includes its own help file describing all its features (help on help).

The INF help file format is impressively efficient in speed and size (help topic contents are indexed lookups to a global word dictionary - reducing size, allows for full-text searching etc). The INF help compiler I use is a cross-platform open source implementation from the OpenWatcom Compiler project. A single small executable with no external dependencies. FPC's fpdoc also supports generating IPF output which can then be compiled into binary INF help files.

DocView can also be integrated with LCL or fpGUI application. If you log into the Lazarus Forum and view the following link, there is an attached source code of a LCL application, showing exactly how to integrate DocView with LCL applications to give you context sensitive help.

http://forum.lazarus.freepascal.org/index.php/topic,27864.msg173887.html#msg173887

It can also be integrated into Lazarus IDE, Delphi IDE or any programmer editor that supports "external tools" functionality - without needing to compile and install IDE add-ons, yet still gives context sensitive help per keyword.

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

they are static html files without any power added to them, or they are chm files which are simple but not so powerful.

What I also don't want from a help file is a Telly Tubbies like looking help text. By that I mean, some idiot with no flare for typography and design, being allowed to author and "customise" help content to death - making my eyes bleed just yes, I've seem many such CHM help files.

That's why I like more minimalist help text (think OSX). It gets the point (help) across without making my eyes bleed, and no ugly distractions. DocView does allows for some end-user customisation though
- changing the proportional and mono fonts used, font size, page background color and search highlighting color. The help content author doesn't need to stress about those "customisations" as it is not up to them to force their (possibly ugly) design onto the end user.

The idea of help text is to help the end-user as efficiently as possible. It is not an excused for the help author to say "oh, look what I can do with colors, fonts and terrible design skills".

As far as I'm concerned HTML is not a good choice for a help format. It's way to verbose and gives too much "design power" to the help author
- without allowing end-user customisation. Adding JavaScript and such to the mix will make the problem even worse. Also, not all HTML viewer components are created equals. Just compare LHelp output so say kCHMViewer or Firefox.

to the mailing list as an idea for anyone who wants to make a rich help system with a rich integrated help system.

And I posted my personal opinions, which I know others might not agree with - but there you go. ;-)

Regards,
Graeme

Can the content of the wiki and FPC's guides be shown/searched with it too?

Mattias

Mattias Gaertner wrote

Can the content of the wiki and FPC's guides be shown/searched with it too?

Wiki no, FPC guides yes.

I believe somebody was working on a "wiki exporter" tool at some point, so the Wiki content could be made available offline. I assume it would result in offline HTML files. That could then be converted (with another tool) to INF in there was a need.

ps:
Don't knock my obsession with offline help. :) Just 3 weeks ago, I was stuck with no Internet for 7 days. Thank goodness for all my offline INF help files. ;-)

Regards,
Graeme

I would like to test that. Can you give me a link or hint?

I believe somebody was working on a "wiki exporter" tool at some point, so the Wiki content could be made available offline.

There is one in lazarus/components/wiki. wikiget downloads the wiki sources. And there is wikiconvert which outputs html, chm or xhtml. Some elements are not yet converted correctly.

I assume it would result in offline HTML files. That could then be converted (with another tool) to INF in there was a need.

... or add a direct converter from wiki to inf.

Mattias

Mattias Gaertner wrote

> Wiki no, FPC guides yes. I would like to test that. Can you give me a link or hint?

Regarding the FPC guides. I consider the FPC Language Reference the most important one, so I manually converted it (and keep it in sync with FPC releases when I can), and also added my own additions to take advantage of the INF format. See attached screenshot.

As for the others guides, I wrote a tool that does LaTex to IPF conversions (that was hard). I also did a HTML to IPF tool. But in both cases some elements are not yet converted, and generally the formatting is not nearly as good as it should be (my standards are high when it comes to help formatting). So I don't publicise what I don't think is of high enough quality yet.

Take the Free Pascal CHM help as an example - it is horrific looking. The fpdoc's HTML output writer was clearly designed for online HTML usage with popup browser windows and decent CSS support etc. The CHM conversion of that gives broken links, unsupported features and bad formatting. It just gives the documentation a bad wrap. fpdoc should have a dedicated CHM output writer. The same can be said for an ePub HTML output writer (if that ever materializes).

There is one in lazarus/components/wiki. wikiget downloads the wiki sources. And there is wikiconvert which outputs html, chm or xhtml.

Ah, thanks. I'll take a look at that when I have a moment.

... or add a direct converter from wiki to inf.

Yes, that would be the best solution.

Regards,
Graeme

Is this a problem of the CHM producer or the CHM viewer?

It just gives the documentation a bad wrap. fpdoc should have a dedicated CHM output writer. The same can be said for an ePub HTML output writer (if that ever materializes).

Mattias

Mattias Gaertner wrote

Is this a problem of the CHM producer or the CHM viewer?

Both. The LaTeX-to-HTML conversion is definitely not great. Michael would agree on this one. Then taking that already bad HTML and converting in to CHM, makes the end result even worse. That doesn't do any justices for Michael's hard work in writing the documentation and having it beautifully presented (like the official PDF versions).

fpdoc's HTML output is designed for online viewing with a web browser. What it generates and how it generates it is not always appropriate for offline viewing, and doesn't take into account CHM viewers and how they differ from web browsers like Firefox or Chrome. Hence my suggestion that a dedicated CHM output writer is needed for fpdoc.

Viewing CHM files are also not equal with all CHM viewers. Although LHelp's HTML component has improved much, it is not a match to KCHMViewer, Microsoft's Help viewer or the likes - which use full blown embedded web browser components. For example, take a look at how Delphi's CHM help looks when viewed with KCHMViewer vs LHelp (1).

LHelp has other flaws too... slow loading times (though that has improved), flaky search results, incomplete or missing TOC entries (compared to what other CHM viewers show for the same CHM file), toolbar arrow navigation that sometimes don't work, broken rendering of images (2). Then there are also useful features missing that every dedicated help viewer should have: ability for some user customisation like adjusting the font size or page background colour, user annotations (inline or otherwise), bookmarks, advanced search (match this but not that, match phrases etc).

Many of LHelp's issues can be addressed, but LHelp doesn't receive much love. I guess the major problem is that CHM is widely considered a Windows-only file format, thus the default viewer is mostly Microsoft's built-in help viewer (when Windows is the platform). Considering that Lazarus promotes multi-platform support, other platforms need to live with the failures of LHelp, or look elsewhere like KCHMViewer - but the latter pulls in its own huge list of 3rd party dependencies.

[1] http://geldenhuys.co.uk/~graemeg/temp/kchmviewer_vs_lhelp.png [2] http://geldenhuys.co.uk/~graemeg/temp/kchmviewer_vs_lhelp_2.png

This discussion is nothing new. I remember mentioning these same issues some years ago.

Regards,
Graeme

Now that I think about my post about using chromium embedded for a help engine, the issue I see is that it's a large dependency .. so for small applications that are say 1MB large, and you want to supply a help system with it... all of a sudden the 1mb exe has to be shipped with a gazillion other files that wouldn't be needed with a more simple format.

Still, I think I will try to release a help system for powtils using chromium embedded, as an offline experiment with CGI (no web server needed). However this will take time, and I almost feel like I posted that chromium idea drunk, even though I was not drinking.

....

On 24 October 2016 at 00:34, Lars via Lazarus <

I think using CEF is fine as there don't seem to be any other realistic options. That is the situation as it is. Something which is likely to get more support is "more better" than a perfect but little used and little known system. A Lazarus installation currently takes over 1 Gb, so what difference does another 300Mb make to it when it is something as critical as help? INF files and viewers may be fine, but besides Graeme who is willing to make the time and effort to learn it well enough to support Graeme to develop it further?
It may sound cynical but that is the state of contemporary systems development where the idea is to settle for less than ideal systems and hope that by throwing enough people at these sub par systems the flaws will be worked out, or made "good enough".

vfclists . wrote

I think using CEF is fine as there don't seem to be any other realistic options. That is the situation as it is.

No it's not! If you have a login for Lazarus Forum's, check out this post with a fully functional application with context sensitive help. That's an application (small), help contents and a help viewer - all under 2MB in size.

http://forum.lazarus.freepascal.org/index.php/topic,30421.msg193651.html#msg193651

known system. A Lazarus installation currently takes over 1 Gb, so what difference does another 300Mb make to it when it is something as critical as help?

If anybody things installing 300MB just to get some lousy help for a small 1MB application is acceptable, then you need to seriously re-evaluate your career as a software developer. Also, my clients don't have Lazarus installed, so 300MB 3rd party files for a 1-10MB application is a MAJOR issue!

For online distribution and online updates, size does matter.

INF files and viewers may be fine, but besides Graeme who is willing to make the time and effort to learn it well enough to support Graeme to develop it further?

I'm more than willing to implement any new feature I deem worthy or beneficial for a help system. IBM did a stellar job designing the INF help system, and it was also used for eBooks - 10+ years ahead of the likes of ePub, AZW etc.

I've said it a million times before, HTML is the worst markup for a help system. It's just to verbose, and the HTML Viewers are too inconsistent with features they support.

Read my previous posts on all the features that INF and DocView supports. I'm not bothered about popularity contests, so if nobody else uses INF, there loss. I can say that I've used it for years in my own applications and 4 of my past clients use it in commercial software too.

hope that by throwing enough people at these sub par systems the flaws will be worked out, or made "good enough".

I welcome your thoughts on why you think INF or DocView would be sub par?

ps:
Did you see the sub par user experience is these CHM files?

http://geldenhuys.co.uk/~graemeg/temp/kchmviewer_vs_lhelp.png http://geldenhuys.co.uk/~graemeg/temp/kchmviewer_vs_lhelp_2.png

Regards,
Graeme

Graeme Geldenhuys wrote

It was surprisingly hard to find a solution, especially something cross-platform. In the end I researched help formats with the goal to implement our own help viewer. We looked at Microsoft's HLP, CHM formats, IBM's INF, OpenOffice's help, Gnome's help sytem and a few others.

I thought I should elaborate on this process a bit, after reading Frank's last message - in case somebody else gets the wrong impression. The research wasn't a quick search on the Internet one afternoon. Cross-Platform Help was very important to my employer. We spent 3 months researching and evaluating help viewers and help formats. We did extensive testing and looking at all aspects around help - from ease of authoring help, efficiency of file formats, file sizes and help viewers.

After all that, I think we came up with a very good choice, and a solution that ticked all our requirements. My employer was also kind enough to donate back all the work that was put into it, hoping others would benefit from this. After all, they benefited hugely from all the effort others put into Free Pascal and Lazarus.

Regards,
Graeme

On 6 November 2016 at 23:20, Graeme Geldenhuys via Lazarus <

I am not questioning the value of the INF format, DocView and other associated utilities. I am just trying to say that this is the current state of affairs today, and for the last 20 years as well, where the computing industry has been try to shoehorn every da*n thing into Javascript and HTML, and who knows what the industry "leaders" will come up in their bid to fit square pegs into round holes and channel users into their increasingly restricted systems? I mean the latest thing now is WebAssembly which shows how ridiculous the whole business has become. It is not a fault on Lars end that he sees CEF as the best way to provide help. It is just the way things are. Computing environments have gone full retard in service of the browser and the web.

BTW, is there an INF to HTML convertor that would enable documentation to be developed in INF then translated to HTML for those who want dumbed down display systems?

vfclists . wrote

computing industry has been try to shoehorn every da*n thing into Javascript and HTML, and who knows what the industry "leaders" will come up in their bid to fit square pegs into round holes and channel users into

Exactly, and there is no reason to follow those idiots - I know I don't. INF (by IBM) and HLP (by Microsoft) was designed from the ground up as help file formats. The are very good at what they do. Having studied both in depth, I think IBM did a much better job, and has more features than HLP had. The only mistake IBM made was that the developed a crappy INF viewer. That's were DocView fills the gap - much more modern and user friendly INF viewer.

BTW, is there an INF to HTML convertor that would enable documentation to be developed in INF then translated to HTML for those who want dumbed down display systems?

That totally defeats the point of a descent and useful help viewer. Saying that, I have implemented an export option for DocView where you can export selected help topics to plain text. I'm also busy writing a new exporter using the new fcl-pdf package, so DocView can export selected topics to PDF.

The idea of this export functionality is to easily print or collate information (help topics) of interest in one condensed file. I don't really use this too much these days, as DocView also supports Bookmarks, which is simply faster.

Creating a exporter for HTML shouldn't be hard either, but I think the PDF format will be much more useful, and like INF, everything (text and images) are contained in a single file.

Regards,
Graeme

I was speaking of a help system for any application, not just lazarus alone... i.e. you build a 2mb exe and ship it to your customer (not lazarus.exe but another exe built with lazarus)...

So now your elf/exe has to include a huge dependency... Chromium is not just one dll. It would be ideal if it was only one dll, like mysqlite.

So if you build a 2-6mb app, now you have to ship yet more files increasing the size further.

Maybe not a huge issue with todays high speed internet connections, but it still is another dependency.

vfclists . wrote

Something which is likely to get more support is "more better" than a perfect but little used and little known system.

One issue is firefox has a track record of not supporting embedded browser for very long without abandoning it, or changing the api to make it incompatible with old code... so who says this isn't also going to happen with chromium (CEF) at some point... Hopefully chromium will not go down the same path as firefox embedded. I do know, that CEF1 has some features that are incompatible with CEF3 so they've already broken some things... hopefully cef3 stays stable api for a long time and there is no cef4 that comes out which breaks old cef3 code.

Graeme Geldenhuys wrote

If anybody things installing 300MB just to get some lousy help for a small 1MB application is acceptable,

Maybe CEF needs a lite version. I am guessing that chromium embedded pulls in a lot of unused code that is not needed for most cef embededded browser apps.

Would be nice if there was a CEF (chromium embedded) lite which was only, maybe 10MB. Obviously, I'd prefer a 100KB option over even a 10MB option....

300MB seems awfully like bloatware to me.. is it really 300MB to ship the latest CEF 3? I haven't checked. Even if it was 110MB that's still too large.

vfclists . wrote

I mean the latest thing now is WebAssembly which shows how ridiculous the whole business has become.

Web assembly, if designed properly, might actually get rid of some problems. Javascript is a large mammoth, or ugly beast. Web assembly may allow one to for example compile freepascal code directly to byte code that runs in the browser, instead of people using ugly obfuscated bloated javascript "hacks".

It's sort of like a JVM bytecode, but for the web browser. Or a .net bytecode. I don't fully know what web assembly intends to be, as it's not completed yet fully, but, it may actually get rid of some of the javascript bloated crap out there.

Lots of people may in fact ignore webassembly and continue to use javascript. God forbid.

It is not a fault on Lars end that he sees CEF as the best way to provide help. It is just the way things are.

Not necessarily the best, because of the large dependency..

If CEF (chromium embedded) offered a lite version that was only 2MB to ship with an exe, or 500KB then it may in fact be a good solution for help..

Lars wrote

Maybe not a huge issue with todays high speed internet connections, but it still is another dependency.

Not all internet connections are equal in all countries. In the UK, 8Mbps is currently the average speed. In South Africa the average speed would be 256-512Kbps (yes, that's with a K). The highest "reliable" speed (take that with a huge pinch of salt - as you never get close to that speed in reality) in South Africa is 4Mbps. A stark contrast to the UK's affordable and reliable 75-200Mbps. And apparently the UK is lagging behind other countries too.

So an additional 10MB download can make a huge difference, depending where in the world you live. Adding a 100-300MB for each application download is simply absurd.

Regards,
Graeme

Lars wrote

One issue is firefox has a track record of not supporting embedded browser for very long without abandoning it, or changing the api to make it incompatible with old code... so who says this isn't also going to happen with chromium (CEF) at some point...

My point is, for a help system you really don't need the latest and greatest HTML5 features. It's simply not needed. What you do want in well formatted text, images and some basic rich text styles. Good help is more about the contents and the speed of getting to that contents, that about the presentation. But some people are more obsessed about presentation with rubbish or near zero content.

Regards,
Graeme

Lars wrote

It's sort of like a JVM bytecode, but for the web browser.

That makes you wonder, why not simply go back to Java Applets. They came out in 1996 and I thought they were brilliant for web applications. You had the full power of the Java language and graphics stack at your disposal.

Yes there was phase when Java had some security issues, but those were resolved, and any future security issues could be resolved just as easily. I simply don't understand why they must always try and reinvent the wheel, when they could simply fix or improve the wheel.

Regards,
Graeme

If you can store a reasonably abstract inbetween format that would be good.

Take the Free Pascal CHM help as an example - it is horrific looking. The fpdoc's HTML output writer was clearly designed for online HTML usage with popup browser windows and decent CSS support etc.

The HTML output writer is parameterizable. IOW there is html output and chm output. The original CHM output was designed for the Windows help viewer though, not Lhelp.

It works fine in the IDE though.

The CHM conversion of that gives broken links, unsupported features and bad formatting.

This is incorrect for fpdoc output, as it is not the html data that is being converted. So I'm going to need examples here.

I seriously doubt that. It's just something that will exist next to javascript but in essence will perform the same tasks as javascript. You can create relatively clean and structured javascript if you want. It just requires discipline as the language doesn't enforce it.

The problem is IMHO not so much the language, but what you do with it.

Lots of people may in fact ignore webassembly and continue to use javascript. God forbid.

Well, there is interest in a WebAssembly backend for FPC. Someone is as we are working on a transpiler from Pascal to Javascript.

Michael.

Michael Van Canneyt wrote

I seriously doubt that. It's just something that will exist next to javascript but in essence will perform the same tasks as javascript.

==OFF TOPIC== (so ignore if there is not a very short answer)

Any plans for a webassembly support with FPC ?

-Michael

I wrote it in the email you are replying to. Please re-read.

Michael.

Hi,

I may have missed this point in the discussion, but would it not make more sense to get a native HTML component (either from IPro or the THTML port) to the point where it can provide everything needed? THTML (my favourite) already has fairly solid layout and CSS support, so it should provide most things that are required. What it does miss is proper DOM access and manipulation, but I'd rather see efforts focused there than on CEF, which would require the same work to wrap it on the pascal side anyway...

Depending on the scenario, we might get away without any Javascript support by using PascalScript, iff there would be some interface between DOM and the host application.

Certainly doing that would result in lots of reusable code for completely different applications.

Martok

+1

There is an old thread about it here:

http://forum.lazarus.freepascal.org/index.php/topic,28836.0.html

Many skeptics, but many think it is an interesting idea even though skeptical.

And what happened to microsoft silverlight? did anyone care?

One issue, back in the day, was that you could only use Java programming language, right? At that time no one had thought of multi language jvm targetting with different originating languages... all java applets were java programming language coded, afaik...

I could be wrong.

Another issue with java applets is you had to make sure they were installed correctly, whereas javascript need not install. With webassembly I don't think there is a java system you have to install on the machine. Java applets required first downloading the JVM from Sun, right?

It's been so long since I've seen a java craplet (that's the locker room talk name for it) that I cannot remember.

...

+1

Well the reason chromium is in my line of sight, is because other people do the work to maintain the browser for you. Creating your own web browser component is massive amounts of work, whereas chromium is coded by other people. True you have to write wrappers around it, but you also end up with a standard component where there are already plenty of c++ examples to learn from, and you are supported by a massive team over at chromium. Whereas writing your own browser component requires constantly playing "catch up", implementing every feature needed which chromium had 5 years ago.

So does IPro or THtml have any large following and existing codebase to work with? I would have to learn about these as I have not used them.

Agreed, but when you need documentation to look as professional as a PDF file, HTML 5 could be useful. I find the documentation, for example, for Total Commander, to just be a little bit too Windows 3.1 looking. It's may be good documentation filled with lots of good text, but it feels like something from Windows 95 or windows 3.1. For professional software apps a windows 3.1 look may be just a bit too off putting. In the case of total commander, the folks who use total commander are they types of nerds that don't care. But for modern professional capitalism sold apps, I think help documents have to look more modern. As much as I hate modern, just for the sake of being modern. Like some kind of fashion show.

Michael Van Canneyt wrote

I seriously doubt that. It's just something that will exist next to javascript but in essence will perform the same tasks as javascript. You can create relatively clean and structured javascript if you want. It just requires discipline as the language doesn't enforce it.

I start off by writing some javascript and I think, hey this isn't so bad. But eventually after about 10 paragraphs of code it starts to get ugly, no matter what I try. That's why there is a book written called "Javascript, the good parts" because it has become such a large mammoth that they needed to write a book about a subset of java that may (or may not) be the good parts. Whether those are the good parts or not, is still up for debate, because I haven't read the book. If I had time..

The problem is IMHO not so much the language, but what you do with it.

Okay but take brainf*ck language as an example. In this case the language is in fact a serious problem. Or take C++. The language just encourages you to do nasty things when you need/want to. In order to write sensible looking C++ code you should... just use a subset of C++, such as C, and avoid most C++ features. But then you call in some library and they are using that feature, so, you have to use it too... the issue with javascript is you pull in a lot of libraries that make use of the features so you have to end up using them indirectly too.

Again, I guess I should read the book "Javascript the good parts" if I have time.

That's good news, and I have no idea how you guys keep up with all this crap that comes out every year. The work required to port fpc to all these systems, whether virtual machines, or real machines, is enormous.

What ever happened to LLVM ? much interest? Yet another port to a virtual machine.

I wrote it in the email you are replying to. Please re-read.

Sorry for hitting the send button too early :-(

-Michael

Lars wrote

One issue, back in the day, was that you could only use Java programming language, right?

Hence the name "Java Applet" ;-)

Another issue with java applets is you had to make sure they were installed correctly,

No, the web server served it to the web browser, just like it does with HTML, CSS etc. Later they introduced WebStart which allows you to run the Java Applet or Application outside the browser window too - thus the embedded window was not a requirement any more.

Java applets required first downloading the JVM from Sun, right?

Correct, just like you need to download and install a Flash plugin before you can view the crap flash-based ads. But if there was enough of a push, a Java runtime could easily have been included with a web browser (just like there Javascript Engines - Netscape did both, so did Opera back in the day), or include a Java runitem as standard with the OS itself (like IBM did with OS/2).

But as with everything Internet based, everything has a maximum shelf life of 6-12 months, then something new must be introduced.

Regards,
Graeme

Lars wrote

I find the documentation, for example, for Total Commander, to just be a little bit too Windows 3.1 looking.

I'll bet you a 6-pack of beer that the documentation was written by the developer himself. That would explain the lack of typography. :)

Regards,
Graeme

True, but you also subscribe to an engine with a lot more known vulnerabilities and attack surface that way.

The frequent updates that often break interfaces are also an headache.

If multi versions installs are not possible or hard, that would complicate keeping old IDEs running.

Creating your own web browser component is massive amounts of work, whereas chromium is coded by other people.

But deployment and updating is still yours, and a tad more involved.

If I would replace lhelp and chm, I wouldn't go that way, but some way with a local webserver (for searching and the like), and just use whatever is installed.

The best reason to have some local (whatever how limited) widget is for IDE popups of helptext instead of an external browser.

But I think lhelp still has enough leeway, and I think Graeme greatly overexaggerates the problems.

[...] The best reason to have some local (whatever how limited) widget is for IDE popups of helptext instead of an external browser.

Good point.

Mattias

Marco van de Voort wrote

But I think lhelp still has enough leeway, and I think Graeme greatly overexaggerates the problems.

And my comparison screenshots (from earlier) show the problem as clear as day. Your comment about "LHelp works fine with fpdoc generated CHM" is a moot point. LHelp is also used for shipping your own application with help and a help viewer (Linux, OSX, FreeBSD, Solaris etc don't include CHM help viewers as standard), in which case you will not be using fpdoc to author application help. The inconsistency of HTML rendering components is a real problem.

Regards,
Graeme

That was also one of my reasons, too. It doesn't even have to do everything modern HTML can (on the part of the layout engine, there haven't really been that many changes anyway), but something to view rich content (purposefully not saying 'RichView' here...) would be good to have. HTMLHelp would really just be one of multiple applications for it.

Graeme Geldenhuys wrote

The inconsistency of HTML rendering components is a real problem.

Yet another reason against the IE5 of this decade.

But, could one compile fpc code to javaapplet jvm bytecode? Why no one thought of this idea? And when I say fpc, I mean literally any language not just fpc. We already have tools that convert languages to jvm runnable code, so why not java applets programmed in other languages?

But it's not just say Ghislers writing style or formatting, but the general look of the old help systems from windows 95 era. i.e. any chm/hlp system appears to be win 3.1 looking, or if not win 3.1, then win 95 looking.

As much as I really appreciate simple text documentation with minimal html bloat, I'm thinking more of the professional $250 software app or $99 software app that needs to ship a documentation system that will make people feel satisfied for their dollar. An old win 3.1/win95 style hlp/chm system just seems a bit too cheap.

But, I'm nit picking. I do appreciate simple documentation without eye candy crap.

Marco van de Voort wrote

The frequent updates that often break interfaces are also an headache.

This is what happened to firefox: xul runner's current state is broken/unknown/scary. I hope the same doesn't happen to chromium. Cef1 has some incompatibilities with cef3 but at least not as bad as the firefox embedded xulrunner state of affairs.

If I would replace lhelp and chm, I wouldn't go that way, but some way with a local webserver (for searching and the like), and just use whatever is installed.

A local web server as in running on port 80?

The issue I see here is what if someone has apache installed already?

The advantage of no web server at all is you have no conflicts with port 80 already running an apache instance.

But maybe I misinterpreted what you are saying.

>> The best reason to have some local (whatever how limited) widget is >> for IDE popups of helptext instead of an external browser.

External browser requires alt-tabbing away from the ide which is a pain. A external browser cannot be communicated with once you open the html file. with a local widget, you can communicate with that widget. With an external browser, once you've loaded the page there is no way to communicate. An an external browser doesn't offer a search system if it's a static html file served off line. So then you end up with people just using google and online help and stack exchange, instead of reading documentation.

My idea with chromium embedded is to write the documentation for an online web server, but then easily port it to offline documentation served with chromium embedded. No local web server needs to be installed on port 80 conflicting with any other servers on the users computer. Html anchors can be used to scroll to certain parts of the documentation. Or if anchors are not enough, there is always javascript.

But, my idea of using chromium embedded is sort of a dream ruined. Because of the large 100+MB dependency it pulls in, as pointed out by others (i.e. Graeme said 300MB, maybe that was exaggeration).

A local ngnix server or similar could serve documentation (or even nYume or Aservia) however this requires that a port 80 be tied up, or another port alternative to port 80 which may be blocked by firewall. That I would want to avoid, as it's just another hassle.

It's amazing someone hasn't thought of a web server that works off line, that uses no ports, and just runs as some kind of plain Exe not using any http port... Not sure if this is an absurd idea (actually, that's kind of what chromium embedded is).

Do you mean showing HTML pages in a HTML control and handling links without TCP ports?

Mattias

Lars wrote

I do appreciate simple documentation without eye candy crap.

:) Just take a look at Apple's OSX built-in help (not the online content). It is minimalist and mostly text - with a hint of good typography. It works! Microsoft Windows 7 does very similar to Apple - simple and elegant.

You don't need some Telly Tubbies color scheme in your help contents (just because HTML allows for it) - it just distracts from the help itself. I've seen many such [terrible] CHM or HTML help in my days.

Regards,
Graeme

Lars wrote

But, could one compile fpc code to javaapplet jvm bytecode?

FPC 3.x can compile to Java Bytecode, but I've never actually tried it myself.

Regards,
Graeme

Lars wrote

port alternative to port 80 which may be blocked by firewall. That I would want to avoid, as it's just another hassle.

You can always use any other port >1024 for that. I've implemented a commercial application that works mostly online, but we wanted a offline version too. So I built a local mini webserver inside the main application. The application launched your default web browser with a URL and port number which the main application served. It worked beautifully.

But for help, firing up Chrome of Firefox is just too damn slow, and eats way to much memory. Also you will have to implement your own search (which will be slow over HTML files), table of contents and index pages. Then what about other useful features like bookmarking a help topic, inline annotations (user defined notes added to a help topic at runtime).

As for communications with a external [dedicated] help viewer. fpGUI's Docview does that via IPC, Microsoft's WinHelp I think could do it too, OS/2 VIEW help viewer did lots of 2-way communications with applications.

Regards,
Graeme

what's wrong with something like LHelp and using IPC to tell it where to load the next help from that the user has asked for??

from these cheap seats i have way over here, it seems like you are over engineering this...

I've always liked the website delphibasics .co .uk (or whatever the address is).

Would the current help systems be even capable of looking like that? Must be just a few div boxes. Really simple, interesting color shades. No fancy garbage, just simple boxes of text.

No issues with default firewalls? Last thing I want, is a customer having to futz around with router firewall, windows firewall, etc.

....

But for help, firing up Chrome of Firefox is just too damn slow, and eats way to much memory. Also you will have to implement your own search (which will be slow over HTML files), table of contents and index pages.

But isn't that what iota full text search is for, to preindex all the search stuff so no time is spent grepping through html files....

The issue with Iota I found was that it was written in an old fpc style where some things are not proper code, but compiled at that state of fpc development. iota, if you don't know, is a full text search indexing library for fpc. Discussed briefly on the fpc mailing lists eons ago.

Then what about other useful features like bookmarking a help topic, inline annotations (user defined notes added to a help topic at runtime).

User defined notes, were not available in chm files were they? I thought chm/hlp file were just dumb, fixed help files with no bells an whistles. i.e. total commander style help.

With a chrome embedded browser object, you can use the DOM to manipulate the document. That's basically how chrome plugins work in the browser where you can modify the html page and add widgets to someone else's site, on your client side. If you wanted to add notes to html help you could use the DOM to do it and store those extra notes in a database, or something. I'd be interested in how many people do this: add notes to their help, inline. We know that people add notes at the end of the documentation, like the php manual where people add comments to the bottom of the page. I didn't realize there were help systems were you could inline some notes?

Which is an interesting question: why hasn't firefox allowed IPC from external apps. Could be a security vulnerability. Maybe just one of those interesting features that could be, should be, would be, but no one has thought of implementing. If firefox had IPC you could navigate to an anchor from an external exe.

Also an interesting question is why hasn't adobe got something like this so that adobe files could be used as help files: scroll to a certain part of the pdf file programmatically using IPC, or maybe using an adobe embedded object. I find pdf files just a little too slow, though, and not as responsive, due to them being like a resource intensive graphic. So I suppose pdf files ruin the zippy feeling of a fast help system.

Lars wrote

Would the current help systems be even capable of looking like that? Must be just a few div boxes. Really simple, interesting color shades. No fancy garbage, just simple boxes of text.

I don't know how much CSS the HTML component in LHelp supports. But if you look at the source of that website, they actually use HTML tables to do most of the layouting.

Looking at the following page...

http://delphibasics.co.uk/RTL.asp?Name=CurrencyString

Also Free Pascal's fpdoc already generates all that same information:
* summary line (name, one line description and unit name)
* declaration
* Description
* extra notes
* example code
* See also (related commands)

The fpdoc linear output writers (LaTeX, INF etc) formats the above information quite neatly. Then again, I thought we were talking about application help which could take on a whole different layout compared to technical API documentation.

As for the color they used. Yes, they are nice pastel colors, but they don't really add much value. If the headers were more prominent (larger and nicer font), then the colored boxes probably wouldn't be needed.

By using colour like that, you are also limiting your audience - eg: what about colour blind people? Just take a look at this web page and see what different color vision deficiency can do to the same image.

http://www.color-blindness.com/coblis-color-blindness-simulator/

Regards,
Graeme

wkitty42--- wrote

what's wrong with something like LHelp and using IPC to tell it where to load the next help from that the user has asked for??

I'll have to experiment with LHelp, thanks

from these cheap seats i have way over here, it seems like you are over engineering this...

Anyone who pulls in a 150MB-300MB chromium embedded plugin is likely over engineering (not to mention bloatware).

I'm critical of my own original post. Would be much better if there was a chromium lite version that you could embed which was only 2MB or 1MB.

One plan I had was to simply port an existing html documentation system that runs on a cgi program on a server, over to offline help, with minimal effort. Chromium embedded seemed the way to go because you can literally trick chromium embedded into being a cgi like device, on the client side, without any web server.

Whether LHelp can do that, is something I'd have to research.

I have some existing projects where the help system is already in place, on a server, and I don't much feel like writing two sets of help systems one that works offline and one that works online, I'd rather just have one system that works online and offline. So I figured CEF3 or CEF1 would be a way to make already existing online documentation, work offline too.

Holy batman, they are using tables? Wow.. I was sure it was a Div box based website but they are using classic tables. Interesting.

By using colour like that, you are also limiting your audience - eg: what about colour blind people?

Would be interesting if there was a firefox/chrome plugin that converted a website to be all black and white to help people, or maybe grayscale. But good point.

Lars wrote

> You can always use any other port >1024 for that. No issues with default firewalls? Last thing I want, is a customer having to futz around with router firewall, windows firewall, etc.

It was 4 years ago, but as far as I remember, we didn't have any firewall issues on Windows.

But isn't that what iota full text search is for, to preindex all the search stuff so no time is spent grepping through html files....

Yeah, but deployment is going to be a pain isn't it? I know of iota, but I don't know how it works. I would imagine it needs to run continuously in the background?

ps:
I believe the is a FTS indexer as part of FCL as well. Though I think it was written for databases, not for HTML files.

User defined notes, were not available in chm files were they? I thought chm/hlp file were just dumb, fixed help files with no bells an whistles.

Now there's an interesting question. :)

WinHelp supported both Annotations and Bookmarks, though the annotations were not inline - it simply showed a paperclip icon or something that you had to click to see the user defined notes, and was limited to one note per help topic.

Window's CHM viewer only support bookmarks (they call it Favourites). So it actually has less features than WinHelp did. :)

DocView supports inline annotations, bookmarks, full text search, advanced search terms (eg: search for this but don't include that, search by phrase, or fine something spelled similar to search term you entered). Docview also allows multiple annotations per help topic. The Bookmarks, Annotations and Advanced Search features are not part of the INF file format, docview implements those. Full Text Search comes standard with INF though - any word in the whole INF file is only stored once (all others are simply pointers to the word lookup table). This is also why INF is so compact (eg: one help file will be 3MB in INF, but that same help content will be a 12MB CHM file)

On a side note:
I use Docview's annotations support a lot! My Free Pascal RTL and FCL help is full of my own comments, code examples etc. I also use it to note down errors in the help (eg: spelling mistakes, grammar, examples) and then later when I have time, report those on Mantis as they are then easy to find again.

I didn't realize there were help systems were you could inline some notes?

Take a look here:

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

In the first screenshot, note all the green text. They are inline annotation examples. You can simply click them to edit them too.

The yellow text is the highlighted search terms it found in that page. Both colors are user configurable, and so too is the font and page background color.

In the "Search Results" list box, the numbers behind the help topics are a search rating value. The higher the value, the more precise the search result was (eg: the search term appeared more than once in that help topic).

Regards,
Graeme

Lars wrote

Would be interesting if there was a firefox/chrome plugin that converted a website to be all black and white to help people, or maybe grayscale. But good point.

Opera 12.x (and earlier) had that built in. Newer versions of Opera (based on Chrome) doesn't support that any more - and neither does Chrome or Firefox.

Regards,
Graeme

In the earlier reply I missed the most crucial part. There is /NO/ catchup. We are not developing a browser. Just something that can display the HTML subset that we generate cq support.