Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

Converted README to Markdown #1007

Closed
wants to merge 3 commits into from

4 participants

@rodrigoflores

I've converted the README to Markdown.

Rodrigo Flores added some commits
@brixen
Owner

Yes, 'most recent' is correct.

Could you explain why you think this is a good change?

I have rejected converting the README to Markdown before for these reasons:

  1. The rendering of the Markdown on Github actually makes this much harder to read. The headings are huge but the text is rendered very small and trails across the page making it much more difficult to read.
  2. Even if the rendering on Github were superb, READMEs are text files that should give core information for someone browsing the source code. This change makes the text even harder to read with '## Foo ##' a lot uglier than a simple '1. Foo'
  3. Github already renders links clickable in plain text files and we have much more extensive docs available on http://rubini.us and already in the repository that someone can access with a simple 'rake docs' command.
  4. The README needs to be cleaned up and about 30% of the information removed. The remaining content is very easy to read in plain text format.

I am very much opposed to changing the format of the README.

@meh

I think markdown reads better when used properly, for example using

Title
=====

Subtitle
--------

Instead of # Stuff #

@brixen
Owner

@meh

We don't need any subtitles in the README. The use of heavy === underlining the few headings is unnecessary in text. We use Markdown in the docs because it's 500% better than trying to write docs embedded in HTML but it adds only complexity to a simple text file.

@rodrigoflores

@brixen

Thanks for your feedback. I've converted README to Markdown because of the superb (IMHO) visualization that @github provides. Almost every great project in Github includes a great README in Markdown, so I thought it should be a nice idea to Rubinius to have one.

