182 lines
7.3 KiB
HTML
182 lines
7.3 KiB
HTML
<!DOCTYPE html>
|
||
<html lang="en">
|
||
<head>
|
||
|
||
<meta charset="utf-8" />
|
||
<link rel="icon" href="favicon.png" />
|
||
<title>FAQ ▲ Prism</title>
|
||
<link rel="stylesheet" href="style.css" />
|
||
<link rel="stylesheet" href="themes/prism.css" data-noprefix />
|
||
<style>
|
||
#toc {
|
||
display: block;
|
||
position: static;
|
||
max-width: 900px;
|
||
font-size: 100%;
|
||
opacity: 1;
|
||
}
|
||
</style>
|
||
<script src="prefixfree.min.js"></script>
|
||
|
||
<script>var _gaq = [['_setAccount', 'UA-33746269-1'], ['_trackPageview']];</script>
|
||
<script src="https://www.google-analytics.com/ga.js" async></script>
|
||
</head>
|
||
<body>
|
||
|
||
<header>
|
||
<div class="intro" data-src="templates/header-main.html" data-type="text/html"></div>
|
||
|
||
<h2>FAQ</h2>
|
||
<p>Frequently Asked Questions, with a few Questions I want people to Frequently Ask.</p>
|
||
</header>
|
||
|
||
<section>
|
||
<h1>This page doesn’t work in Opera!</h1>
|
||
|
||
<p><strong>Prism works fine in Opera.</strong> However, this page might sometimes appear to not be working in Opera, due to the theme switcher triggering an Opera bug.
|
||
This will be fixed soon.</p>
|
||
</section>
|
||
|
||
<section>
|
||
<h1>Isn’t it bad to do syntax highlighting with regular expressions?</h1>
|
||
|
||
<p>It is true that to correctly handle every possible case of syntax found in the wild, one would need to write a full-blown parser.
|
||
However, in most web applications and websites a small error margin is usually acceptable and a rare highlighting failure is not the end of the world.
|
||
A syntax highlighter based on regular expressions might only be accurate 99% of the time (the actual percentage is just a guess),
|
||
but in exchange for the small error margin, it offers some very important benefits:
|
||
|
||
<ul>
|
||
<li>Smaller filesize. Proper parsers are very big.</li>
|
||
<li>Extensibility. Authors can define new languages simply by knowing how to code regular expressions.
|
||
Writing a correct, unambiguous BNF grammar is a task at least an order of magnitude harder.</li>
|
||
<li>Graceful error recovery. Parsers fail on incorrect syntax, where regular expressions keep matching.</li>
|
||
</ul>
|
||
|
||
<p>For this reason, most syntax highlighters on the web and on desktop, are powered by regular expressions. This includes the internal syntax
|
||
highlighters used by popular native applications like Espresso and Sublime Text, at the time of writing.
|
||
Of course, not every regex-powered syntax highlighter is created equal. The number and type of failures can be vastly different, depending on
|
||
the exact algorithm used. <a href="examples.html">Prism’s known failures are documented in the Examples section</a>.</p>
|
||
</section>
|
||
|
||
<section>
|
||
<h1>Why is asynchronous highlighting disabled by default?</h1>
|
||
|
||
<p>Web Workers are good for preventing syntax highlighting of really large code blocks from blocking the main UI thread.
|
||
In most cases, you will want to highlight reasonably sized chunks of code, and this will not be needed.
|
||
Furthermore, using Web Workers is actually <strong>slower</strong> than synchronously highlighting, due to the overhead of creating and terminating
|
||
the Worker. It just appears faster in these cases because it doesn’t block the main thread.
|
||
In addition, since Web Workers operate on files instead of objects, plugins that hook on core parts of Prism (e.g. modify language definitions)
|
||
will not work unless included in the same file (using the builder in the <a href="download.html">Download</a> page will protect you from this pitfall).
|
||
Lastly, Web Workers cannot interact with the DOM and most other APIs (e.g. the console), so they are notoriously hard to debug.
|
||
</p>
|
||
</section>
|
||
|
||
<section>
|
||
<h1>Why is pre-existing HTML stripped off?</h1>
|
||
|
||
<p>Because it would complicate the code a lot, although it’s not a crucial feature for most people.
|
||
If it’s very important to you, you can use the <a href="plugins/keep-markup/">Keep Markup plugin</a>.</p>
|
||
</section>
|
||
|
||
<section>
|
||
<h1>If pre-existing HTML is stripped off, how can I highlight certain parts of the code?</h1>
|
||
|
||
<p>There is a number of ways around it. You can always break the block of code into multiple parts, and wrap the HTML around it (or just use a <code>.highlight</code> class).
|
||
You can see an example of this in action at the “<a href="index.html#basic-usage">Basic usage</a>” section of the homepage.</p>
|
||
<p>Another way around the limitation is to use the <a href="plugins/line-highlight/">Line Highlght plugin</a>, to highlight and link to specific lines and/or line ranges.
|
||
</section>
|
||
|
||
<section>
|
||
<h1>How do I know which tokens I can style for every language?</h1>
|
||
|
||
<p>Every token that is highlighted gets two classes: <code>token</code> and a class with the token type (e.g. <code>comment</code>).
|
||
You can find the different types of tokens either by looking at the keys of the object defining the language or by running this snippet in the console:
|
||
<pre><code class="language-javascript">function printTokens(o, prefix) { for (var i in o) { console.log((prefix? prefix + ' > ' : '') + i); if (o[i].inside) printTokens(o[i].inside, (prefix? prefix + ' > ' : '') + i); } };</code></pre>
|
||
<p>Then you can use the function for every language you want to examine. For example, markup:</p>
|
||
<pre><code class="language-javascript">printTokens(Prism.languages.markup);</code></pre>
|
||
<p>which outputs:</p>
|
||
<pre>comment
|
||
prolog
|
||
doctype
|
||
script
|
||
script > tag
|
||
script > tag > tag
|
||
script > tag > tag > punctuation
|
||
script > tag > tag > namespace
|
||
script > tag > attr-value
|
||
script > tag > attr-value > punctuation
|
||
script > tag > punctuation
|
||
script > tag > attr-name
|
||
script > tag > attr-name > namespace
|
||
script > rest
|
||
style
|
||
style > tag
|
||
style > tag > tag
|
||
style > tag > tag > punctuation
|
||
style > tag > tag > namespace
|
||
style > tag > attr-value
|
||
style > tag > attr-value > punctuation
|
||
style > tag > punctuation
|
||
style > tag > attr-name
|
||
style > tag > attr-name > namespace
|
||
style > rest
|
||
cdata
|
||
tag
|
||
tag > tag
|
||
tag > tag > punctuation
|
||
tag > tag > namespace
|
||
tag > attr-value
|
||
tag > attr-value > punctuation
|
||
tag > punctuation
|
||
tag > attr-name
|
||
tag > attr-name > namespace
|
||
entity</pre>
|
||
</section>
|
||
|
||
<section>
|
||
<h1>How can I use different highlighting for tokens with the same name in different languages?</h1>
|
||
<p>Just use a descendant selector, that includes the language class. The default <code>prism.css</code> does this, to have different colors for
|
||
JavaScript strings (which are very common) and CSS strings (which are relatively rare). Here’s that code, simplified to illustrate the technique:
|
||
<pre><code class="language-css">
|
||
.token.string {
|
||
color: #690;
|
||
}
|
||
|
||
.language-css .token.string,
|
||
.style .token.string {
|
||
color: #a67f59;
|
||
}</code></pre>
|
||
|
||
<p>Abbreviated language classes (e.g. <code>lang-css</code>) will be converted to their extended forms, so you don’t need to account for them.</p>
|
||
<p>The same technique can be used to differentiate XML tag namespaces from attribute namespaces:</p>
|
||
<pre><code class="language-css">.tag > .token.namespace {
|
||
color: #b37298;
|
||
}
|
||
.attr-name > .token.namespace {
|
||
color: #ab6;
|
||
}</code></pre>
|
||
</section>
|
||
|
||
<footer data-src="templates/footer.html" data-type="text/html"></footer>
|
||
|
||
<script src="prism.js"></script>
|
||
<script src="utopia.js"></script>
|
||
<script>
|
||
$$('section > h1').forEach(function (h1) {
|
||
$u.element.create('p', {
|
||
contents: {
|
||
tag: 'a',
|
||
properties: {
|
||
href: '#toc'
|
||
},
|
||
contents: '↑ Back to top'
|
||
},
|
||
inside: h1.parentNode
|
||
});
|
||
});
|
||
</script>
|
||
<script src="components.js"></script>
|
||
<script src="code.js"></script>
|
||
|
||
</body>
|
||
</html> |