PageRenderTime 24ms CodeModel.GetById 13ms app.highlight 4ms RepoModel.GetById 1ms app.codeStats 1ms

/samples/scalate-sample-sitegen/src/highlight/readme.eng.txt

http://github.com/scalate/scalate
Plain Text | 486 lines | 376 code | 110 blank | 0 comment | 0 complexity | 9db4724fef74148df95dcc2900c95a2c MD5 | raw file
  1# Highlight.js
  2
  3Highlight.js highlights syntax in code examples on blogs, forums and
  4in fact on any web pages. It's very easy to use because it works
  5automatically: finds blocks of code, detects a language, highlights it.
  6
  7Autodetection can be fine tuned when it fails by itself (see "Heuristics").
  8
  9
 10## Installation and usage
 11
 12Downloaded package includes file "highlight.pack.js" which is a full compressed
 13version of the library intended to use in production. All uncompressed source
 14files are also available, feel free to look into them!
 15
 16The script is installed by linking to a single file and making a single
 17initialization call:
 18
 19    <script type="text/javascript" src="highlight.pack.js"></script>
 20    <script type="text/javascript">
 21      hljs.initHighlightingOnLoad();
 22    </script>
 23
 24Also you can replaces TAB ('\x09') characters used for indentation in your code
 25with some fixed number of spaces or with a `<span>` to set them special styling:
 26
 27    <script type="text/javascript">
 28      hljs.tabReplace = '    '; // 4 spaces
 29      // ... or
 30      hljs.tabReplace = '<span class="indent">\t</span>';
 31
 32      hljs.initHighlightingOnLoad();
 33    </script>
 34
 35Then the script looks in your page for fragments `<pre><code>...</code></pre>`
 36that are used traditionally to mark up code examples. Their content is
 37marked up by logical pieces with defined class names.
 38
 39
 40### Custom initialization
 41
 42If you use different markup for code blocks you can initialize them manually
 43with `highlightBlock(code, tabReplace)` function. It takes a DOM element
 44containing the code to highlight and optionally a string with which to replace
 45TAB characters.
 46
 47Initialization using for example jQuery might look like this:
 48
 49    $(document).ready(function() {
 50      $('pre code').each(function(i, e) {hljs.highlightBlock(e, '    ')});
 51    });
 52
 53
 54### Styling
 55
 56Elements of code marked up with classes can be styled as desired:
 57
 58    .comment {
 59      color: gray;
 60    }
 61
 62    .keyword {
 63      font-weight: bold;
 64    }
 65
 66    .python .string {
 67      color: blue;
 68    }
 69
 70    .html .atribute .value {
 71      color: green;
 72    }
 73
 74Highligt.js comes with several style themes located in "styles" directory that
 75can be used directly or as a base for your own experiments.
 76
 77A full list of available classes is below ("Languages").
 78
 79
 80## Export
 81
 82File export.html contains a little program that shows and allows to copy and paste
 83an HTML code generated by the highlighter for any code snippet. This can be useful
 84in situations when one can't use the script itself on a site.
 85
 86
 87## Languages
 88
 89This is a full list of available classes corresponding to languages'
 90syntactic structures. In parentheses after language names are identifiers
 91used as class names in `<code>` element.
 92
 93Python ("python"):
 94
 95  keyword          keyword
 96  built_in         built-in objects (None, False, True and Ellipsis)
 97  number           number
 98  string           string (of any type)
 99  comment          comment