An alternative: we may also provide a plain text version of the README (I don't know if Github will choose the Markdown version instead of the plain text version to show when someone opens, I have to check). It is not "DRY" but it provides a nice visualization on Github without removing the plain text README.

About the Recent x Updated: we currently have "Most current documentation". I agree that recent can be better than updated, but I don't like "most current".

@brixen
Owner

@rodrigoflores

Thanks for the additional explanation. The part of the README with RVM information needs to be reworked. We don't need to duplicate the RVM information. One step to install the current version and a link to RVM should be all that is included. Then the text could be something like "See the RVM documentation."

I'm really curious why you think Github renders the Markdown better than plain text. I could skitch the two side-by-side and show how the Markdown rendering straggles across the screen with short and long text lines interspersed providing a very poor reading experience. The Github rendering is just terrible for readability.

@brixen
Owner

This is a rendering of the Markdown format:
https://skitch.com/brixen/frk4k/rodrigoflores-rubinius-github

This is a rendering of the plain text. As the notes point out, there is nothing the Markdown format gives other than a needless horizontal rule and big heading text.
https://skitch.com/brixen/frk4p/rubinius-rubinius-github

@rodrigoflores

@brixen

Another doubt: Can we at least change most current to "most updated" or "most recent" ?

@brixen brixen was assigned
@brixen
Owner

I've simplified the README quit a bit. There are lots of places that the built-in documentation could be improved for folks getting started with Rubinius. I'd like to focus efforts there.

@brixen brixen closed this
@jc00ke
Owner
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Commits on Jun 11, 2011
  1. Moved README to Markdown

    Rodrigo Flores authored
  2. Updated is better than documentation

    Rodrigo Flores authored
  3. Minor changes on README syntax

    Rodrigo Flores authored
This page is out of date. Refresh to see the latest.
Showing with 86 additions and 115 deletions.
  1. +0 −115 README
  2. +86 −0 README.mdown
View
115 README
@@ -1,115 +0,0 @@
-1. What is Rubinius
-
-Rubinius is an implementation of the Ruby programming language. Rubinius
-includes a bytecode virtual machine, parser, bytecode compiler, garbage
-collector, JIT native machine code compiler, and Ruby core and standard
-libraries.
-
-Rubinius currently is compatible with Ruby version 1.8.7. Support for Ruby
-version 1.9.2 is coming soon.
-
-
-2. License
-
-Rubinius uses the BSD license. See LICENSE for details.
-
-
-3. Installing Rubinius
-
-Rubinius runs on Mac OS X and many Unix/Linux operating systems. Support for
-Microsoft Windows is coming soon.
-
-For more information about building and running Rubinius, run 'rake docs'.
-
-To install Rubinius, use the following steps:
-
- 1. Ensure you have MRI 1.8.7+, rubygems, rake, and git installed
- 2. git clone git://github.com/rubinius/rubinius.git
- 3. cd rubinius
- 4. ./configure --prefix=/path/to/install/dir
- 5. rake install
-
-When the install process finishes, follow the directions to add the Rubinius
-executable (bin) directory to your PATH.
-
-Rubinius comes with RubyGems built-in. To install a gem, run the following:
-
- rbx gem install <gem_name>
-
-After installing Rubinius, you can access the built-in documentation at any
-time by running 'rbx docs'.
-
-3.1 Rubinius with RVM
-
-You may wish to use the Ruby enVironment Manager (RVM) project to install
-Rubinius. For the most current documentation for RVM, please visit
-https://rvm.beginrescueend.com.
-
-Be sure that RVM has been installed properly and is loaded as a function as is
-explained in detail on the basics page, https://rvm.beginrescueend.com/rvm/basics/
-
-Assuming all Rubinius dependencies have been preinstalled on the system, you may
-now install Rubinius either latest or head as follows,
-
- rvm install rbx # Installs latest release (defaulted to install head)
- rvm install rbx-head # Installs Rubinius master branch from github
-
-Once installed,
-
- rvm use rbx # Selects Rubinius into the current shell session.
-
-If you wish to make Rubinius the default interpreter when you open new shells,
-
- rvm use rbx --default
-
-In order to view the dependency list to preinstall for rbx type
-
- rvm notes
-
-For more information on working with rvm please visit the RVM website,
-
- https://rvm.beginrescueend.com/
-
-4. Version 1.1
-
-Rubinius has been under development as a public open-source project since
-November 2006. Rubinius development is sponsored by Engine Yard, Inc. and
-assisted by the generous work of over 100 contributors.
-
-At version 1.1, Rubinius is significantly feature-complete. It is expected
-that your Ruby code will run correctly. Additionally, many MRI C extensions
-are expected to work, as long as they do not depend on MRI-specific object
-internals or the MRI interpreter internals.
-
-With the JIT, Rubinius performance is quite good, sometimes faster than MRI
-and sometimes slower. Rubinius generally executes Ruby code very fast as
-compared to MRI. However, since the majority of the Ruby core library is also
-implemented in Ruby rather than C as it is in MRI, code that depends heavily
-on Array, Hash, String, etc. may run slower in Rubinius right now. As the JIT
-improves, overall performance of your code under Rubinius will improve.
-
-
-5. Goals
-
-* Thread safety. Rubinius intends to be thread-safe so you could embed more
- than one interpreter in a single application.
-
-* Clean, readable code that is easy for users to understand and extend.
-
-* Reliable, rock-solid code. Valgrind is used to help verify correctness.
-
-* Bring modern research in virtual machines, garbage collectors, and compilers
- to the Ruby programming language.
-
-
-6. Tickets
-
-Please file tickets for bugs or problems that you encounter. The issue tracker
-is: http://github.com/rubinius/rubinius/issues. Run 'rake docs' for more
-details.
-
-
-7. Contributing
-
-The Rubinius team welcomes contributions. Run 'rake docs' and see the
-"Contributing" page.
View
86 README.mdown
@@ -0,0 +1,86 @@
+# What is Rubinius #
+
+Rubinius is an implementation of the Ruby programming language. Rubinius includes a bytecode virtual machine, parser, bytecode compiler, garbage collector, JIT native machine code compiler, and Ruby core and standard libraries.
+
+Rubinius currently is compatible with Ruby version 1.8.7. Support for Ruby version 1.9.2 is coming soon.
+
+
+# License #
+
+Rubinius uses the BSD license. See LICENSE for details.
+
+
+# Installing Rubinius #
+
+Rubinius runs on Mac OS X and many Unix/Linux operating systems. Support for Microsoft Windows is coming soon.
+
+For more information about building and running Rubinius, run 'rake docs'.
+
+To install Rubinius, use the following steps, and ensure you have MRI 1.8.7+, rubygems, rake, and git installed
+
+ git clone git://github.com/rubinius/rubinius.git
+ cd rubinius
+ ./configure --prefix=/path/to/install/dir
+ rake install
+
+When the install process finishes, follow the directions to add the Rubinius executable (bin) directory to your PATH.
+
+Rubinius comes with RubyGems built-in. To install a gem, run the following:
+
+ rbx gem install <gem_name>
+
+After installing Rubinius, you can access the built-in documentation at any time by running `rbx docs`.
+
+## Rubinius with RVM ##
+
+You may wish to use the Ruby enVironment Manager (RVM) project to install Rubinius. For the most updated documentation for RVM, please visit [RVM website](https://rvm.beginrescueend.com).
+
+Be sure that RVM has been installed properly and is loaded as a function as is explained in detail on the [basics page](https://rvm.beginrescueend.com/rvm/basics/).
+
+Assuming all Rubinius dependencies have been preinstalled on the system, you may now install Rubinius either latest or head as follows,
+
+ rvm install rbx # Installs latest release (defaulted to install head)
+ rvm install rbx-head # Installs Rubinius master branch from github
+
+Once installed,
+
+ rvm use rbx # Selects Rubinius into the current shell session.
+
+If you wish to make Rubinius the default interpreter when you open new shells,
+
+ rvm use rbx --default
+
+In order to view the dependency list to preinstall for rbx type
+
+ rvm notes
+
+For more information on working with rvm please visit the [RVM website](https://rvm.beginrescueend.com/)
+
+# Version 1.1 #
+
+Rubinius has been under development as a public open-source project since November 2006. Rubinius development is sponsored by Engine Yard, Inc. and assisted by the generous work of over 100 contributors.
+
+At version 1.1, Rubinius is significantly feature-complete. It is expected that your Ruby code will run correctly. Additionally, many MRI C extensions are expected to work, as long as they do not depend on MRI-specific object internals or the MRI interpreter internals.
+
+With the JIT, Rubinius performance is quite good, sometimes faster than MRI and sometimes slower. Rubinius generally executes Ruby code very fast as compared to MRI. However, since the majority of the Ruby core library is also implemented in Ruby rather than C as it is in MRI, code that depends heavily on Array, Hash, String, etc. may run slower in Rubinius right now. As the JIT improves, overall performance of your code under Rubinius will improve.
+
+
+# Goals #
+
+* Thread safety. Rubinius intends to be thread-safe so you could embed more than one interpreter in a single application.
+
+* Clean, readable code that is easy for users to understand and extend.
+
+* Reliable, rock-solid code. Valgrind is used to help verify correctness.
+
+* Bring modern research in virtual machines, garbage collectors, and compilers to the Ruby programming language.
+
+
+# Tickets #
+
+Please file tickets for bugs or problems that you encounter. The issue tracker is: http://github.com/rubinius/rubinius/issues. Run `rake docs` for more details.
+
+
+# Contributing #
+
+The Rubinius team welcomes contributions. Run 'rake docs' and see the "Contributing" page.
Something went wrong with that request. Please try again.