Cross-platform Application Help for FMX and VCL

[Alexander Halser 20]

We have just released an open-source Delphi implementation for a HTML-based cross-platform application help system.

 

Information page:

Ziphelp - an open cross-platform help format

 

Direct download link:

https://www.helpandmanual.com/download/delphi-ziphelp-demo-source.zip

 

 

About Ziphelp

On the surface, Ziphelp is basically HTML in a compressed zip archive, hence the name. Pack any folder with HTML files into a zip archive and you are good to go.

 

But Ziphelp is more than that, it is a protocol based on the standard sitemap protocol, designed to give a help viewer (here: the Delphi implementation) extended information about the content of the help system. That is help context numbers, help keywords, associative keywords, page titles. This information is missing in a standard sitemap.xml. Ziphelp extends the sitemap protocol and enables direct communication of an app with the help system.

 

The Ziphelp protocol is not just for zip archives. It works inside an archive, with uncompressed folders or with HTML content loaded directly from a website. A Delphi desktop app may be deployed with local application help, uncompressed, zipped or embedded. A mobile or web application might not ship with local HTML content, but refer to an online version instead. The mechanism is the same in both cases and the TZiphelp component implements this for Delphi.

 

Demo Application

A demo app for VCL and FMX (Win/MacOS) is included. The demo builds on standard Delphi components (TWebBrowser) to display the help system.

 

 

 

[Alexander Halser 20]

The project now has been moved to Sourceforge:

 

Delphi Cross-Platform Application Help download | SourceForge.net

[Rollo62 502]

Thanks, this is a very good idea.

From the explanations, I would think it is not derived from the MS-CHM Format or any others, but written from scratch.

Or is this based on any existing, well-known XML format ?

 

Maybe you took the best parts from CHM and baked them into a more modern cake ?

This would be a tough task anyhow.

Edited September 20, 2023 by Rollo62

[Alexander Halser 20]

Quote

I would think it is not derived from the MS-CHM Format

No, it is not derived from CHM. Because CHM is basically Windows only and not cross-platform.

Quote

Or is this based on any existing, well-known XML format ?

Yes. plain HTML5 and based on the regular "sitemap" XML schema.

 

When you create CHM files for a Windows application, you typically use an authoring tool for this and don't craft the HTML in Notepad. Those authoring tools which create CHM files usually create plain HTML5 as well. The example help you see in the demo project was created with Help+Manual, it's plain vanilla HTML5 and Javascript.

 

But not just Help+Manual produces this output, Madcap Flare does, Adobe Robohelp does, you name it. And most authoring tools offer some kind of syntax to use the plain HTML5 output for context-sensitive help. Unfortunately, everyone has their own syntax, there is no established standard. And because of a missing standard, there are no viewer applications, as long as everyone does their own thing.

 

Ziphelp is an attempt and a ready-to-use solution for this dilemma. It is as open as possible, because it is based on the standard sitemap protocol. This is the same sitemap.xml that you use on your website to help Google index it. Ziphelp is basically a legal extension of this protocol. Open for everyone to produce content that includes a Ziphelp sitemap and open for everyone to create an HTML viewer that can read it.

 

To give it a head start, we have created a freely distributable HTML viewer that reads the Ziphelp protocol (https://www.helpandmanual.com/ewriter/). Some people prefer this solution because it's less work for them.

 

But for Delphi developers, I think that a native cross-platform implementation is more appealing. Here, everything is under your control and your application can interactively question the help system if it actually "supports help context number 45327" or if that number is outdated in the UI of your app (and you should clean it up, but at least you don't let your end users run into an 404 error). This interactivity is missing even with CHM files.

 

So, here you go. A free Delphi implementation that supports HTML5 in a zip archive, uncompressed HTML or web-based content. It all works with the same protocol and the same mechanism, on all platforms. You can create this HTML5 help system with our tool Help+Manual, of course. But you don't have to. If you prefer a different authoring tool, go for it.

 

[Anders Melander 1639]

1 hour ago, Alexander Halser said:

Because CHM is basically Windows only and not cross-platform.

It's just a file format. There's nothing it that limits it to Windows.

https://en.wikipedia.org/wiki/Microsoft_Compiled_HTML_Help#Use_in_non-Windows_applications

[Rollo62 502]

You separated the ZipHelp file management from the view, that is very good.
While in the demo, the view part is done by TWebBrowser.

I have not checked the code too deeply, but what stops you from using this same demo and concept on iOS or Android too ?

Maybe permissions, maybe different TWebBrowser operation ?

Edited September 21, 2023 by Rollo62

[Alexander Halser 20]

Quote

what stops you from using this same demo and concept on iOS or Android

A personal preference, no technical obstacle. 

 

A mobile app I want to be lean and small. So, I'd put the help system on the app's website and let it refer to the online version, displaying the help in the regular system browser. The demo has an option that illustrates this (though the demo uses its internal TWebBrowser to display the result). In other words: I would not use the zip functionality for a mobile app and rather remove the reference to system.zip in ziphelp.pas for those platforms with a compiler switch (plus the single line that uses it). The rationale behind this consideration is that a mobile app goes to one of the stores and automated updates are very likely, minimizing the risk of a version mismatch between app and help. Furthermore I expect a mobile device to be online anyway. Both points may not apply to a desktop app. But it's really a personal preference.

[Anders Melander 1639]

3 hours ago, Alexander Halser said:

The rationale behind this consideration is that a mobile app goes to one of the stores and automated updates are very likely, minimizing the risk of a version mismatch between app and help. Furthermore I expect a mobile device to be online anyway. Both points may not apply to a desktop app. But it's really a personal preference.

It makes perfect sense to me.

[Fr0sT.Brutal 897]

On 9/21/2023 at 11:38 AM, Alexander Halser said:

Furthermore I expect a mobile device to be online anyway

One flies on a plane and tries to solve some issue with your app. Oops, here comes the failure

[timfrost 73]

Sounds good, but raises some questions:

Is this an alternative to ewriter files or an eventual replacement?   Can you summarise the advantages/disadvantages of one over the other?  How much change is needed in Delphi VCL applications, or in my help build procedures, to switch to using Ziphelp?  And does a download of Ziphelp attract the usual Windows 'block' on zip files?

Edited October 4, 2023 by timfrost

[Alexander Halser 20]

Quote

Is this an alternative to ewriter files

eWriter is an always compressed single-file format, created by our tool Help+Manual. It has a couple of advantages over simple zipped HTML, but is a proprietary format.

 

Ziphelp, on the other hand, is an open protocol. Maybe zipped, maybe not, you choose. You can create it with standard tools and view it with Delphi's on-board components. That's the entire point of this endeavour: a format/protocol for application help, that is open on both ends (creator and viewer) without dependency on any particular tool.

 

Quote

How much change is needed in Delphi VCL applications

Between 3 and 20 lines of code. Check out the VCL example in the download file. It implements all help methods including F1 help with standard TControl.HelpContext and TControl.HelpKeyword properties, plus a validity check [of context numbers] and iteration of parent controls. If you want to skip the latter, you are basically down to 3-5 lines of code.

 

Quote

And does a download of Ziphelp attract the usual Windows 'block' on zip files?

Does not apply. If you want to zip-pack your HTML content, you most probably distribute it with your app. If you choose the online version, then there's no zip.