100  decorator        @-decorator for functions
101  function         function header "def some_name(...):"
102  class            class header "class SomeName(...):"
103  title            name of a function or a class inside a header
104  params           everything inside parentheses in a function's or class' header
105
106Python profiler results ("profile"):
107
108  number           number
109  string           string
110  builtin          builtin function entry
111  filename         filename in an entry
112  summary          profiling summary
113  header           header of table of results
114  keyword          column header
115  function         function name in an entry (including parentheses)
116  title            actual name of a function in an entry (excluding parentheses)
117
118Ruby ("ruby"):
119
120  keyword          keyword
121  string           string
122  subst            in-string substitution (#{...})
123  comment          comment
124  yardoctag        YARD tag
125  function         function header "def some_name(...):"
126  class            class header "class SomeName(...):"
127  title            name of a function or a class inside a header
128  parent           name of a parent class
129  symbol           symbol
130  instancevar      instance variable
131
132Perl ("perl"):
133
134  keyword          keyword
135  comment          comment
136  number           number
137  string           string
138  regexp           regular expression
139  sub              subroutine header (from "sub" till "{")
140  variable         variable starting with "$", "%", "@"
141  operator         operator
142  pod              plain old doc
143
144PHP ("php"):
145
146  keyword          keyword
147  number           number
148  string           string (of any type)
149  comment          comment
150  phpdoc           phpdoc params in comments
151  variable         variable starting with "$"
152  preprocessor     preprocessor marks: "<?php" and "?>"
153
154Scala ("scala"):
155
156  keyword          keyword
157  number           number
158  string           string
159  comment          comment
160  annotaion        annotation
161  javadoc          javadoc comment
162  javadoctag       @-tag in javadoc
163  class            class header
164  title            class name inside a header
165  params           everything in parentheses inside a class header
166  inheritance      keywords "extends" and "with" inside class header
167
168XML ("xml"):
169
170  tag              any tag from "<" till ">"
171  comment          comment
172  pi               processing instruction (<? ... ?>)
173  cdata            CDATA section
174  attribute        attribute
175  value            attribute's value
176
177HTML ("html"):
178
179  keyword          HTML tag
180  tag              any tag from "<" till ">"
181  comment          comment
182  doctype          <!DOCTYPE ... > declaration
183  attribute        tag's attribute with or without value
184  value            attribute's value
185
186CSS ("css"):
187
188  keyword          HTML tag when in selectors, CSS keyword when in rules
189  id               #some_name in selectors
190  class            .some_name in selectors
191  at_rule          @-rule till first "{" or ";"
192  attr_selector    attribute selector (square brackets in a[href^=http://])
193  pseudo           pseudo classes and elemens (:after, ::after etc.)
194  comment          comment
195  rules            everything from "{" till "}"
196  value            property's value inside a rule, from ":" till ";" or
197                   till the end of rule block
198  number           number within a value
199  string           string within a value
200  hexcolor         hex color (#FFFFFF) within a value
201  function         CSS function within a value
202  params           everything between "(" and ")" within a function
203
204Django ("django"):
205
206  keyword          HTML tag in HTML, default tags and default filters in templates
207  tag              any tag from "<" till ">"
208  comment          comment
209  doctype          <!DOCTYPE ... > declaration
210  attribute        tag's attribute with or withou value
211  value            attribute's value
212  template_tag     template tag {% .. %}
213  variable         template variable {{ .. }}
214  template_comment template comment, both {# .. #} and {% comment %}
215  filter           filter from "|" till the next filter or the end of tag
216  argument         filter argument
217
218Javascript ("javascript"):
219
220  keyword          keyword
221  comment          comment
222  number           number
223  literal          special literal: "true", "false" and "null"
224  string           string
225  regexp           regular expression
226  function         header of a function
227  title            name of a function inside a header
228  params           everything inside parentheses in a function's header
229
230VBScript ("vbscript"):
231
232  keyword          keyword
233  number           number
234  string           string
235  comment          comment
236  built_in         built-in function
237
238Lua ("lua"):
239
240  keyword          keyword
241  number           number
242  string           string
243  comment          comment
244  built_in         built-in operator
245  function         header of a function
246  title            name of a function inside a header
247  params           everything inside parentheses in a function's header
248  long_brackets    multiline string in [=[ .. ]=]
249
250Delphi ("delphi"):
251
252  keyword          keyword
253  comment          comment (of any type)
254  number           number
255  string           string
256  function         header of a function, procedure, constructor and destructor
257  title            name of a function, procedure, constructor or destructor
258                   inside a header
259  params           everything inside parentheses in a function's header
260  class            class' body from "= class" till "end;"
261
262Java ("java"):
263
264  keyword          keyword
265  number           number
266  string           string
267  comment          commment
268  annotaion        annotation
269  javadoc          javadoc comment
270  class            class header from "class" till "{"
271  title            class name inside a header
272  params           everything in parentheses inside a class header
273  inheritance      keywords "extends" and "implements" inside class header
274
275C++ ("cpp"):
276
277  keyword          keyword
278  number           number
279  string           string and character
280  comment          comment
281  preprocessor     preprocessor directive
282  stl_container    instantiation of STL containers ("vector<...>")
283
284C# ("cs"):
285
286  keyword          keyword
287  number           number
288  string           string
289  comment          commment
290  xmlDocTag        xmldoc tag ("///", "<!--", "-->", "<..>")
291
292RenderMan RSL ("rsl"):
293
294  keyword          keyword
295  number           number
296  string           string (including @"..")
297  comment          comment
298  preprocessor     preprocessor directive
299  shader           sahder keywords
300  shading          shading keywords
301  built_in         built-in function
302
303RenderMan RIB ("rib"):
304
305  keyword          keyword
306  number           number
307  string           string
308  comment          comment
309  commands         command
310
311Maya Embedded Language ("mel"):
312
313  keyword          keyword
314  number           number
315  string           string
316  comment          comment
317  variable         variable
318
319SQL ("sql"):
320
321  keyword          keyword (mostly SQL'92 and SQL'99)
322  number           number
323  string           string (of any type: "..", '..', `..`)
324  comment          comment
325  aggregate        aggregate function
326
327Smalltalk ("smalltalk"):
328
329  keyword          keyword
330  number           number
331  string           string
332  comment          commment
333  symbol           symbol
334  array            array
335  class            name of a class
336  char             char
337  localvars        block of local variables
338
339Lisp ("lisp"):
340
341  keyword          keyword
342  number           number
343  string           string
344  comment          commment
345  variable         variable
346  literal          b, t and nil
347  list             non-quoted list
348  title            first symbol in a non-quoted list
349  body             remainder of the non-quoted list
350  quoted_list      quoted list, both "(quote .. )" and "'(..)"
351
352Ini ("ini"):
353
354  title            title of a section
355  value            value of a setting of any type
356  string           string
357  number           number
358  keyword          boolean value keyword
359
360Apache ("apache"):
361
362  keyword          keyword
363  number           number
364  comment          commment
365  literal          On and Off
366  sqbracket        variables in rewrites "%{..}"
367  cbracket         options in rewrites "[..]"
368  tag              begin and end of a configuration section
369
370Nginx ("nginx"):
371
372  keyword          keyword
373  string           string
374  number           number
375  comment          comment
376  built_in         built-in constant
377  variable         $-variable
378
379DOS ("dos"):
380
381  keyword          keyword
382  flow             batch control keyword
383  stream           DOS special files ("con", "prn", ...)
384  winutils         some commands (see dos.js specifically)
385  envvar           environment variables
386
387Bash ("bash"):
388
389  keyword          keyword
390  string           string
391  number           number
392  comment          comment
393  literal          special literal: "true" и "false"
394  variable         variable
395  shebang          script interpreter header
396
397Diff ("diff"):
398
399  header           file header
400  chunk            chunk header within a file
401  addition         added lines
402  deletion         deleted lines
403  change           changed lines
404
405Axapta ("axapta"):
406
407  keyword          keyword
408  number           number
409  string           string
410  comment          commment
411  class            class header from "class" till "{"
412  title            class name inside a header
413  params           everything in parentheses inside a class header
414  inheritance      keywords "extends" and "implements" inside class header
415  preprocessor     preprocessor directive
416
4171C ("1c"):
418
419  keyword          keyword
420  number           number
421  date             date
422  string           string
423  comment          commment
424  function         header of function or procudure
425  title            function name inside a header
426  params           everything in parentheses inside a function header
427  preprocessor     preprocessor directive
428
429AVR assembler ("avrasm"):
430
431  keyword          keyword
432  built_in         pre-defined register
433  number           number
434  string           string
435  comment          commment
436  label            label
437  preprocessor     preprocessor directive
438  localvars        substitution in .macro
439
440Parser3 ("parser3"):
441
442  keyword          keyword
443  number           number
444  comment          commment
445  variable         variable starting with "$"
446  preprocessor     preprocessor directive
447  title            user-defined name starting with "@"
448
449TeX ("tex"):
450
451  comment          comment
452  number           number
453  command          command
454  parameter        parameter
455  formula          formula
456  special          special symbol
457
458
459## Heuristics
460
461Autodetection of a code's language is done with a simple heuristics:
462the program tries to highlight a fragment with all available languages and
463counts all syntactic structures that it finds along the way. The language
464with greatest count wins.
465
466This means that in short fragments the probability of an error is high
467(and it really happens sometimes). In this cases you can set the fragment's
468language explicitly by assigning a class to the `<code>` element:
469
470    <pre><code class="html">...</code></pre>
471
472You can use class names recommended in HTML5: "language-html",
473"language-php". Classes also can be assigned to the `<pre>` element.
474
475To disable highlighting of a fragment altogether use "no-highlight" class:
476
477    <pre><code class="no-highlight">...</code></pre>
478
479## Contacts
480
481Version: 5.11
482URL:     http://softwaremaniacs.org/soft/highlight/en/
483Author:  Ivan Sagalaev (Maniac@SoftwareManiacs.Org)
484
485For the license terms see LICENSE files.
486For the list of contributors see AUTHORS.en.txt file.