ExtendScript: Doc misleading for importing parameters

For an illustration of the consequences of missing precise documentation see Importing fm-doc fails miserably

In the Function Summary of the FrameMaker Scripting Guide there is misleading information concerning the properties for the Import function.

FS_AlertUserAboutFailure: Alert user if an unexpected condition, such as an unrecognised file type, occurs. Set to either True or False.

Missing: Open dialogue Unknown File Type in case of importing text (FS_ImportAsType set to FV_TYPE_TEXT).

FS_ForceImportAsText: Import the file as a Text Only document, even if it is a MIF file or a filterable file. Set to either True or False.

Missing: If this setting is missing when importing text (FS_ImportAsType set to FV_TYPE_TEXT) does not interpret UTF8 files correctly. They are treated as ASCII files.

Reporting bad filename

The import functions requires a parameter named filename, which should be a full path. If this is wrong - file can not be found - FA_errno is set to -43 (FE_BadParameter). This does not indicate, which parameter of the function call is wrong.

The error code should be analogous to FE_BadSaveFileName (-50). The requirement for aadditional analysis of FS_OpenStatus flags is quite clumsy. Only with these one gets a useful information, such as FV_BadFileName (67).

File name

It must be stated in which format a file name (full path) is expected by a function! File System Access in the JavaScript Tools Guide states: File and Folder objects can be used anywhere that a path name is required, such as in properties and arguments for files and folders.

ExtendScript Tools and Features in the same document states: $.fileName (string) The file name of the current script. Read only.

Problem

Using $.fileName to get the name of the current script gives an URI notation: /e/_DDDprojects/Test_ImportDoc1.jsx

In descriptions of functions there is no notion in which format the parameter filename is expected. For example for the function Import the documentation (FM Scripting Guide) states:

filename (string) The full path of the file to import.

Using the output of $.fileName as input to this function yields error -43 (FE_BadParameter).

The file name/path must be given in platform specific notation: E:/_DDDprojects/Test_ImportDoc1.js

► Unsufficient documentaion - especially that related to scripting - leads to a waste of time for the development of scripts. In many cases it is necessary to resort to the FDK documentation - but even there are holes in the information.