From 5b3b3e46eadaccf6586b40bcd4cba51809e72b12 Mon Sep 17 00:00:00 2001
From: Lars Christensen <larsch@belunktum.dk>
Date: Sat, 14 Mar 2020 14:06:53 +0100
Subject: [PATCH] Convert README to markdown

---
 Manifest.txt             |   2 +-
 README.rdoc => README.md | 217 +++++++++++++++++++--------------------
 Rakefile                 |  49 +++++----
 3 files changed, 132 insertions(+), 136 deletions(-)
 rename README.rdoc => README.md (77%)

diff --git a/Manifest.txt b/Manifest.txt
index 1bff2932..3393724e 100644
--- a/Manifest.txt
+++ b/Manifest.txt
@@ -1,6 +1,6 @@
 History.txt
 Manifest.txt
-README.rdoc
+README.md
 Rakefile
 bin/ocra
 share/ocra/lzma.exe
diff --git a/README.rdoc b/README.md
similarity index 77%
rename from README.rdoc
rename to README.md
index a91f9bc2..8e2d839f 100644
--- a/README.rdoc
+++ b/README.md
@@ -1,23 +1,25 @@
-= ocra
+# ocra
 
-* https://github.com/larsch/ocra/
-* Issue tracker: http://github.com/larsch/ocra/issues
-* Google Group: http://groups.google.com/group/ruby-ocra
+home   :: https://github.com/larsch/ocra/
 
-== DESCRIPTION:
+issues :: http://github.com/larsch/ocra/issues
+
+forum  :: http://groups.google.com/group/ruby-ocra
+
+## Description
 
 OCRA (One-Click Ruby Application) builds Windows executables from Ruby
 source code. The executable is a self-extracting, self-running
 executable that contains the Ruby interpreter, your source code and
 any additionally needed ruby libraries or DLL.
 
-== FEATURES
+## Features
 
 * LZMA Compression (optional, default on)
 * Both windowed/console mode supported
 * Includes gems based on usage, or from a Bundler Gemfile
 
-== PROBLEMS & BUG REPORTING:
+## Problems & Bug Reporiting
 
 * Windows support only
 
