[GR-20548] Link titles improvements to render properly at graalvm.org.

PullRequest: truffleruby/1263

Author: eregon

doc/user/compatibility.md

@@ -36,7 +36,7 @@ Additionally, TruffleRuby defines:
 
 In the C API, we define a preprocessor macro `TRUFFLERUBY`.
 
-## Features entirely missing
+## Features Entirely Missing
 
 #### Continuations and `callcc`
 
@@ -87,7 +87,7 @@ more explanation on this.
 
 `RubyVM` is not intended for users and is not implemented.
 
-## Features with major differences
+## Features with Major Differences
 
 #### Threads run in parallel
 
@@ -121,7 +121,7 @@ MRI provides some classes that are described in the documentation as being only
 available on MRI (C Ruby). We implement these classes if it's practical to do
 so, but this isn't always the case. For example `RubyVM` is not available.
 
-## Features with subtle differences
+## Features with Subtle Differences
 
 #### Command line switches
 
@@ -202,7 +202,7 @@ signals are also unavailable on MRI.
 When TruffleRuby is run as part of a polyglot application, any signals that are
 handled by another language become unavailable for TruffleRuby to trap.
 
-## Features with very low performance
+## Features with Very Low Performance
 
 #### `ObjectSpace`
 
@@ -285,7 +285,7 @@ not clear if this will ever be a priority.
 We do not have any plans at the moment to provide support for Rubinius'
 extensions to Ruby.
 
-## Features not yet supported in native configuration
+## Features Not Yet Supported in Native Configuration
 
 Running TruffleRuby in the native configuration is mostly the same as running
 on the JVM. There are differences in resource management, as both VMs use

doc/user/deploying.md

@@ -4,7 +4,7 @@ If you're attempting to experiment with deploying TruffleRuby to production we'd
 encourage you to contact us so we can help you understand what is possible at
 the moment and to help solve any issues for you.
 
-## TruffleRuby configurations
+## TruffleRuby Configurations
 
 There are two main configurations of TruffleRuby - *native* and *JVM*. It's
 important to understand the different configurations of TruffleRuby, as each has
@@ -35,20 +35,20 @@ If you are running a short-running program you probably want the default,
 highest possible performance you probably want the *JVM* configuration, by using
 `--jvm`.
 
-## Getting the best startup time performance
+### Getting the best startup time performance
 
 To get the best startup time performance in most cases you want to use the
 native configuration, which is the default.
 
-## Getting the lowest memory footprint
+### Getting the lowest memory footprint
 
 To get the lowest memory footprint you probably initially want to use the native
 configuration, but as you get a larger working set of objects you may find that
 the simpler garbage collector and current lack of compressed ordinary object
 pointers (OOPS) actually increases your memory footprint and you'll be better
 off with the JVM configuration using `--jvm` to reduce memory use.
 
-## Getting the best peak performance from TruffleRuby
+### Getting the best peak performance from TruffleRuby
 
 To get the best peak performance from TruffleRuby for longer-running
 applications we would in most cases recommend the JVM configuration with

doc/user/installing-graalvm.md

@@ -19,7 +19,7 @@ x86 64-bit systems (note that TruffleRuby does not support Windows yet).
 
 To get the best performance you want to use the Enterprise Edition.
 
-## Installing the base image
+## Installing the Base Image
 
 GraalVM starts with a base image which provides the platform for
 high-performance language runtimes.
@@ -38,7 +38,7 @@ Whichever edition you get you will get a tarball which you can extract. There
 will be a `bin` directory (`Contents/Home/bin` on macOS) which you can add to
 your `$PATH` if you want to.
 
-## Installing Ruby and other languages
+## Installing Ruby and Other Languages
 
 After installing GraalVM you then need to install the Ruby language into it.
 This is done using the `gu` command. The Ruby package is the same for both
