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.

[joshgoebel]

@allejo Any thoughts on these API naming changes? I think this was a topic before we added you to the team.

[allejo]

I agree with Egor where "start" isn't clear. I'd lean more towards:

• highlightDOMElement or highlightDOMNode (I don't immediately think a DOM element if it's just highlightElement)
• highlightAll
• highlightAllOnLoad

[joshgoebel]

After more though I don't like this highlightAllOnLoad vs highlightAll nonsense and forcing users to think about WHEN. I think instead:

highlightAll() - just works, no matter when it's called (hooks onload, or if already loaded simply highlights)

A single API.

[joshgoebel]

I think I'm going to leave highlightAuto for now since change that gets into issues with callback names and other things...

[precondition]

I appreciate the quick rundown on how to upgrade the code.