@@ -26,11 +28,11 @@ the issue tracker on GitHub (http://github.com/larsch/ocra/issues).
 You can also join the Google Group discussion forum to ask questions
 and get help (http://groups.google.com/group/ruby-ocra).
 
-== INSTALLATION:
+## Installation
 
 Gem:
 
-  gem install ocra
+    gem install ocra
 
 Alternatively you can download the gem at either
 http://rubygems.org/gems/ocra or
@@ -40,23 +42,23 @@ Stand-alone Version: Get ocrasa.rb from
 https://github.com/larsch/ocra/releases/. Requires nothing but a
 working Ruby installation on Windows.
 
-== SYNOPSIS:
+## Synopsis
 
-=== Building an executable:
+### Building an executable:
 
-  ocra script.rb
+    ocra script.rb
 
-Will package "<tt>script.rb</tt>", the Ruby interpreter and all
+Will package `script.rb`, the Ruby interpreter and all
 dependencies (gems and DLLs) into an executable named
-"<tt>script.exe</tt>".
+`script.exe`.
 
-=== Command line:
+### Command line:
   
-  ocra [options] script.rb [<other files> ...] [-- <script arguments> ...]
+    ocra [options] script.rb [<other files> ...] [-- <script arguments> ...]
 
-=== Options:
+### Options:
 
-  ocra --help
+    ocra --help
 
 Ocra options:
 
@@ -80,23 +82,27 @@ Gem content detection modes:
     --gem-full[=gem1,..]     Include EVERYTHING
     --gem-spec[=gem1,..]     Include files in gemspec (Does not work with Rubygems 1.7+)
 
-  minimal: loaded scripts  
-  guess: loaded scripts and other files  
-  all: loaded scripts, other scripts, other files (except extras)  
-  full: Everything found in the gem directory  
-
     --[no-]gem-scripts[=..]  Other script files than those loaded
     --[no-]gem-files[=..]    Other files (e.g. data files)
     --[no-]gem-extras[=..]   Extra files (README, etc.)
 
-  scripts: .rb/.rbw files  
-  extras: C/C++ sources, object files, test, spec, README  
-  files: all other files  
+Gem modes:
+
+* *minimal*: loaded scripts
+* *guess*: loaded scripts and other files
+* *all*: loaded scripts, other scripts, other files (except extras)
+* *full*: Everything found in the gem directory
+
+File groups:
+
+* *scripts*: .rb/.rbw files  
+* *extras*: C/C++ sources, object files, test, spec, README  
+* *files*: all other files  
 
 Auto-detection options:
 
     --no-dep-run       Don't run script.rb to check for dependencies.
-   --no-autoload      Don't load/include script.rb's autoloads.
+    --no-autoload      Don't load/include script.rb's autoloads.
     --no-autodll       Disable detection of runtime DLL dependencies.
 
 Output options:
@@ -115,9 +121,9 @@ Executable options:
     --debug-extract    Executable will unpack to local dir and not delete after.  
 
   
-=== Compilation:
+### Compilation:
 
-* OCRA will load your script (using <tt>Kernel#load</tt>) and build
+* OCRA will load your script (using `Kernel#load`) and build
   the executable when it exits.
 
 * Your program should 'require' all necessary files when invoked without
@@ -128,56 +134,49 @@ Executable options:
 
 * .rb files will become console applications. .rbw files will become
   windowed application (without a console window popping
-  up). Alternatively, use the "<tt>--console</tt>" or
-  "<tt>--windows</tt>" options.
+  up). Alternatively, use the `--console` or
+  `--windows` options.
 
-=== Running your application:
+### Running your application:
 
 * The 'current working directory' is not changed by OCRA when running
   your application. You must change to the installation or temporary
   directory yourself. See also below.
-
 * When the application is running, the OCRA_EXECUTABLE environment
   variable points to the .exe (with full path).
-
 * The temporary location of the script can be obtained by inspected
   the $0 variable.
-
-* OCRA does not set up the include path. Use <tt>$:.unshift
-  File.dirname($0)</tt> at the start of your script if you need to
+* OCRA does not set up the include path. Use `$:.unshift
+  File.dirname($0)` at the start of your script if you need to
   'require' additional source files from the same directory as your
   main script.
 
-=== Pitfalls:
+### Pitfalls:
 
 * Avoid modifying load paths at run time. Specify load paths using -I
   or RUBYLIB if you must, but don't expect OCRA to preserve them for
   runtime. OCRA may pack sources into other directories than you
   expect.
-
-* If you use .rbw files or the <tt>--windows</tt> option, then check
+* If you use .rbw files or the `--windows` option, then check
   that your application works with rubyw.exe before trying with OCRA.
-
 * Avoid absolute paths in your code and when invoking OCRA.
 
-== REQUIREMENTS:
+## REQUIREMENTS:
 
 * Windows
-
 * Working Ruby installation.
-
 * MinGW Installation (when working with the source code only)
 
-=== Stand-alone version
+### Stand-alone version
 
 Get ocrasa.rb from http://rubyforge.org/frs/?group_id=8185. Requires
 nothing but a working Ruby installation on Windows.
 
-== TECHNICAL DETAILS
+## Technical details
 
 OCRA first runs the target script in order to detect any files that
-are loaded and used at runtime (Using <tt>Kernel#require</tt> and
-<tt>Kernel#load</tt>).
+are loaded and used at runtime (Using `Kernel#require` and
+`Kernel#load`).
 
 OCRA embeds everything needed to run a Ruby script into a single
 executable file. The file contains the .exe stub which is compiled
@@ -191,9 +190,9 @@ scripts into a temporary directory. The directory will contains the
 same directory layout as your Ruby installlation. The source files for
 your application will be put in the 'src' subdirectory.
 
-=== Libraries
+### Libraries
 
-Any code that is loaded through <tt>Kernel#require</tt> when your
+Any code that is loaded through `Kernel#require` when your
 script is executed will be included in the OCRA
 executable. Conditionally loaded code will not be loaded and included
 in the executable unless the code is actually run when OCRA invokes
@@ -209,13 +208,13 @@ gems using --gem-*=gemname.
 
 Libraries found in non-standard path (for example, if you invoke OCRA
 with "ruby -I some/path") will be placed into the site dir
-(lib/ruby/site_ruby). Avoid changing <tt>$LOAD_PATH</tt> or
-<tt>$:</tt> from your script to include paths outside your source
+(lib/ruby/site_ruby). Avoid changing `$LOAD_PATH` or
+`$:` from your script to include paths outside your source
 tree, since OCRA may place the files elsewhere when extracted into the
 temporary directory.
 
 In case your script (or any of its dependencies) sets up autoloaded
-module using <tt>Kernel#autoload</tt>, OCRA will automatically try to
+module using `Kernel#autoload`, OCRA will automatically try to
 load them to ensure that they are all included in the
 executable. Modules that doesn't exist will be ignored (a warning will
 be logged).
@@ -223,19 +222,19 @@ be logged).
 Dynamic link libraries (.dll files, for example WxWidgets, or other
 source files) will be detected and included by OCRA.
 
-=== Including libraries non-automatically
+### Including libraries non-automatically
 
 If an application or framework is complicated enough that it tends
 to confuse Ocra's automatic dependency resolution, then you can
 use other means to specify what needs to be packaged with your app.
 
-To disable automatic dependency resolution, use the --no-dep-run
+To disable automatic dependency resolution, use the `--no-dep-run`
 option; with it, Ocra will skip executing your program during the
-build process. This on the other hand requires using --gem-full option
+build process. This on the other hand requires using `--gem-full` option
 (see more below); otherwise Ocra will not include all the necessary
 files for the gems.
 
-You will also probably need to use the --add-all-core option to
+You will also probably need to use the `--add-all-core` option to
 include the Ruby core libraries.
 
 If your app uses gems, then you can specify them in a
@@ -252,17 +251,17 @@ directory "someapp" and create an exe named "someapp.exe", without
 actually running the app during the build, you could use the
 following command:
 
-  ocra someapp/script/rails someapp --output someapp.exe --add-all-core \
-  --gemfile someapp/Gemfile --no-dep-run --gem-full --chdir-first -- server
+    ocra someapp/script/rails someapp --output someapp.exe --add-all-core \
+    --gemfile someapp/Gemfile --no-dep-run --gem-full --chdir-first -- server
 
-Note the space between "--" and "server"! It's important; "server" is
+Note the space between `--` and `server`! It's important; `server` is
 an argument to be passed to rails when the script is ran.
 
 Rails 2 apps can be packaged similarly, though you will have to
 integrate them with Bundler (http://gembundler.com/rails23.html)
 first.
 
-=== Gem handling
+### Gem handling
 
 By default, Ocra includes all scripts that are loaded by your script
 when it is run before packaging. Ocra detects which gems are using and
@@ -273,17 +272,17 @@ tests, specs, etc.
 This behaviour can be changed by using the --gem-* options. There are
 four possible modes:
 
-  minimal: Include only loaded scripts
-  guess: Include loaded scripts and important files (DEFAULT)
-  all: Include all scripts and important files
-  full: Include all files
+* *minimal*: Include only loaded scripts
+* *guess*: Include loaded scripts and important files (DEFAULT)
+* *all*: Include all scripts and important files
+* *full*: Include all files
 
 If you find that files are missing from the resulting executable, try
 first with --gem-all=gemname for the gem that is missing, and if that
 does not work, try --gem-full=gemname. The paranoid can use --gem-full
 to include all files for all required gems.
 
-=== Creating an installer for your application
+### Creating an installer for your application
 
 To make your application start up quicker, or to allow it to
 keep files in its application directory between runs, or if
@@ -294,12 +293,12 @@ for your app with the free Inno Setup software.
 You will first have to download and install Inno Setup 5 or
 later, and also add its directory to your PATH (so that Ocra
 can find the ISCC compiler program). Once you've done that,
-you can use the --innosetup option to Ocra to supply an
+you can use the `--innosetup` option to Ocra to supply an
 Inno Setup script. Do not add any [Files] or [Dirs] sections
 to the script; Ocra will figure those out itself.
 
 To continue the Rails example above, let's package the Rails 3
-app into an installer. Save the following as "<tt>someapp.iss</tt>":
+app into an installer. Save the following as `someapp.iss`:
 
   [Setup]
   AppName=SomeApp
@@ -314,14 +313,14 @@ app into an installer. Save the following as "<tt>someapp.iss</tt>":
 
 Then, run Ocra with this command:
 
-  ocra someapp/script/rails someapp --output someapp.exe --add-all-core \
-  --gemfile someapp/Gemfile --no-dep-run --gem-full --chdir-first --no-lzma \
-  --innosetup someapp.iss -- server
+    ocra someapp/script/rails someapp --output someapp.exe --add-all-core \
+    --gemfile someapp/Gemfile --no-dep-run --gem-full --chdir-first --no-lzma \
+    --innosetup someapp.iss -- server
 
 If all goes well, a file named "SomeAppInstaller.exe" will be placed
 into the Output directory.
 
-=== Environment variables
+### Environment variables
 
 OCRA executables clear the RUBYLIB environment variable before your
 script is launched. This is done to ensure that your script does not
@@ -335,69 +334,67 @@ executables.
 OCRA executables set OCRA_EXECUTABLE to the full path of the
 executable, for example
 
-  ENV["OCRA_EXECUTABLE"] # => C:\Program Files\MyApp\MyApp.exe
+    ENV["OCRA_EXECUTABLE"] # => C:\Program Files\MyApp\MyApp.exe
 
-=== Working directory
+### Working directory
 
 The OCRA executable does not change the working directory when it is
-launched, unless you use the "<tt>--chdir-first</tt>" option.
+launched, unless you use the `--chdir-first` option.
 
 You should not assume that the current working directory when invoking
 an executable built with .exe is the location of the source script. It
 can be the directory where the executable is placed (when invoked
 through the Windows Explorer), the users' current working directory
 (when invoking from the Command Prompt), or even
-<tt>C:\\WINDOWS\\SYSTEM32</tt> when the executable is invoked through
+`C:\\WINDOWS\\SYSTEM32` when the executable is invoked through
 a file association.
 
-With the "<tt>--chdir-first</tt>" option, the working directory will
+With the `--chdir-first` option, the working directory will
 always be the common parent directory of your source files. This
 should be fine for most applications. However, if your application
 is designed to run from the command line and take filenames as
 arguments, then you cannot use this option.
 
 If you wish to maintain the user's working directory, but need to
-'require' additional Ruby scripts from the source directory, you can
+`require` additional Ruby scripts from the source directory, you can
 add the following line to your script:
 
-  $LOAD_PATH.unshift File.dirname($0)
+    $LOAD_PATH.unshift File.dirname($0)
 
-=== Load path mangling
+### Load path mangling
 
-Adding paths to <tt>$LOAD_PATH</tt> or <tt>$:</tt> at runtime is not
+Adding paths to `$LOAD_PATH` or `$:` at runtime is not
 recommended. Adding relative load paths depends on the working
 directory being the same as where the script is located (See
 above). If you have additional library files in directories below the
 directory containing your source script you can use this idiom:
 
-  $LOAD_PATH.unshift File.join(File.dirname($0), 'path/to/script')
+    $LOAD_PATH.unshift File.join(File.dirname($0), 'path/to/script')
 
-=== Detecting OCRA
+### Detecting
 
 You can detect whether OCRA is currently building your script by
 looking for the 'Ocra' constant. If it is defined, OCRA is currenly
 building the executable from your script. For example, you can use
 this to avoid opening a GUI window when compiling executables:
 
-  app = MyApp.new
-  if not defined?(Ocra)
-    app.main_loop
-  end
+    app = MyApp.new
+    app.main_loop unless defined?(Ocra)
 
-=== Additional files and resources
+### Additional files and resources
 
 You can add additional files to the OCRA executable (for example
 images) by appending them to the command line. They should be placed
 in the source directory with your main script (or a subdirectory).
 
-  ocra mainscript.rb someimage.jpeg docs/document.txt
+    ocra mainscript.rb someimage.jpeg docs/document.txt
 
 This will create the following layout in the temporary directory when
 your program is executed:
 
-  src/mainscript.rb
-  src/someimage.jpeg
-  src/docs/document.txt
+    src/mainscript.rb
+    src/someimage.jpeg
+    src/docs/document.txt
 
 Both files, directoriess and glob patterns can be specified on the
 command line. Files will be added as-is. If a directory is specified,
@@ -405,22 +402,22 @@ OCRA will include all files found below that directory. Glob patterns
 (See Dir.glob) can be used to specify a specific set of files, for
 example:
 
-  ocra script.rb assets/**/*.png
+    ocra script.rb assets/**/*.png
 
-=== Command Line Arguments
+### Command Line Arguments
 
 To pass command line argument to your script (both while building and
 when run from the resulting executable), specify them after a
-"<tt>--</tt>" marker. For example:
+`--` marker. For example:
 
-  ocra script.rb -- --some-options=value
+    ocra script.rb -- --some-options=value
 
-This will pass "<tt>--some-options=value</tt>" to the script when
+This will pass `--some-options=value` to the script when
 build and when running the executable. Any extra argument specified by
 the user when invoking the executable will be appended after the
 compile-time arguments.
 
-=== Window/Console
+### Window/Console
 
 By default, OCRA builds console application from .rb-files and
 windowed applications (without console window) from .rbw-files.
@@ -428,10 +425,10 @@ windowed applications (without console window) from .rbw-files.
 Ruby on Windows provides two executables: ruby.exe is a console mode
 application and rubyw.exe is a windowed application which does not
 bring up a console window when launched using the Windows Explorer.
-By default, or if the "<tt>--console</tt>" option is used, OCRA will
+By default, or if the `--console` option is used, OCRA will
 use the console runtime (ruby.exe). OCRA will automatically select the
 windowed runtime when your script has the ".rbw" extension, or if you
-specify the "<tt>--windows</tt>" command line option.
+specify the `--windows` command line option.
 
 If your application works in console mode but not in windowed mode,
 first check if your script works without OCRA using rubyw.exe. A
@@ -442,16 +439,16 @@ buffers run full).
 You can also try wrapping your script in an exception handler that
 logs any errors to a file:
 
-  begin
-    # your script here
-  rescue Exception => e
-    File.open("except.log") do |f|
-      f.puts e.inspect
-      f.puts e.backtrace
+    begin
+      # your script here
+    rescue Exception => e
+      File.open("except.log") do |f|
+        f.puts e.inspect
+        f.puts e.backtrace
+      end
     end
-  end
 
-== CREDITS:
+## CREDITS:
 
 Thanks for Igor Pavlov for the LZMA compressor and decompressor. The
 source code used was place into Public Domain by Igor Pavlov.
@@ -461,11 +458,11 @@ Erik Veenstra for rubyscript2exe which provided inspiration.
 Dice for the default .exe icon (vit-ruby.ico,
 http://ruby.morphball.net/vit-ruby-ico_en.html)
 
-== LICENSE:
+## LICENSE:
 
 (The MIT License)
 
-Copyright (c) 2009-2010 Lars Christensen
+Copyright (c) 2009-2020 Lars Christensen
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the
diff --git a/Rakefile b/Rakefile
index ddf4a9a5..da237766 100644
--- a/Rakefile
+++ b/Rakefile
@@ -1,66 +1,66 @@
 # -*- ruby -*-
 
-require 'rubygems'
-require 'hoe'
+require "rubygems"
+require "hoe"
 
 Hoe.plugin :minitest
 
-spec = Hoe.spec 'ocra' do
+spec = Hoe.spec "ocra" do
   developer "Lars Christensen", "larsch@belunktum.dk"
   license "MIT"
 end
 
-spec.urls.each { |url| url.chomp! }
+spec.urls.each { |key, url| url.chomp! }
 
 task :build_stub do
   sh "mingw32-make -C src"
-  cp 'src/stub.exe', 'share/ocra/stub.exe'
-  cp 'src/stubw.exe', 'share/ocra/stubw.exe'
-  cp 'src/edicon.exe', 'share/ocra/edicon.exe'
+  cp "src/stub.exe", "share/ocra/stub.exe"
+  cp "src/stubw.exe", "share/ocra/stubw.exe"
+  cp "src/edicon.exe", "share/ocra/edicon.exe"
 end
 
-file 'share/ocra/stub.exe' => :build_stub
-file 'share/ocra/stubw.exe' => :build_stub
-file 'share/ocra/edicon.exe' => :build_stub
+file "share/ocra/stub.exe" => :build_stub
+file "share/ocra/stubw.exe" => :build_stub
+file "share/ocra/edicon.exe" => :build_stub
 
 task :test => :build_stub
 
-task :standalone => [ 'bin/ocrasa.rb' ]
+task :standalone => ["bin/ocrasa.rb"]
 
-standalone_zip = "bin/ocrasa-#{ENV['VERSION']}.zip"
+standalone_zip = "bin/ocrasa-#{ENV["VERSION"]}.zip"
 
-file standalone_zip => 'bin/ocrasa.rb' do
-  chdir 'bin' do
-    sh "zip", "ocrasa-#{ENV['VERSION']}.zip", "ocrasa.rb"
+file standalone_zip => "bin/ocrasa.rb" do
+  chdir "bin" do
+    sh "zip", "ocrasa-#{ENV["VERSION"]}.zip", "ocrasa.rb"
   end
 end
 
 task :release_standalone => standalone_zip do
-  load 'bin/ocra'
+  load "bin/ocra"
   sh "rubyforge add_release ocra ocra-standalone #{Ocra::VERSION} #{standalone_zip}"
 end
 
-file 'bin/ocrasa.rb' => [ 'bin/ocra', 'share/ocra/stub.exe', 'share/ocra/stubw.exe', 'share/ocra/lzma.exe', 'share/ocra/edicon.exe' ] do
-  cp 'bin/ocra', 'bin/ocrasa.rb'
+file "bin/ocrasa.rb" => ["bin/ocra", "share/ocra/stub.exe", "share/ocra/stubw.exe", "share/ocra/lzma.exe", "share/ocra/edicon.exe"] do
+  cp "bin/ocra", "bin/ocrasa.rb"
   File.open("bin/ocrasa.rb", "a") do |f|
     f.puts "__END__"
 
-    stub = File.open("share/ocra/stub.exe", "rb") {|g| g.read}
+    stub = File.open("share/ocra/stub.exe", "rb") { |g| g.read }
     stub64 = [stub].pack("m")
     f.puts stub64.size
     f.puts stub64
 
-    stub = File.open("share/ocra/stubw.exe", "rb") {|g| g.read}
+    stub = File.open("share/ocra/stubw.exe", "rb") { |g| g.read }
     stub64 = [stub].pack("m")
     f.puts stub64.size
     f.puts stub64
 
-    lzma = File.open("share/ocra/lzma.exe", "rb") {|g| g.read}
+    lzma = File.open("share/ocra/lzma.exe", "rb") { |g| g.read }
     lzma64 = [lzma].pack("m")
     f.puts lzma64.size
     f.puts lzma64
 
-    lzma = File.open("share/ocra/edicon.exe", "rb") {|g| g.read}
+    lzma = File.open("share/ocra/edicon.exe", "rb") { |g| g.read }
     lzma64 = [lzma].pack("m")
     f.puts lzma64.size
     f.puts lzma64
@@ -74,14 +74,13 @@ task :clean do
 end
 
 task :test_standalone => :standalone do
-  ENV['TESTED_OCRA'] = 'ocrasa.rb'
+  ENV["TESTED_OCRA"] = "ocrasa.rb"
   system("rake test")
-  ENV['TESTED_OCRA'] = nil
+  ENV["TESTED_OCRA"] = nil
 end
 
 task :release_docs => :redocs do
   sh "pscp -r doc/* larsch@ocra.rubyforge.org:/var/www/gforge-projects/ocra"
 end
 
-
 # vim: syntax=Ruby