Use the .ewriter file extension for books distributed on their own

You need to use the .ewriter extension for eWriter files that are going to be distributed on their own. It is registered with the Windows Store, and when a Windows 10 user who does not have the viewer opens an .ewriter file they will be prompted to install the viewer from the Windows store. Users on older versions of Windows can download the Win32 installer from our eWriter page, which will also register the .ewriter extension.

Use your own file extension for eWriter used for software documentation

When you are using eWriter for software documentation you want to install the Win32 version of eViewer together with your software and make your calls to it directly. You also don't want to conflict with any other version of the viewer that your user may have installed, so in this case you don't want to use the .ewriter extension. Instead, see one of your own.

See URL-style command syntax for full details on this.

Making calls to eWriter help files from your applications to display topics is very simple. On Windows, you basically just need to call the viewer app with a shellExecute() or equivalent function in your programming language, along with the name of the topic file to be viewed and an optional anchor to scroll to.

File extensions of your topic files

The HTML topic files inside eWriter Help can have either the .htm or .html extension, based on your settings for the topic file extension in your project in Configuration > Publishing Options > WebHelp > HTML Export Options. However, only these two extensions are permitted. If you set a different extension in your project (for example .php or .asp), the standard .htm extension will be used.

You need to use the correct extension in your context help calls, otherwise the topics will not be found.

Context calls syntax

The syntax for context calls to eWriter Help has been changed with the introduction of the new MacOS eViewer and the updated Windows eViewer. If you have used eWriter for application help in the past the calls with the old syntax in your existing projects will still work. However, we strongly recommend switching to the new integrated URL-style syntax from now on.

Please refer to the eWriter for Software Help chapter for full details and instructions.

Basic New Syntax:

"<viewer app>" "ewriter://<ewriter file>?loadpage=<page in the help>"

Note that when you are using integrated EXE eWriter Help files, the viewer app is the help file itself, so it calls itself when using the new syntax.

Basic Old Syntax (not supported for MacOS):

"<viewer app>" "<page in the help>"

URL examples eViewer app:
"<path>eViewer.exe" "ewriter://<path>my_help.ewriter?loadpage=index.html"
"<path>eViewer.exe" "ewriter://<path>my_help.ewriter?loadpage=index.html?introduction.htm#anchor2"
"<path>eViewer.exe" "ewriter://<path>my_help.ewriter?loadpage=introduction.html?anchor=anchor2 (Premium Pack)"

URL examples Windows EXE eWriter file:
"<path>MyHelp.exe" "ewriter://<path>MyHelp.exe?loadpage=index.html"
"<path>MyHelp.exe" "ewriter://<path>MyHelp.exe?loadpage=index.html?introduction.htm#anchor2"
"<path>MyHelp.exe" "ewriter://<path>MyHelp.exe?loadpage=introduction.html?anchor=anchor2" (Premium Pack)

URL parameters and JavaScript

If your HTML pages include scripts that can evaluate URL parameters (supported in some Premium Pack skins, for example) you can also include parameters to be parsed by your script, like this:

"<path>eViewer.exe" "ewriter://<path>my_help.ewriter?loadpage=index.html?mysetting=xyz&setting2=12"

The HTML location object is fully supported for interpreting URLs you pass to your pages like this. This means you can extract the query portion of the script with document.location.search, the hash portion (anchor) with document.location.hash and so on.

If you have multiple eWriter help files installed on your user's computer you may sometimes want to link between them. This will normally only apply when you are using eWriter for software documentation.

There are several methods you can use for linking between eWriter files. You must always use the File Link option for this, not the Internet Link!

Linking between eWriter files when the file association is known

You can use a simple method if you are sure that the .ewriter extension has been associated with the eViewer application, or if you are using your own extension that you have registered as part of your installation on the user's computer. Then you just need to reference the eWriter file and the topic parameters.

This also works when you have changed the file extension and eViewer name:

Note that this also works if you are using eWriter for software documentation and you have changed both the file extension and the name of your copy of the eViewer application. You just need to link to another eWriter file that has the same extension as the eWriter file containing the link.

Using an Internet link instead of a File link (required for MacOS)

You can also use an Internet link to link between eWriter Help files, but then you have to use the new syntax with the ewriter:// prefix. This is also required if you are using eWriter Help on MacOS.

ewriter://NewProject.ewriter?loadpage=index.html?topic_name.html

Linking between files when you are using the integrated viewer in EXE eWriter books

When you create combined book and viewer files with the EXE extension you always just enter the EXE file as the file to link to and the topic to open as the parameters.

You can still create the original EXE eWriter files with an integrated viewer if you wish, although we strongly recommend using the separate viewer. You just need to change the output file extension to .exe in the Publish screen before publishing. Help+Manual identifies this automatically and then creates an EXE eWriter Help file with an integrated viewer.

Not supported on MacOS

Note that EXE eWriter Help is a Windows format and cannot be used on MacOS. On Macs, you must use the eViewer app and .ewriter data files.

Context calls syntax

The calling syntax is the same as with the external viewer, except you call the EXE eWriter Help file instead of the viewer, followed by the parameters. You can use both the old and the new syntax for this.

Old syntax:

<path>my_ebook.exe "index.html?introduction.htm"
<path>my_ebook.exe "index.html?this_page.htm#anchor"
<path>my_ebook.exe "index.html?anotherpage.htm"

New syntax:

If you use the new syntax, you must also include the name of the EXE eWriter Help file after the ewriter:// protocol prefix, so that the file is calling itself:

<path>my_ebook.exe "ewriter://my_ebook.exe?loadpage=index.html?introduction.htm"
<path>my_ebook.exe "ewriter://my_ebook.exe?loadpage=index.html?this_page.htm#anchor"
<path>my_ebook.exe "ewriter://my_ebook.exe?loadpage=index.html?anotherpage.htm"

Always include the page parameters in quotes, even if there are no spaces. Otherwise you will get Windows errors caused by some of the characters that need to be used.

If you're used to producing CHM files and WebHelp you don't even think about opening executable EXE program files from your documentation. But with eWriter Help, you can! This is possible both from normal links in topics and from TOC entries.

RESTRICTION: Not supported in the Windows Store version of the viewer!

Windows Store apps are not permitted to invoke executable files from within the program. Because of this, the functions described below are not available in the Windows Store version of the viewer app. However, you can use them if you are installing the standard Windows eViewer app together with your software. See EWriter for Software Help for details.

Current directory status when linking to executable files

When executing external files, the eWriter viewer explicitly sets the current directory to prevent possible failure of file links using a relative path.

File links to executables in topics

Just create a normal file link to the EXE file and add exec: directly before the file name, like this:

exec:notepad.exe
exec:../demo_program/widget_maker.exe

Links to executables in the TOC

You can also create links to executable files in the TOC of an eWriter Help file. Create a new topic entry and choose the TOC Link option, and then Link to Web Address. Then enter the target in the Web Address: field, using same exec:filename.exe format as above. Here too, you can include a relative path if necessary.

exec:notepad.exe
exec:../demo_program/widget_maker.exe