@@ -74,7 +74,7 @@ haven't done so already:
 gu install native-image
 ```
 
-## Using a Ruby package manager
+## Using a Ruby Manager
 
 Inside the GraalVM is a `jre/languages/ruby` or `languages/ruby` directory which
 has the usual structure of a Ruby implementation. It is recommended to add this

doc/user/installing-libssl.md

@@ -8,31 +8,31 @@ If you experience `openssl`-related errors, it might help to recompile the
 This is done automatically by Ruby managers, and mentioned in the post-install
 message when installing TruffleRuby via `gu install` in GraalVM.
 
-## RedHat-based: Fedora, Oracle Linux, etc
+### RedHat-based: Fedora, Oracle Linux, etc
 
 ```bash
 $ sudo dnf install openssl-devel
 ```
 
-## Debian-based: Ubuntu, etc
+### Debian-based: Ubuntu, etc
 
 ```bash
 $ sudo apt-get install libssl-dev
 ```
 
-## macOS
+### macOS
 
 On macOS the system version is too old.
 
-### Homebrew
+#### Homebrew
 
 We recommend installing libssl via [Homebrew](https://brew.sh).
 
 ```bash
 $ brew install openssl
 ```
 
-### MacPorts
+#### MacPorts
 
 MacPorts should also work but is not actively tested.
 

doc/user/installing-llvm.md

@@ -6,19 +6,19 @@ version, see [the documentation for that version](https://github.com/oracle/truf
 
 The `make` utility as well as the dependencies of the toolchain still need to be available to build C and C++ extensions.
 
-## RedHat-based: Fedora, Oracle Linux, etc
+### RedHat-based: Fedora, Oracle Linux, etc
 
 ```bash
 $ sudo dnf install make gcc
 ```
 
-## Debian-based: Ubuntu, etc
+### Debian-based: Ubuntu, etc
 
 ```bash
 $ sudo apt-get install make gcc
 ```
 
-## macOS
+### macOS
 
 On macOS, make sure you have installed the command line developer tools from Xcode:
 

doc/user/installing-zlib.md

@@ -3,18 +3,18 @@
 TruffleRuby provides the `zlib` module but not the native `zlib` system
 library that the module uses.
 
-## RedHat-based: Fedora, Oracle Linux, etc
+### RedHat-based: Fedora, Oracle Linux, etc
 
 ```bash
 $ sudo dnf install zlib-devel
 ```
 
-## Debian-based: Ubuntu, etc
+### Debian-based: Ubuntu, etc
 
 ```bash
 $ sudo apt-get install libz-dev
 ```
 
-## macOS
+### macOS
 
 On macOS the system version can be used.

doc/user/jruby-migration.md

@@ -513,7 +513,7 @@ Java classes cannot be re-opened in TruffleRuby.
 Java classes cannot be subclassed in TruffleRuby. Use composition or interfaces
 instead.
 
-## Extending TruffleRuby using Java
+## Extending TruffleRuby Using Java
 
 JRuby supports extensions written in Java. These extensions are written against
 an informal interface that is simply the entire internals of JRuby, similar to

doc/user/options.md

@@ -46,7 +46,7 @@ Features:
 TruffleRuby also reads the `RUBYOPT` environment variable, as in standard
 Ruby, if run from the Ruby launcher.
 
-## Unlisted Ruby switches
+## Unlisted Ruby Switches
 
 MRI has some extra Ruby switches which are aren't normally listed in help output
 but are documented in the Ruby manual page.
@@ -59,7 +59,7 @@ but are documented in the Ruby manual page.
                   the same as --external-encoding=external and optionally --internal-encoding=internal
 ```
 
-## TruffleRuby options
+## TruffleRuby Options
 
 TruffleRuby options are set via `--option=value`, or you can use
 `--ruby.option=value` from any launcher. You can omit `=value` to set to `true`.
@@ -83,7 +83,7 @@ run from the Ruby launcher.
 `--` or the first non-option argument stops processing of TrufflRuby and VM
 options in the same way it stops processing of Ruby arguments.
 
-## VM options
+## VM Options
 
 To set options in the underlying VM, use `--vm.`, valid for both the native
 configuration and the JVM configuration.
@@ -93,12 +93,12 @@ For example `--vm.Dsystem_property=value` or `--vm.ea`.
 To set the classpath, use the `=` notation, rather than two separate arguments.
 For example `--vm.cp=lib.jar` or `--vm.classpath=lib.jar`.
 
-## Other binary switches
+## Other Binary Switches
 
 Other binaries, such as `irb`, `gem`, and so on, support exactly the same
 switches as in standard Ruby.
 
-## Determining the TruffleRuby home
+## Determining the TruffleRuby Home
 
 TruffleRuby needs to know where to locate files such as the standard library.
 These are stored in the TruffleRuby home directory.

doc/user/polyglot.md

