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 EWriter for Software Help for full details on this.

Making calls to eWriter help files from your applications to display topics is very simple. 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 eBooks 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 in eWriter. 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 calls, otherwise the topics will not be found.

Context calls syntax

The viewer and the book don't need to be in the same folder, of course. If they're not, just include the path to the book before its name and enclose both the path and the book name in double quotes. The syntax is simple and intuitive:

<path>eViewer.exe "<path>my_ebook.ewriter" "index.html"

<path>eViewer.exe "<path>my_ebook.ewriter" "this_page.html#anchor"

Always include the page parameters in quotes, even if they do not contain spaces, otherwise you will get Windows errors caused by some of the characters that need to be used.

Defining the size and position of the viewer with calls

You can override the position and dimensions of the viewer defined in the eWriter book with the /defpos: switch in the command line.

/defpos:x,y,width,height,stayontop

The first four parameters are decimal integers. No spaces allowed. The x and y parameters are the position on the screen. The width and height parameters are the dimensions of the viewer. The position parameters are required, the dimension parameters are optional. The last parameter is optional and changes the window style to float on top of all other windows. This can be useful on smaller screens, where there is not enough space to display an application window and a help window side by side.

Examples:

<path>eViewer.exe "<path>my_ebook.ewriter" "index.html?this_page.htm" /defpos:50,50

<path>eViewer.exe "<path>my_ebook.ewriter" "index.html?this_page.htm" /defpos:50,50,700,900
<path>eViewer.exe "<path>my_ebook.ewriter" "index.html?this_page.htm" /defpos:50,50,700,900,stayontop

The first example opens the book with its standard dimensions but positions its top left corner at x = 50 and y = 50 pixels. The second example also overrides the dimensions, setting the viewer to be 700 pixels wide and 900 pixels high (virtual pixels on hi-resolution devices).

The third example positions the viewer window on top of all other windows.

Including the password for protected eWriter books

If your book is protected with a password you can include it in the call with the /pw: switch so that the user does not need to enter it. However, be aware that doing this is not secure: Windows saves the parameters of every program execution and it is quite easy for a professional to get the password on a computer where this has been done.

<path>eViewer.exe "<path>mybook.ewriter" "index.html?this_page.html#anchor" /pw:password 

Calls to CHM help context numbers instead of topic IDs/file names

If you are using eWriter as a replacement for CHM help files for your application you may already be using CHM help context numbers for making calls to your topics. If you want to continue using them you can do this with two different syntax options. You can either just use the context number as the parameter after the help file name (without quotes) or use the same context number syntax that Help+Manual uses in WebHelp.

<path>eViewer.exe "<path>mybook.ewriter" 20600

<path>eViewer.exe "<path>mybook.ewriter" "index.html?contextid=20600"

Important: When using only the context number as the parameter you must do this without quotes.

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 "<path>mybook.ewriter" "index.html?mysetting=xyz"

<path>eViewer.exe "<path>mybook.ewriter" "index.html?topic_file.htm&setting1=abc&setting2=xyz#anchor"

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.

Linking to the eViewer application and adding the eWriter file and topic as parameters

Alternatively, you can also create a file link to the eViewer application, for example in the location where you have installed it together with your software. Then you add both the eWriter book file and the topic parameters as the execution parameters.

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. 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 eBook with an integrated viewer.

Context calls syntax

The calling syntax is the same as with the external viewer, except you call the EXE eBook instead of the viewer, followed by the parameters.

<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"

Always include the page parameters in quotes, otherwise you will get Windows errors caused by some of the characters that need to be used.

Including the password for protected eWriter books

If your book is protected with a password you can include it in the call with the /pw: switch so that the user does not need to enter it. However, be aware that doing this is not secure: Windows saves the parameters of every program execution and it is quite easy for a professional to get the password on a computer where this has been done.

<path>myebook.exe "index.html?this_page.html#anchor" /pw:password 

Calls to CHM help context numbers instead of topic IDs/file names

If you are using eWriter as a replacement for CHM help files for your application you may already be using CHM help context numbers for making calls to your topics. If you want to continue using them you can do this with two different syntax options. You can either just use the context number as the parameter after the help file name (without quotes) or use the same context number syntax that Help+Manual uses in WebHelp.

<path>my_ebook.exe 20600

<path>my_ebook.exe "index.html?contextid=20600"

Important: When using only the context number as the parameter you must do this without quotes.

URL parameters and JavaScript

If your HTML pages include scripts that can evaluate URL parameters you can also include parameters to be parsed by your script, like this:

<path>eViewer.exe <path>my_ebook.ewriter "index.html?mysetting=xyz"

<path>eViewer.exe <path>my_ebook.ewriter "index.html?topic_file.htm&setting1=abc&setting2=xyz#anchor"

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, using scripting in your skin.

In addition to opening the eWriter viewer from your program, you can also close it. To do that, you just need to issue this simple command:

<path>eViewer.exe myEbook.ewriter close

<path>my_book.exe close

As shown above, this works both for the eViewer app and for books with integrated viewers.

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 eBooks, 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 eBook. 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