Some questions to the experts

[K.Daube]

I have observed some things the reason for which I do not understand:

1. What is the purpose of function Main () ?
   • Is it just a wrapper around the initial stuff ?
   • I assume that global definitions must still precede this.
2. Adobe's examples (e.g. SnpCreateDialog) use the form
   • SnpCreateDialog.prototype.run = function() { ...}
   • rather than simply function SnpCreateDialog () { ...}
   • What is the rationale behind this?
3. I have also found a that certain Unicode characters are not allowed in comments of an UTF-8 coded script. In my lengthy script (now > 1000 lines) I needed a regex in the editor to find the culprit: [^\p{L}\p{N}\p{P}\s\$\<\>=+\^]

// goRtfDoc.Close ... // must be postponed to keep the ¶-IDs intact

       This creates the error

Error Message      : Character conversion error
Script, Line#   : H:\Adobe\framemaker.12en\AdobeFrameMaker12\6,  0

     Replacing the symbol ¶ by the word paragraph fixed the error.

    =>  Is there a list of 'unallowed' characters or vice versa a list of allowed characters (also for string constants?).

[Russ Ward · Accepted solution]

Hi Klaus,

I am far from an expert, but I can answer some questions, I think.

I'm not sure that a main() function has any particular importance within JavaScript, which parses and runs largely in a procedural fashion. It is important for self-contained executable programs (EXEs), because when you run a program, the OS or runtime environment needs to know where to start. For example, an executable Java archive must have a main() function, as this is the standard for the JRE to know what function/method to run first when the program is launched. If you see it in JavaScript, it might just be there as a matter of general convention from programmers who like general conventions. -DISCLAIMER- I don't know for sure that is true.

I think global variables can appear anywhere outside of functions within JavaScript, although I think it is certainly best to declare them before any functions that will use them.

The prototype business is a technique for adding a method to the underlying object type, such that all objects of that type can invoke it afterwards. In your example, it's my guess that if you do this...

var kdaubesDialog = new SnpCreateDialog();

Then you could do this with your object:

kdaubesDialog.run();

For more information, see JavaScript Prototypes.

As far as the unicode problem, I think there may be some bugs in the ES implementation. I also ran into this problem where some character (or maybe character sequence) caused the whole thing just to freeze up. I forget which character it was, but once I got rid of it, things worked fine. Maybe there is a JavaScript standard for this, but I'm not aware of it.

Hope this helps.

Russ

[frameexpert]

I usually use a main function as the entry point for my script. The name "main" is arbitrary as far as JavaScript/ExtendScript go, but I use it to signify the starting point for my scripts.

#target framemaker

main ();

function main () {

    var doc = app.ActiveDoc;
    if (doc.ObjectValid () === 0) {
        alert ("There is no active document.");
    }
    else if (doc.Name === "") {
        alert ("Please save the document and run the script again.");
    }
    else {
        processDoc (doc);
    }
}

[K.Daube]

Thank You both, Ric and Russ,

These are things wich is not found in the 'ordinary' documentation about Escript, hence I appreciate Your comments very much.

My large script starts after the global definitions with just just two calls:

/* FM-biblio.jsx
   Desctiption of the whole thing
*/
#target framemaker
// --- global definitions
var lvlTrace      = 0;                            // level of function nesting
var gaFndCitations= [];                           // array of found citation texts (excluding brackets)
var gCollectPath  = "";                           // same as current book/file path
var gaFmtCitsRaw  = [];                           // left column in processed RTF
// ...
ReportInfo ();

DefineMenus();

And then follow all the functions (now 40). Only the naming of the data types is not yet consistent with 'good practice' - but I'm also working on that.

[frameexpert]

JavaScript has become a hugely popular language because of its use in web browsers. As a result, there are a lot of books about JavaScript. Two that I specifically recommend are "JavaScript: The Good Parts" by Crockford and "JavaScript Patterns" by Stefanov (both published by O'Reilly). I like these because they discuss the language someone independently from its use in the browser. Also, there is an excellent course on Udemy called "JavaScript: The Weird Parts" which gives an in-depth look at the language. Udemy has sales all of the time; I think I paid $19 for the course and it has been an eye-opener for me.

Like most things we learn in life, our understanding does not increase in a linear fashion. We plod along slowly, hit walls and get stuck, but suddenly something "clicks" and things suddenly get clear. And this process will repeat as we continue to learn. As we say in the US, I know enough about JavaScript to be dangerous, but I am striving to really understand it and master it. In spite of your limited experience, you are doing really well. Keep going and don't quit!

[Russ Ward]

Hey Klaus, I was able to dig up the character problem I had. It doesn't involve multibyte characters, but it does speak to the possibility of parsing bugs in ES:

Script will not run with ]]&gt; in it

Russ

[frameexpert]

One possibility occurs to me: JavaScript was written to work with UTF-16 encoding. And, supposedly, the ExtendScript Toolkit is written in ExtendScript, so perhaps some valid UTF-8 characters don't work well in JavaScript. Only a guess.... -Rick

[K.Daube]

Thanks Rick for the recommended books.

I have already looked into The Good Parts" by Crockford and decided to first check for the pitfalls (chapter "Bad parts") before I continue with my project.

There are real surpirses, for example the === and !==  (I have used == and !== for equal/not-equal assuming the NOT is a 'prefix').

Well, concerning the Awful parts I can not follow all the recommendations there: e.g. I need global varaibles and ararays. On the other hand, automatic semicolon insertion must really be avoided.

I will check whether my Unicode problem is the result of the 'design for 16 bit' (in which range my character was).

BTW I have not found any reference in the Scripting Guide which coding is allowed for Escripts. A test reveals that ESTK produces UTF-8 files. In the FDK documents there is also no mention of the coding of the source. So it is unclear whether an Escript may be written in a Windows code page (1250, 1251, 1252).

Using JSLint (http://www.jslint.com/) is not that encouraging:

All Escript examples I have (including Yours and Yours and Adobe's) do not observe a main requirement: declare a function before it is used. And unfortunately this requirement can not be switched off, so other errors are only found at the start of a not so buggy script. The ESTK is not a help in finding bad practice constructs - what else is available besided the experise of seasoned scripters like You?

For example, I'm not a fan of writing function ExpandInBook(book) { ... } rather than function ExpandInBook (book) {...}

For clarity / ability to comment I write

function DefineMenus () {
  giLvlTrace += 1; ZTrace ("DefineMenus");
  var sMenuMain   = gasIniTexts[0];
  var sMenuDocu   = gasIniTexts[1];
  var sMenuColl   = gasIniTexts[2];

rather than

function DefineMenus () {
  giLvlTrace += 1;
  ZTrace ("DefineMenus");
  var sMenuMain   = gasIniTexts[0], sMenuDocu   = gasIniTexts[1], sMenuColl   = gasIniTexts[2];

Of course style is often a matter of taste - but I try to keep up with proven practice.