@@ -23,7 +23,7 @@ access to other languages.
 * [Threading and interop](#threading-and-interop)
 * [Embedded configuration](#embedded-configuration)
 
-## Running Ruby code from another language
+## Running Ruby Code from Another Language
 
 When you `eval` Ruby code from the [Context API](https://www.graalvm.org/sdk/javadoc/org/graalvm/polyglot/Context.html)
 in another language and mark the `Source` as interactive, the same interactive
@@ -34,7 +34,7 @@ The semantics are the same as the Ruby semantics of calling
 `INTERACTIVE_BINDING.eval(code)` for every `Context.eval()` call with an
 interactive `Source`. This is similar to most REPL semantics.
 
-## Loading code written in foreign languages
+## Loading Code Written in Foreign Languages
 
 `Polyglot.eval(id, string)` executes code in a foreign language identified by
 its ID.
@@ -45,21 +45,21 @@ identified by its language ID.
 `Polyglot.eval_file(path)` executes code in a foreign language from a file,
 automatically determining the language.
 
-## Exporting Ruby objects to foreign languages
+## Exporting Ruby Objects to Foreign Languages
 
 `Polyglot.export(name, value)` exports a value with a given name.
 
 `Polyglot.export_method(name)` exports a method, defined in the top-level
 object.
 
-## Importing foreign objects to Ruby
+## Importing Foreign Objects to Ruby
 
 `Polyglot.import(name)` imports and returns a value with a given name.
 
 `Polyglot.import_method(name)` imports a value, which should be `IS_EXECUTABLE`,
 with a given name, and defines it in the top-level object.
 
-## Using Ruby objects from a foreign language
+## Using Ruby Objects from a Foreign Language
 
 Using JavaScript as an example - the left example is JavaScript, the right one
 is the corresponding action it takes on the Ruby object expressed in Ruby code.
@@ -100,7 +100,7 @@ written, a good object to pass is usually a `Struct`, as this will have both the
 they will also respond to `object['foo']` and `object['foo'] = value` which
 means they will work from other languages sending read and write messages.
 
-## Using foreign objects from Ruby
+## Using Foreign Objects from Ruby
 
 `object[name/index]` will read a member from the foreign object.
 
@@ -144,7 +144,7 @@ foreign object, using its size or length and reading from it.
 Where boolean value is expected (e.g. in if conditions) the foreign value is
 converted to boolean if possible or considered to be true.
 
-## Accessing Java objects
+## Accessing Java Objects
 
 TruffleRuby's Java interop interface is similar to the interface from the
 Nashorn JavaScript implementation, as also implemented by Graal.js.
@@ -182,14 +182,14 @@ class Embedding {
 }
 ```
 
-## Using Ruby objects from embedding Java
+## Using Ruby Objects from Embedding Java
 
 Ruby objects are represented by the `Value` class when embedded in Java.
 
 ### Accessing arrays
 
 ```java
-boolean hasArrayElements() 
+boolean hasArrayElements()
 Value getArrayElement(long index)
 void setArrayElement(long index, Object value)
 boolean removeArrayElement(long index)
@@ -210,8 +210,8 @@ boolean removeMember(String identifier)
 ### Executing procs, lambdas, and methods
 
 ```java
-boolean canExecute() 
-Value execute(Object... arguments) 
+boolean canExecute()
+Value execute(Object... arguments)
 void executeVoid(Object... arguments)
 ```
 
@@ -221,7 +221,7 @@ void executeVoid(Object... arguments)
 boolean canInstantiate() {
 Value newInstance(Object... arguments)
 ```
-      
+
 ### Accessing primitives
 
 ```java
@@ -253,7 +253,7 @@ Ruby strings and symbols are converted to Java strings when they are passed to
 foreign languages, and Java strings are converted to Ruby strings when they
 are passed into Ruby.
 
-## Threading and interop
+## Threading and Interop
 
 Ruby is designed to be a multi-threaded language and much of the ecosystem
 expects threads to be available. This may be incompatible with other Truffle

doc/user/reporting-performance-problems.md

@@ -25,7 +25,7 @@ show them so it may be a new problem to some people in the Ruby community.
 To experiment with how fast TruffleRuby can be we recommend using the
 [Enterprise Edition of GraalVM and rebuilding the Ruby executable images](installing-graalvm.md).
 
-## Using the JVM configuration
+## Using the JVM Configuration
 
 For the best peak performance, you want to use the JVM configuration, using
 `--jvm`. The default native configuration starts faster but doesn't quite reach
@@ -36,7 +36,7 @@ benchmark. If you want to write simpler benchmarks that just run a while loop
 with a simple timer (which we would not recommend anyway), then use the default
 native mode so that startup and warmup time is shorter.
 
-## How to check for basic performance problems
+## How to Check for Basic Performance Problems
 
 If you are examining the performance of TruffleRuby, we would recommend that you
 always run with the `--engine.TraceCompilation` flag. If you see
@@ -45,7 +45,7 @@ indicator that something is not working as intended and you may need to examine
 why, or ask us to help you do so. If you don't run with this flag Truffle will
 try to work around errors and you will not see that there is a problem.
 
-## How to write a performance benchmark
+## How to Write a Performance Benchmark
 
 We recommend that you use
 [`benchmark-ips`](https://github.com/evanphx/benchmark-ips), by Evan Phoenix, to