Propose: Improve `highlight` API

[joshgoebel]

For those finding there way here from the deprecation warning it's easy to upgrade your code:

// The old API:
highlight(language, code, ignore_illegals, continuation) {
// The new API take an options object literal:
highlight(code, { language, ignoreIllegals}) {

So to upgrade your code:

// before
html = highlight("vbscript","your code goes here", true)
// after
html = highlight("your code goes here", {language: "vbscript", ignoreIllegals: true })

IE, just switch the order of the arguments and pass language and ignoreIllegals in the options object now.

---

Advantages:

• target of the verb [highlight] is now the first argument, which makes more sense, such as format(drive), highlight(code)
• no need to remember order of the arguments
• we can still support the old API for legacy (ie, non-breaking change)
• fewer arguments are generally better (easier to understand, now at the call site you always see the names of the optional arguments, etc)

Checklist:

• new highlight API as shown above
• highlightAuto -> highlight(code)
• highlightAuto is deprecated
• highlightBlock -> highlightElement enh(parser) add highlightElement, deprecate highlightBlock #3003
• highlightBlock -> deprecated enh(parser) add highlightElement, deprecate highlightBlock #3003
• fixMarkup -> deprecated, will be removed with v11
• initHighlightingOnLoad -> highlightAll()
• initHighlighting -> highlightAll()

[egor-rogov]

Yes, the suggested API looks better to my taste. But I can't see enough value in it to justify API breaking change.
Making it non-breaking - well, why not.

[joshgoebel]

Any objection to:

• highlightBlock -> highlightElement
• initHighlighting -> start() or highlightAll()
• initHighlightingOnLoad -> startOnLoad()

Both for clarity and simplicity.

[egor-rogov]

start doesn't looks clear to me, highlightAll is better to my taste.