How context help calls work on Windows

On Windows, you can call an executable with command line parameters. Multiple calls to the same executable will normally start multiple instances of the program. However, this is prevented by the eViewer application. It always displays just one instance of the viewer for the same help file, even when you make multiple calls to it.

How context help calls work on MacOS

On MacOS, when an application is opened by another program, it is possible to specify command line parameters as well. But only once. Because of the general single-instance policy on MacOS, a subsequent call to the same executable does not create a new instance. Instead, it brings the running instance into foreground. At this point, the already running application does not receive the (different) command line parameters after the --args command line switch.

All is not lost, however, because MacOS also makes it pretty simple to register a custom URL scheme for an app, which can be used both to open your app and pass commands to a running instance.

The references for topic files in your call URLs are slightly different for standard Help+Manual skins and frameless Premium Pack skins. With the standard skins you need to call both the layout page (index.html) and the topic page (topic.htm or topic_id.html, depending on what you set as your topic extension in your project).

Standard skins:

ewriter://<path>my_doc.ewriter?loadpage=index.html?topic.htm#anchor_id

Premium Pack V3, V4 and V5 skins

ewriter://<path>my_doc.ewriter?loadpage=topic_id.html?anchor=anchor_id

The URL command combines 3 parts: a) the protocol, b) the domain which is our ewriter file and c) the optional command parameters as the URL query part.

The URL is preceded by the viewer reference

All examples are the argument. They must always be preceded by a reference eViewer app or the eWriter EXE file name if you are using that format on Windows. When using standalone Windows EXE files the file is both the viewer and the target and calls itself.

You can use two ? separators in the same URL

Note that you use the ? character after the index.html reference as the first separator, even though it also comes after the eWriter Help file name. This is because the URL is actually two combined URLs that are split internally by the viewer.

Calls on Windows with eViewer.exe and data help files

The calling convention on Windows is:

Open:           eViewer.exe "urlstring"

Note:
The protocol for the Windows version is always ewriter://, even if the app has been renamed. This is possible because the protocol cannot create conflicts on Windows.

Examples:

eViewer.exe "ewriter://c:\users\username\documents\my_ebook.ewriter?loadpage=index.html?topic.htm&defpos=50,50"

Myviewer.exe "ewriter://c:\users\username\documents\my_ebook.ewriter?loadpage=topic.html&defpos=50,50"

Escaping (percent encoding) URLs:

The URL can be escaped (percent encoded) on Windows. When served in quotes as a command line string, the URL is technically a simple string and eViewer.exe will take it at face value, even if it is not escaped. Escaped URLs will be unescaped internally.  See How to escape a URL below.

Calls on Windows with integrated EXE help files

On Windows you can also create eWriter Help files as a standalone EXE with an integrated viewer. The calling syntax for these files is exactly the same, with the difference that the file calls itself. This is because the file is both the viewer and the help file. So it looks like this:

<path>\widgets_intro.exe "ewriter://<path>\widgets_intro.exe?loadpage=index.html?topic.htm&defpos=50,50"

<path>\advanced_version.exe "ewriter://<path>\advanced_version.exe?loadpage=topic.html&defpos=50,50"

MacOS

The calling convention on MacOS is two-fold. You can use the command line (but only once) and you can also optionally open the custom URL directly:

Open:   eViewer.app --args "urlstring"
Open:   "urlstring"

Note:
You must use the same protocol on MacOS that you modified in the installer's Info.plist. See Installation & Configuration.

If the protocol doesn't work immediately after modification, start the app with a double click. This should be sufficient to register the custom URL scheme on the Mac.

Examples:

(a) Command line arguments
eViewer.app --args "ewriter:///Users/username/documents/my_ebook.ewriter?loadpage=index.html?topic.htm&defpos=50,50"
Myviewer.app --args "myprotocol:///Users/username/documents/my_ebook.ewriter?loadpage=topic.html&defpos=50,50"

(b) Custom URL scheme
"ewriter:///Users/username/documents/my_ebook.ewriter?loadpage=index.html?topic.htm&defpos=50,50"
"myprotocol:///Users/username/documents/my_ebook.ewriter?loadpage=topic.html&defpos=50,50"

The URL must be escaped with percent encoding on MacOS. It will work unescaped when served in quotes as a command line string, but the direct call to a custom URL scheme requires a properly escaped URL.

A URL is a single string without spaces. It is made up of a protocol, a domain and trailing query strings. No spaces are allowed in the domain or the query strings. The domain and query strings are separated by a question mark (?). Multiple query strings are separated by an ampersand (&). For detailed information, see the W3C website  HTML URL Encoding Reference.

To serve the URL string correctly, we must at least escape all spaces in the entire URL and the question marks within parameters:

Raw:
"ewriter://c:\users\user name\my documents\my ebook.ewriter?loadpage=index.html?topic.html&defpos=50,50"

Escaped:
"ewriter://c:\users\user%20name\my%20documents\my%20ebook.ewriter?loadpage=index.html%3Ftopic.html&defpos=50,50"