user guide updates for code sections

doc/user_guide.md

@@ -93,8 +93,10 @@ The following files should be added to source control:
 Add the following line to `.gitignore` (or the equivalent thereof for different
 version control systems):
 
-    /.rscons*
+```
-    /build/
+/.rscons*
+/build/
+```
 
 # The Build Script
 
@@ -102,11 +104,13 @@ Rscons looks for instructions for what to build by reading a build script file
 called `Rsconscript` (or `Rsconscript.rb`).
 Here is a simple example `Rsconscript` file:
 
-    build do
+```ruby
+build do
   Environment.new do |env|
     env.Program("myprog.exe", glob("src/**/*.c"))
   end
-    end
+end
+```
 
 This `Rsconscript` file would instruct Rscons to produce a *Program* target
 called `myprog.exe` which is to be built from all C source files found
@@ -183,10 +187,12 @@ A `configure` block is optional.
 It can be used to perform various checks and setup operations for a project.
 Example `configure` block:
 
-    configure do
+```ruby
+configure do
   check_cxx_compiler
   check_c_header "getopt.h"
-    end
+end
+```
 
 ### Checking for a Compiler
 
@@ -203,11 +209,13 @@ If such a list is supplied, the compilers are tested in the order listed.
 Here are example calls which also show the default compiler list for each
 supported language:
 
-    configure do
+```ruby
+configure do
   check_c_compiler "gcc", "clang"
   check_cxx_compiler "g++", "clang++"
   check_d_compiler "gdc", "ldc2"
-    end
+end
+```
 
 ### Checking for a Header File
 
@@ -221,11 +229,13 @@ first argument, and take an optional Hash of arguments as the second argument.
 
 Example calls:
 
-    configure do
+```ruby
+configure do
   check_c_header "getopt.h", fail: false, set_define: "HAVE_GETOPT_H"
   check_c_header "FreeType2.h"
   check_cxx_header "memory"
-    end
+end
+```
 
 #### Options
 
@@ -247,10 +257,12 @@ This method takes the name of the import to check for as the first argument.
 
 Example calls:
 
-    configure do
+```ruby
+configure do
   check_d_import "std.stdio"
   check_d_import "std.numeric"
-    end
+end
+```
 
 ### Checking for a Library
 
@@ -261,10 +273,12 @@ and take an optional Hash of arguments as the second argument.
 
 Example calls:
 
-    configure do
+```ruby
+configure do
   check_lib "kpty", fail: false, set_define: "HAVE_LIBKPTY"
   check_lib "GL"
-    end
+end
+```
 
 #### Options
 
@@ -285,9 +299,11 @@ host operating system environment.
 
 Example call:
 
-    configure do
+```ruby
+configure do
   check_program "xxd"
-    end
+end
+```
 
 ### Checking for a Package Configuration
 
@@ -299,10 +315,12 @@ This method takes a Hash of options as its only argument.
 
 Example calls:
 
-    configure do
+```ruby
+configure do
   check_cfg package: "zlib"
   check_cfg program: "freetype-config", fail: false, set_define: "HAVE_FREETYPE"
-    end
+end
+```
 
 #### Options
 
@@ -333,11 +351,13 @@ An Rscons build script would not be very useful without a `build` block.
 
 Here is an example `build` block demonstrating how to register a build target:
 
-    build do
+```ruby
+build do
   Environment.new do |env|
     env.Program("myprog.exe", glob("src/**/*.c"))
   end
-    end
+end
+```
 
 This `Rsconscript` would build an executable called `myprog.exe` from all C
 source files found recursively under the `src` directory.
@@ -359,11 +379,13 @@ It supports a syntax similar to the Ruby [Dir.glob method](https://ruby-doc.org/
 
 Example use:
 
-    build do
+```ruby
+build do
   Environment.new do |env|
     env.Program("mytests", glob("src/**/*.cc", "test/**/*.cc"))
   end
-    end
+end
+```
 
 This example would build the `mytests` executable from all `.cc` source files
 found recursively under the `src` or `test` directory.
@@ -377,12 +399,14 @@ construction variables.
 
 Example:
 
-    build do
+```ruby
+build do
   Environment.new do |env|
     env["CCFLAGS"] += %w[-O2 -Wall]
     env["LIBS"] += %w[m]
   end
-    end
+end
+```
 
 This example modifies the `CCFLAGS` construction variable to add `-O2` and
 `-Wall` to the compilation commands used for C and C++ source files.
@@ -591,7 +615,8 @@ build target or source file names.
 
 Example:
 
-    build do
+```ruby
+build do
   Environment.new do |env|
     env["CFLAGS"] << "-Wall"
     env.add_build_hook do |builder|
@@ -602,7 +627,8 @@ Example:
     end
     env.Program("program.exe", glob("src/**/*.c"))
   end
-    end
+end
+```
 
 This example script would compile all C sources under the `src` directory with
 the `-Wall` flag except for sources under the `src/tests` directory.
@@ -619,7 +645,7 @@ the `-Wall` flag except for sources under the `src/tests` directory.
 
 # License
 
-Rscons is licensed under the terms of the MIT License.
+Rscons is licensed under the terms of the MIT License:
 
 ```
 ${include LICENSE.txt}

rb/assets/user_guide.html.erb

@@ -5,6 +5,9 @@
       body {
         max-width: 140ex;
       }
+      .code {
+        padding-left: 2ex;
+      }
       .ruby_code .normal {}
       .ruby_code .comment { color: #005; font-style: italic; }
       .ruby_code .keyword { color: #A00; font-weight: bold; }

rb/gen_user_guide.rb

@@ -63,9 +63,9 @@ class Generator
     end
     if syntax != ""
       convertor = Syntax::Convertors::HTML.for_syntax(syntax)
-      %[<div class="#{syntax}_code">\n#{convertor.convert(code)}\n</div>\n]
+      %[<div class="code #{syntax}_code">\n#{convertor.convert(code)}\n</div>\n]
     else
-      %[<div class="code">\n#{code}\n</div>\n]
+      %[<div class="code">\n<pre>#{code}</pre>\n</div>\n]
     end
   end
 end