kmx git

Commit 357124f075cf602f8ca7a6099afea70793db1e0e

2012-07-28T20:48:17
Docs update, added FAQ, new examples
diff --git a/examples.html b/examples.html
index 309d13c..c6abc2b 100644
--- a/examples.html
+++ b/examples.html
@@ -92,8 +92,29 @@ And i'm not</code></pre>
 	
 	<h2>Entities</h2>
 	<pre><code>&amp;amp; &amp;#x2665; &amp;#160; &amp;#x152;</code></pre>
-
-</pre>
+	
+	<h2>Embedded JS and CSS</h2>
+	<pre><code>&lt;!DOCTYPE html>
+&lt;html lang="en">
+&lt;head>
+	&lt;meta charset="utf-8" />
+	&lt;title>I can haz embedded CSS and JS&lt;/title>
+	&lt;style>
+		@media print {
+			p { color: red !important; }
+		}
+	&lt;/style>
+&lt;/head>
+&lt;body>
+	&lt;h1>I can haz embedded CSS and JS&lt;/h1>
+	&lt;script>
+	if (true) {
+		console.log('foo');
+	}
+	&lt;/script>
+	
+&lt;/body>
+&lt;/html></code></pre>
 </section>
 
 <section class="language-css">
@@ -177,8 +198,11 @@ var comment = /\/\*[\w\W]*?\*\//g;</code></pre>
 	If a failure is listed here, it doesn’t mean it will never be fixed. This is more of a “known bugs” list, just with a certain type of bug.
 	</p>
 	
-	<h2>Comment-like strings</h2>
+	<h2>Comment-like substrings</h2>
 	<pre><code>"foo /* bar */ baz"; "foo // bar";</code></pre>
+	
+	<h2>Strings inside regexes</h2>
+	<pre><code>/"foo"/;</code></pre>
 </section>
 
 <footer data-src="templates/footer.html" data-type="text/html"></footer>
diff --git a/faq.html b/faq.html
new file mode 100644
index 0000000..47de6f6
--- /dev/null
+++ b/faq.html
@@ -0,0 +1,135 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+
+<meta charset="utf-8" />
+<title>FAQ ▲ Prism</title>
+<link rel="stylesheet" href="style.css" />
+<link rel="stylesheet" href="prism.css" data-noprefix />
+<style>
+#toc {
+	position: static;
+	font-size: 100%;
+	opacity: 1;
+}
+</style>
+<script src="../prefixfree/prefixfree.min.js"></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, or Questions I want people to Frequently Ask.</p>
+</header>
+
+<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, it just appears faster because it doesn’t block the main thread.
+	Also, Web Workers cannot interact with the DOM and most other APIs, 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, there are sufficient hooks to allow you to <a href="extending.html#writing-plugins">write a plugin</a> that retains it.</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 the “<a href="#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 print its tokens. 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">
+.language-javascript .token.string {
+	color: #690;
+}
+
+.language-css .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 is 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('a', {
+			properties: {
+				href: '#toc'
+			},
+			contents: '↑ Back to top',
+			inside: h1.parentNode
+		});
+	});
+</script>
+<script src="code.js"></script>
+
+</body>
+</html>
\ No newline at end of file
diff --git a/index.html b/index.html
index c0b0594..df3aa78 100644
--- a/index.html
+++ b/index.html
@@ -9,7 +9,7 @@
 <meta charset="utf-8" />
 <title>Prism</title>
 <link rel="stylesheet" href="style.css" />
-<link rel="stylesheet" href="prism.css" data-noprefix />
+<link rel="stylesheet" href="prism-funky.css" data-noprefix id="prism-css" />
 <script src="../prefixfree/prefixfree.min.js"></script>
 
 </head>
@@ -20,8 +20,16 @@
 	
 	<ul id="features">
 		<li>
+			<strong>Dead simple</strong>
+			Include prism.css and prism.js, use proper HTML5 code tags (<code>code.language-xxxx</code>), done!
+		</li>
+		<li>
+			<strong>Intuitive</strong>
+			Language classes are inherited so you can only define the language once for multiple code snippets.
+		</li>
+		<li>
 			<strong>Incredibly lightweight</strong>
-			Only 1.5KB minified &amp; gzipped (core)
+			The core is 1.5KB minified &amp; gzipped. Languages add 0.3-0.5KB each, themes are around 1KB.
 		</li>
 		<li>
 			<strong>Blazing fast</strong>
@@ -33,20 +41,38 @@
 		</li>
 		<li>
 			<strong>Easily themeable</strong>
-			All styling is done through CSS, with sensible class names
+			All styling is done through CSS, with sensible class names like <code>.comment</code>, <code>.string</code>, <code>.property</code> etc
 		</li>
 	</ul>
 	
 </header>
 
