From b119c5577678b14f320a1a5cd58d8f591cb3084d Mon Sep 17 00:00:00 2001
From: Guinness <guinness@crans.org>
Date: Mon, 13 Jul 2020 11:16:51 +0200
Subject: Syntax highlighting in the docs

This adds the syntax highlights in the MarkDown files.
Fixes #33741
---
 doc/HACKING/HelpfulTools.md | 130 +++++++++++++++++++++++++++-----------------
 1 file changed, 80 insertions(+), 50 deletions(-)

(limited to 'doc/HACKING/HelpfulTools.md')

diff --git a/doc/HACKING/HelpfulTools.md b/doc/HACKING/HelpfulTools.md
index 15bd153318..0ce59576f0 100644
--- a/doc/HACKING/HelpfulTools.md
+++ b/doc/HACKING/HelpfulTools.md
@@ -43,7 +43,9 @@ Builds should show up on the web at jenkins.torproject.org and on IRC at
 
 ## Valgrind
 
-    valgrind --leak-check=yes --error-limit=no --show-reachable=yes src/app/tor
+```console
+$ valgrind --leak-check=yes --error-limit=no --show-reachable=yes src/app/tor
+```
 
 (Note that if you get a zillion openssl warnings, you will also need to
 pass `--undef-value-errors=no` to valgrind, or rebuild your openssl
@@ -77,10 +79,12 @@ we wish to permit are also documented in the blacklist file.
 Lcov is a utility that generates pretty HTML reports of test code coverage.
 To generate such a report:
 
-    ./configure --enable-coverage
-    make
-    make coverage-html
-    $BROWSER ./coverage_html/index.html
+```console
+$ ./configure --enable-coverage
+$ make
+$ make coverage-html
+$ $BROWSER ./coverage_html/index.html
+```
 
 This will run the tor unit test suite `./src/test/test` and generate the HTML
 coverage code report under the directory `./coverage_html/`. To change the
@@ -93,36 +97,48 @@ investigated (as of July 2014).
 
 To quickly run all the tests distributed with Tor:
 
-    make check
+```console
+$ make check
+```
 
 To run the fast unit tests only:
 
-    make test
+```console
+$ make test
+```
 
 To selectively run just some tests (the following can be combined
 arbitrarily):
 
-    ./src/test/test <name_of_test> [<name of test 2>] ...
-    ./src/test/test <prefix_of_name_of_test>.. [<prefix_of_name_of_test2>..] ...
-    ./src/test/test :<name_of_excluded_test> [:<name_of_excluded_test2]...
+```console
+$ ./src/test/test <name_of_test> [<name of test 2>] ...
+$ ./src/test/test <prefix_of_name_of_test>.. [<prefix_of_name_of_test2>..] ...
+$ ./src/test/test :<name_of_excluded_test> [:<name_of_excluded_test2]...
+```
 
 To run all tests, including those based on Stem or Chutney:
 
-    make test-full
+```console
+$ make test-full
+```
 
 To run all tests, including those based on Stem or Chutney that require a
 working connection to the internet:
 
-    make test-full-online
+```console
+$ make test-full-online
+```
 
 ## Running gcov for unit test coverage
 
-    ./configure --enable-coverage
-    make
-    make check
-    # or--- make test-full ? make test-full-online?
-    mkdir coverage-output
-    ./scripts/test/coverage coverage-output
+```console
+$ ./configure --enable-coverage
+$ make
+$ make check
+$ # or--- make test-full ? make test-full-online?
+$ mkdir coverage-output
+$ ./scripts/test/coverage coverage-output
+```
 
 (On OSX, you'll need to start with `--enable-coverage CC=clang`.)
 
@@ -145,7 +161,9 @@ you can run `make reset-gcov` to clear the intermediary gcov output.
 If you have two different `coverage-output` directories, and you want to see
 a meaningful diff between them, you can run:
 
-    ./scripts/test/cov-diff coverage-output1 coverage-output2 | less
+```console
+$ ./scripts/test/cov-diff coverage-output1 coverage-output2 | less
+```
 
 In this diff, any lines that were visited at least once will have coverage "1",
 and line numbers are deleted.  This lets you inspect what you (probably) really
@@ -313,12 +331,16 @@ that you're using the emacs-specific version of `etags` (bundled under the
 If you're using vim or emacs, you can also use Universal Ctags to build a tag
 file using the syntax:
 
-    ctags -R -D 'MOCK_IMPL(r,h,a)=r h a' .
+```console
+$ ctags -R -D 'MOCK_IMPL(r,h,a)=r h a' .
+```
 
 If you're using an older version of Universal Ctags, you can use the following
 instead:
 
-    ctags -R --mline-regex-c='/MOCK_IMPL\([^,]+,\W*([a-zA-Z0-9_]+)\W*,/\1/f/{mgroup=1}' .
+```console
+ctags -R --mline-regex-c='/MOCK_IMPL\([^,]+,\W*([a-zA-Z0-9_]+)\W*,/\1/f/{mgroup=1}' .
+```
 
 A vim-compatible tag file will be generated by default. If you use emacs, add
 the `-e` flag to generate an emacs-compatible tag file.
@@ -330,50 +352,58 @@ source code. Here's how to use it:
 
   1. Begin every file that should be documented with
 
-         /**
-          * \file filename.c
-          * \brief Short description of the file.
-          */
+```
+ /**
+  * \file filename.c
+  * \brief Short description of the file.
+  */
+```
 
-     (Doxygen will recognize any comment beginning with /** as special.)
+  (Doxygen will recognize any comment beginning with /** as special.)
 
   2. Before any function, structure, #define, or variable you want to
      document, add a comment of the form:
 
-        /** Describe the function's actions in imperative sentences.
-         *
-         * Use blank lines for paragraph breaks
-         *   - and
-         *   - hyphens
-         *   - for
-         *   - lists.
-         *
-         * Write <b>argument_names</b> in boldface.
-         *
-         * \code
-         *     place_example_code();
-         *     between_code_and_endcode_commands();
-         * \endcode
-         */
+```
+/** Describe the function's actions in imperative sentences.
+ *
+ * Use blank lines for paragraph breaks
+ *   - and
+ *   - hyphens
+ *   - for
+ *   - lists.
+ *
+ * Write <b>argument_names</b> in boldface.
+ *
+ * \code
+ *     place_example_code();
+ *     between_code_and_endcode_commands();
+ * \endcode
+ */
+```
 
   3. Make sure to escape the characters `<`, `>`, `\`, `%` and `#` as `\<`,
      `\>`, `\\`, `\%` and `\#`.
 
   4. To document structure members, you can use two forms:
 
-        struct foo {
-          /** You can put the comment before an element; */
-          int a;
-          int b; /**< Or use the less-than symbol to put the comment
-                 * after the element. */
-        };
+```c
+struct foo {
+  /** You can put the comment before an element; */
+  int a;
+  int b; /**< Or use the less-than symbol to put the comment
+         * after the element. */
+};
+```
 
   5. To generate documentation from the Tor source code, type:
 
-        $ doxygen -g
+```console
+$ doxygen -g
+```
 
-     to generate a file called `Doxyfile`.  Edit that file and run
-     `doxygen` to generate the API documentation.
+  to generate a file called `Doxyfile`.  Edit that file and run
+  `doxygen` to generate the API documentation.
 
   6. See the Doxygen manual for more information; this summary just
      scratches the surface.
-- 
cgit v1.2.3-54-g00ecf