Delphi Cross-Platform Application Help Files

{*******************************************************}
{                                                       }
{     Ziphelp Delphi Implementation for VCL and FMX     }
{              Released September 2023                  }
{                                                       }
{         Copyright(c) 2023 EC Software GmbH            }
{       https://www.helpandmanual.com/ziphelp/          }
{                                                       }
{*******************************************************}


---------------------------
** Files in this package **
---------------------------

ReadMe.txt 					Readme file
License.txt 					GNU General Public License (GPL)
Ziphelp-documentation.pdf 			PDF documentation
\Demo\FMX\*.* 					Firemonkey demo application
\Demo\VCL\*.* 					VCL demo application
\Demo\Help\ZiphelpDemo.Zhelp.zip 		Compressed Ziphelp demo help, used by the demo application
\Demo\Help\ZiphelpDemo-unzipped\*.*		Uncompressed Ziphelp demo help, used by the demo application
\Component\Ziphelp.pas 				Cross-platform Delphi implementation of the TZiphelp component.


------------------------
**   About Ziphelp    **
------------------------

When starting with cross-platform software development, the bullet point "Online help" may not be on the very top of the to-do list. After all, it's a mobile app, isn't it? Don't bother, we developers might think.

However, the more complex a software application becomes, the more urgently it needs some form of software documentation, a user guide. With so many platforms under one belt, creating online help has not become simpler.

On Windows, the Microsoft "HTML Help" (.chm) format is or was the defacto standard for application help. Unfortunately, Microsoft has been neglecting the CHM format since about 2011 and the status quo is not going to brighten up. On MacOS, the situation is not much better. There is "Apple Help", a proprietary HTML-based format. It has received its last revision in 2013 and most MacOS developers simply don't bother with Apple Help Books.

For those reasons, many cross-platform developers and Windows developers alike have long switched to a simple HTML-based software documentation. However, many of those simple HTML docs do not support context-sensitive help. Which is a pity, because most cross-platform development tools (Microsoft Visual Studio, Embarcadero Delphi, to name just two) do support tried-and-tested tools to implement context-sensitive help for an application user interface. Either on form level, in some case even for certain controls or control groups. The properties TControl.HelpContext and TControl.HelpKeyword are your friends. What's missing is a (common) cross-platform help format.


Requirements for a cross-platform help format:

1.An open standards-compliant help format, not proprietary. This is, of course, HTML.

2.The very same documentation should be used for all platforms, for desktop, mobile and on the web.

3.HTML creation must not rely on a particular tool. However, a common cross-platform help API is needed, which must integrate into existing HTML-based help systems without modifying them.

4.The API must implement the calling syntax, as different HTML-based help system might require a special syntax with certain parameters to function properly.

5.The cross-platform help API must support context sensitivity, in order to supply contextual help for apps.

6.The API should further support error-tolerant context-sensitive help, accomplished by associative keywords (a-keywords).

7.The API must work locally as well as online, because documentation is deployed either locally in combination with the app, or online, or both, or with a mix of both.


A perfect candidate for these requests is the classic sitemap XML protocol. It already covers points 1 to 4. For the requirements 5 to 7, it needs to be extended. Fortunately, the sitemap protocol permits custom extensions. Ziphelp is this sitemap extension that covers all requirements from 1 to 7.