Doubly check the manual flag

[TimWolla]

Currently the manual is only checked before attaching the event
listener, making it hard to reliably set the flag without jumping
through hoops and special cases if Prism is bundled together with
other scripts into a single script file.
Change to check the flag once before attaching the event listener
and once again before actually highlighting to support setting it
after the Prism initialization has run.

see discussion starting at:
#1087 (comment)

---

Quoting from the discussion in the issue:

We can; we would break BC for people using the old document.removeEventListener('DOMContentLoaded', Prism.highlightAll) method of removing auto-highlighting, as now the callback we're attaching won't be just Prism.highlightAll.

and

Fine by me; if we do that, we should document that somewhere though. Is the CHANGELOG enough or should we include a "how to disable auto-highlighting" somewhere?

Should I make some other adjustments anywhere? /cc @mAAdhaTTah

[TimWolla]

Misunderstood the requirement to not touch anything outside of components/ and did not run gulp. Now fixed and force pushed.

[TimWolla]

This pull request is the only PR that is not labeled at all, so it looks like it might have slipped through the cracks. Can you take a look, please?

[RunDevelopment]

Sorry for the delay @TimWolla!

All in all, I'm ok with this aside from a few minor things (see comments).

Regarding the documentation:
I think we definetly need the doc (#1402) and should put this on your front page in the basic usage section (preferably above the CDN section).
Two or three sentences with one or two code example should be enough to sell the idea. The doc should mention Prism.manual and data-manual.

/cc @mAAdhaTTah

[TimWolla]

I've made the requested adjustments to the code.

[TimWolla]

I think we definetly need the doc and should put this on your front page in the basic usage section (preferably above the CDN section).

This can simply go into index.html? I notice that it already says:

f you want to prevent any elements from being automatically highlighted, you can use the attribute data-manual on the <script> element you used for prism and use the API. Example:

So only Prism.manual would need to be added, no?

[RunDevelopment]

This can simply go into index.html?

Yes.

I didn't notice it already mentioned data-manual. What an attentive reader I am...
In that case, just Prism.manual and how data-manual affects Prism.manual is enough.

[TimWolla]

In that case, just Prism.manual and how data-manual affects Prism.manual is enough.

Okay, I've added the docs as well. Let me know if there's something else I forgot!

[RunDevelopment]

I would still like to have @mAAdhaTTah approve this.

[mAAdhaTTah]

Just need to resolve the conflicts.

[TimWolla]

Just need to resolve the conflicts.

@mAAdhaTTah I've rebased my branch onto PrismJS:master and resolved the conflicts.

[RunDevelopment]

Thank you for contributing @TimWolla!

[piotr-cz]

After this change it's not possible to minify script using uglify-js and "use strict" declaration:

  13971 |
  13972 |       if (!_.manual) {
> 13973 |               function highlightAutomaticallyCallback() {
        |       ^ In strict mode code, functions can only be declared at top level or immediately within another function.
  13974 |                       if (!_.manual) {
  13975 |                               _.highlightAll();
  13976 |                       }

Functions shouldn't be declared inside the if code block.