08-27-周三_17-09-29

node_modules/highlight.js/docs/building-testing.rst

@@ -0,0 +1,88 @@
+Building and testing
+====================
+
+To actually run highlight.js it is necessary to build it for the environment
+where you're going to run it: a browser, the node.js server, etc.
+
+
+Building
+--------
+
+The build tool is written in JavaScript using node.js. Before running the
+script, make sure to have node installed and run ``npm install`` to get the
+dependencies.
+
+The tool is located in ``tools/build.js``. A few useful examples:
+
+* Build for a browser using only common languages::
+
+    node tools/build.js :common
+
+* Build for node.js including all available languages::
+
+    node tools/build.js -t node
+
+* Build two specific languages for debugging, skipping compression in this case::
+
+    node tools/build.js -n python ruby
+
+On some systems the node binary is named ``nodejs``; simply replace ``node``
+with ``nodejs`` in the examples above if that is the case.
+
+The full option reference is available with the usual ``--help`` option.
+
+The build result will be in the ``build/`` directory.
+
+.. _basic-testing:
+
+Basic testing
+-------------
+
+The usual approach to debugging and testing a language is first doing it
+visually. You need to build highlight.js with only the language you're working
+on (without compression, to have readable code in browser error messages) and
+then use the Developer tool in ``tools/developer.html`` to see how it highlights
+a test snippet in that language.
+
+A test snippet should be short and give the idea of the overall look of the
+language. It shouldn't include every possible syntactic element and shouldn't
+even make practical sense.
+
+After you satisfied with the result you need to make sure that language
+detection still works with your language definition included in the whole suite.
+
+Testing is done using `Mocha <http://mochajs.org/>`_ and the
+files are found in the ``test/`` directory. You can use the node build to
+run the tests in the command line with ``npm test`` after installing the
+dependencies with ``npm install``.
+
+**Note**: for Debian-based machine, like Ubuntu, you might need to create an
+alias or symbolic link for nodejs to node. The reason for this is the
+dependencies that are requires to test highlight.js has a reference to
+"node".
+
+Place the snippet you used inside the browser in
+``test/detect/<language>/default.txt``, build the package with all the languages
+for node and run the test suite. If your language breaks auto-detection, it
+should be fixed by :ref:`improving relevance <relevance>`, which is a black art
+in and of itself. When in doubt, please refer to the discussion group!
+
+
+Testing markup
+--------------
+
+You can also provide additional markup tests for the language to test isolated
+cases of various syntactic construct. If your language has 19 different string
+literals or complicated heuristics for telling division (``/``) apart from
+regexes (``/ .. /``) -- this is the place.
+
+A test case consists of two files:
+
+* ``test/markup/<language>/<test_name>.txt``: test code
+* ``test/markup/<language>/<test_name>.expect.txt``: reference rendering
+
+To generate reference rendering use the Developer tool located at
+``tools/developer.html``. Make sure to explicitly select your language in the
+drop-down menu, as automatic detection is unlikely to work in this case.
+
+