+<section id="examples">
+	<h1>Examples</h1>
+	
+	<p>The Prism source, highlighted with Prism (don’t you just love how meta this is?):</p>
+	<pre data-src="prism.js"></pre>
+	
+	<p>This page’s CSS code, highlighted with Prism:</p>
+	<pre data-src="style.css"></pre>
+	
+	<p>This page’s HTML, highlighted with Prism:</p>
+	<pre data-src="index.html"></pre>
+	
+	<p>This page’s logo (SVG), highlighted with Prism:</p>
+	<pre data-src="logo.svg"></pre>
+	
+	<p>If you’re still not sold, you can <a href="examples.html">view more examples</a>.</p>
+</section>
+
 <section id="features-full">
 	<h1>Full list of features</h1>
 	<ul>
 		<li><strong>Only 1.5KB</strong> minified &amp; gzipped (core). Each language definition adds roughly 300-500 bytes.</li>
-		<li>Supports <strong>parallelism with Web Workers</strong>, if available. Disabled by default.</li>
+		<li>Supports <strong>parallelism with Web Workers</strong>, if available. Disabled by default (<a href="faq.html#why-is-asynchronous-highlighting-disabled-by-default">why?</a>).</li>
 		<li>Very easy to extend without modifying the code, due to Prism’s <a href="#plugins">plugin architecture</a>. Multiple hooks are scattered throughout the source.</li>
 		<li>Very easy to <a href="extending.html#language-definitions">define new languages</a>. Only thing you need is a good understanding of regular expressions</li>
-		<li>All styling is done through CSS, with sensible class names rather than ugly namespaced abbreviated nonsense.</li>
+		<li>All styling is done through CSS, with <a href="faq.html#how-do-i-know-which-tokens-i-can-style-for">sensible class names</a> rather than ugly namespaced abbreviated nonsense.</li>
 		<li>Wide browser support: IE9+, Firefox, Chrome, Safari, Opera, most Mobile browsers</li>
 		<li>Highlight specific lines and/or line ranges (requires <a href="plugins/line-highlight/">plugin</a>)</li>
 		<li>Show invisible characters like tabs, line breaks etc (requires <a href="plugins/show-invisibles/">plugin</a>)</li>
@@ -56,29 +82,12 @@
 <section id="limitations">
 	<h1>Limitations</h1>
 	<ul>
-		<li>Any pre-existing HTML in the code will be stripped off</li>
+		<li>Any pre-existing HTML in the code will be stripped off. <a href="faq.html#if-pre-existing-html-is-stripped-off-how-can-i-highlight">There are ways around it though</a>.</li>
 		<li>Regex-based so it *will* fail on certain edge cases.</li>
 		<li>No IE 6-8 support. If someone can read code, they are probably in the 85% of the population with a modern browser.</li>
 	</ul>
 </section>
 
-<section id="examples">
-	<h1>Examples</h1>
-	<p>The Prism source, highlighted with Prism (don’t you just love how meta this is?):</p>
-	<pre data-src="prism.js"></pre>
-	
-	<p>This page’s CSS code, highlighted with Prism:</p>
-	<pre data-src="style.css"></pre>
-	
-	<p>This page’s HTML, highlighted with Prism:</p>
-	<pre data-src="index.html"></pre>
-	
-	<p>This page’s logo (SVG), highlighted with Prism:</p>
-	<pre data-src="logo.svg"></pre>
-	
-	<p>If you’re still not sold, you can <a href="examples.html">view more examples</a>.</p>
-</section>
-
 <section id="basic-usage" class="language-markup">
 	<h1>Basic usage</h1>
 	
@@ -138,7 +147,6 @@
 <script src="prism.js" data-default-language="markup"></script>
 <script src="utopia.js"></script>
 <script src="code.js"></script>
-<script src="download.js"></script>
 
 </body>
 </html>
\ No newline at end of file
diff --git a/templates/footer.html b/templates/footer.html
index cf93e80..2187a46 100644
--- a/templates/footer.html
+++ b/templates/footer.html
@@ -6,6 +6,7 @@ and <a href="https://github.com/LeaVerou/prism/contributors" target="_blank">all
 	<ul>
 		<li><a href="index.html">Home</a></li>
 		<li><a href="download.html">Download</a></li>
+		<li><a href="faq.html">FAQ</a></li>
 		<li><a href="extending.html">Extending Prism</a></li>
 		<li><a href="https://github.com/LeaVerou/prism/">Fork Prism on Github</a></li>
 	</ul>
kmx.io/prism.js

Commit 357124f075cf602f8ca7a6099afea70793db1e0e
