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
-      Environment.new do |env|
+build do
-        env.Program("myprog.exe", glob("src/**/*.c"))
+  Environment.new do |env|
-      end
+    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
-      check_cxx_compiler
+configure do
-      check_c_header "getopt.h"
+  check_cxx_compiler
-    end
+  check_c_header "getopt.h"
+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
-      check_c_compiler "gcc", "clang"
+configure do
-      check_cxx_compiler "g++", "clang++"
+  check_c_compiler "gcc", "clang"
-      check_d_compiler "gdc", "ldc2"
+  check_cxx_compiler "g++", "clang++"
-    end
+  check_d_compiler "gdc", "ldc2"
+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
-      check_c_header "getopt.h", fail: false, set_define: "HAVE_GETOPT_H"
+configure do
-      check_c_header "FreeType2.h"
+  check_c_header "getopt.h", fail: false, set_define: "HAVE_GETOPT_H"
-      check_cxx_header "memory"
+  check_c_header "FreeType2.h"
-    end
+  check_cxx_header "memory"
+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
-      check_d_import "std.stdio"
+configure do
-      check_d_import "std.numeric"
+  check_d_import "std.stdio"
-    end
+  check_d_import "std.numeric"
+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
-      check_lib "kpty", fail: false, set_define: "HAVE_LIBKPTY"
+configure do
-      check_lib "GL"
+  check_lib "kpty", fail: false, set_define: "HAVE_LIBKPTY"
-    end
+  check_lib "GL"
+end
+```
 
 #### Options
 
@@ -285,9 +299,11 @@ host operating system environment.
 
 Example call:
 
-    configure do
+```ruby
-      check_program "xxd"
+configure do
-    end
+  check_program "xxd"
+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
-      check_cfg package: "zlib"
+configure do
-      check_cfg program: "freetype-config", fail: false, set_define: "HAVE_FREETYPE"
+  check_cfg package: "zlib"
-    end
+  check_cfg program: "freetype-config", fail: false, set_define: "HAVE_FREETYPE"
+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
-      Environment.new do |env|
+build do
-        env.Program("myprog.exe", glob("src/**/*.c"))
+  Environment.new do |env|
-      end
+    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
-      Environment.new do |env|
+build do
-        env.Program("mytests", glob("src/**/*.cc", "test/**/*.cc"))
+  Environment.new do |env|
-      end
+    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
-      Environment.new do |env|
+build do
-        env["CCFLAGS"] += %w[-O2 -Wall]
+  Environment.new do |env|
-        env["LIBS"] += %w[m]
+    env["CCFLAGS"] += %w[-O2 -Wall]
-      end
+    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.
@@ -420,8 +444,8 @@ There are several default builders that are built-in to Rscons:
 env.Command(target, sources, "CMD" => command)
 # Example
 env.Command("docs.html", "docs.md",
-    "CMD" => ["pandoc", "-fmarkdown", "-thtml", "-o${_TARGET}", "${_SOURCES}"],
+  "CMD" => ["pandoc", "-fmarkdown", "-thtml", "-o${_TARGET}", "${_SOURCES}"],
-    "CMD_DESC" => "PANDOC")
+  "CMD_DESC" => "PANDOC")
 ```
 
 The `Command` builder executes a user-defined command in order to produce the
@@ -591,18 +615,20 @@ build target or source file names.
 
 Example:
 
-    build do
+```ruby
-      Environment.new do |env|
+build do
-        env["CFLAGS"] << "-Wall"
+  Environment.new do |env|
-        env.add_build_hook do |builder|
+    env["CFLAGS"] << "-Wall"
-          # Compile sources from under src/tests without the -Wall flag.
+    env.add_build_hook do |builder|
-          if builder.sources.first =~ %r{src/tests/}
+      # Compile sources from under src/tests without the -Wall flag.
-            builder.vars["CFLAGS"] -= %w[-Wall]
+      if builder.sources.first =~ %r{src/tests/}
-          end
+        builder.vars["CFLAGS"] -= %w[-Wall]
-        end
-        env.Program("program.exe", glob("src/**/*.c"))
       end
     end
+    env.Program("program.exe", glob("src/**/*.c"))
+  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