[main] typeset: add promise-based API

[pkra]

Resolves #297

[dpvc]

Do we need to be worried about the fact that output.errors an include warnings (like missing characters)? There is a configuration option for turning this off, so it may not be necessary to worry about that here.

[pkra]

I would have said no since undefinedCharError is false by default (and if you switch it on, you likely want to reject the promise).

However, I have noticed that switching it to true has no effect for the promise-based API, e.g.,

var mjAPI = require("./lib/main.js");
mjAPI.config({undefinedCharError: true});

mjAPI.typeset({
    math: "呵呵",
    format: "TeX",
    htmlNode: true,
    html: true,
    svg: true,
    equationNumbers: "AMS"
}, function (data) {
    console.log(data.errors); // has errors
});


mjAPI.typeset({math:'呵呵 ', html:true})
    .then((output, input) => console.log(output))
    .catch(errors => console.log("Errors:",errors)); //does not have errors

I don't understand what's going on here. (Hard errors work fine by the way, e.g., in the test file.)

[dpvc]

The problem turns out to be that the CHTML undefined character signals are not being trapped — only the SVG ones. So your first typeset() call shows them because it has svg: true, but the second doesn't, because it is only for html.

You can fix this by adding

      MathJax.Hub.Register.MessageHook("CommonHTML Jax - unknown char",function (message) {
        AddError("CHTML - Unknown character: U+"+message[1].toString(16).toUpperCase()+
                    " in "+(message[2].fonts||["unknown"]).join(","),!undefinedChar);
      });

just after the corresponding SVG version at around line 198.

[dpvc]

I would have said no since undefinedCharError is false by default

I thought it was true, but I see that you are right, so I agree, no need to do anything about it. But at least we did find out that the CHTML undefined character signals aren't currently being trapped. :-)

[pkra]

@dpvc PTAL

[dpvc]

I'd prefer to see the math character as a unicode reference ('\u5475) rather than rely on the proper encoding of the javascript file.

[dpvc]

Same here.

[pkra]

One might argue that this won't be a problem on engines that understand promises but I'm happy to make the change.

[pkra]

edited the above.

[dpvc]

Because you can't specify the encoding used in a javascript source file, it is bad practice to use raw unicode (I assume this is UTF-8, but there are other unicode encodings). For example, once of the editors I use will get this wrong, and were I to save it, the characters would change.

Were this to be loaded into a web page (and I know that it won't be), the javascript would be loaded (even in modern browsers, last time I checked) using the encoding of the web page itself, so if this were loaded into a non-UTF-8 page, it might not produce the correct character. This is why we use explicit \uXXXX for the localization menu, for example. It isn't about modern versus old browsers, it is about making assumptions about the encoding used.

[pkra]

Yes, agreed. I was spouting nonsense.

[dpvc]

Other than the raw unicode issue, this looks good, and is ready to merge.

[pkra]

@dpvc PTAL.