ron 0.1

data/man/ron.1.ron

@@ -0,0 +1,136 @@
+ron(1) -- the opposite of roff
+==============================
+
+## SYNOPSIS
+
+`ron` [ _OPTIONS_ ]  
+`ron` --build _FILE_ ...  
+`ron` --install _FILE_ ...  
+`ron` --man _FILE_
+
+## DESCRIPTION
+
+`Ron` is a humane text format and toolchain for authoring man pages
+(and things that appear as man pages from a distance). Use it to build
+and install standard UNIX / roff(7) formatted man pages and to
+generate nicely formatted HTML manual pages.
+
+The `ron` command converts one or more named input <em>FILE</em>s
+(or standard input when no files are named or the file name `-`
+is given) from humane man page markup to one or more destination
+output formats. If no output format is selected explicitly, `ron`
+writes output in roff format.
+
+## FILES
+
+The `ron` command expects input to be formatted as ron(5) text.
+Source files are typically named '_name_._section_.ron' (e.g.,
+`hello.1.ron`). The _name_ and _section_ should match the name
+and section defined in _FILE_'s heading.
+
+When building roff and/or HTML output files with the `--build`
+argument, destination filenames are determined by taking the basename
+of the input _FILE_ and adding the appropriate file extension (or
+removing the file extension in the case of roff output).
+
+For example, the command `ron -b --html --roff hello.1.ron` would
+generate a `hello.1` file with roff output and a `hello.1.html` file
+with HTML output.
+
+## OPTIONS
+
+`Ron`'s default mode of operation is to read a single document from
+standard input and to write the generated output to standard output.
+The following arguments change this behavior:
+
+  * `-b`, `--build`:
+    Write output directly to files instead of standard output. When
+    the `--roff` option is provided, writes roff output to
+    _file_._section_. When the `--html` option is provided, writes
+    output to '_file_._section_.html'.
+
+  * `-i`, `--install`:
+    Install the roff formatted man page to the local system such
+    that it can be displayed by man(1). The `MANHOME`
+    environment variable is used to determine the prefix where
+    man pages should be installed when defined.
+
+    If `MANHOME` is not defined, `ron` installs man pages to
+    _/usr/local/man_.
+
+  * `-m`, `--man`:
+    Display _FILE_ as if man(1) were invoked on the roff output
+    file. This simulates default man behavior by piping the roff
+    output through groff(1) and the paging program specified by the
+    `MANPAGER` environment variable.
+
+The following options control the output formats generated:
+
+  * `--html`:
+    Generate HTML output.
+
+  * `--roff`:
+    Generate roff output. This is the default behavior when no
+    other format argument is provided.
+
+## EXAMPLES
+
+Generate `roff(7)` output on stdout:
+
+    $ ron < hello.1.ron
+
+Build a roff file based on the input filename:
+
+    $ ron -b hello.1.ron
+    building: hello.1
+    $ man hello.1
+
+Build and open a standalone HTML file based on the input filename:
+
+    $ ron -b --html test.1.ron
+    $ open test.1.html
+
+Build roff and HTML versions of all `.ron` files in the current
+directory:
+
+    $ ron -b --roff --html *.ron
+    building: hello.1
+    building: hello.1.html
+    building: world.1
+    building: world.1.html
+
+View a ron file in the same way as man(1) without building a roff
+file:
+
+    $ ron -m hello.1.ron
+
+Install the roff man page for a ron file:
+
+    $ ron -i hello.1.ron
+
+## ENVIRONMENT
+
+  * `MANHOME`:
+    Location where roff formatted man pages should be installed.
+    Relevant only when the `--installed` argument is provided.
+    _PATH_ is to the base of a man file hierarchy. e.g.,
+    `/usr/local/share/man`, `/home/rtomayko/man`.
+
+  * `MANPAGER`:
+    The paging program used for man pages. This is typically set
+    to something like 'less -is'.
+
+  * `PAGER`:
+    Used instead of `MANPAGER` when `MANPAGER` is not defined.
+
+## BUGS
+
+Ron is written in Ruby.
+
+## COPYRIGHT
+
+`ron` is Copyright (C) 2009 Ryan Tomayko <tomayko.com/about>
+
+## SEE ALSO
+
+ron(5), markdown(5), manpages(5), man(1), roff(7), groff(1)

data/man/ron.5.ron

@@ -0,0 +1,150 @@
+ron(5) -- humane manual page authoring format
+=============================================
+
+## SYNOPSIS
+
+    name(1) -- one sentence description
+    ===================================
+
+    ## SECTION HEADING
+
+    A normal paragraph. This can span multiple lines and is
+    terminated with two or more line endings -- just like
+    Markdown.
+
+    ## INLINE MARKUP
+
+    Inline markup should be used for `code` (displayed in
+    boldface) and _variables_ (displayed in underline).
+
+    Manual page references like sh(1), markdown(5), roff(7), etc.
+    are displayed in boldface and hyperlinked in HTML output.
+
+    ## DEFINITION LISTS
+
+    Definition lists are used to define arguments, variables,
+    or other terms:
+
+      * `-a`, `--arg1`=[_OPTION_]:
+        One or more paragraphs describing the 
+      * `-b`, `--arg2`:
+        Any number of these may be specified and they can be
+        nested.
+
+## DESCRIPTION
+
+`Ron` files are simple ascii texts that document things in the
+style of UNIX man pages but with a syntax and feature-set less
+insane than that of roff(7). `Ron` files are piped through
+ron(1) to build and install traditional roff(7) man pages or
+to generate hyperlinked HTML documentation.
+
+All `ron` files must conform to a simple subset of markdown(5), a
+humane text markup designed for writing on the web. It is neither
+possible nor desirable to express many of roff(7)'s complex
+typesetting features in `ron`.
+
+## MANPAGE TITLE
+
+All man pages have a _name_, belong to a _section_, and have a
+single sentence _tagline_ (useless but witty, preferably). `Ron`
+files must begin with a first-level heading that includes all of
+this information. For example, this very man page begins:
+
+    ron(5) -- humane manual page authoring format
+    =============================================
+
+Here, we're saying that the man page documents a thing named `ron`
+in manual section `5` -- the "file formats" section; see
+manpages(5) for full section list -- and that's quickly
+described as a "humane manual page authoring format".
+
+These bits of information are used to fill in the document
+header, to create the `NAME` section, and also to establish
+output filenames when processed with ron(1).
+
+## SECTION HEADINGS
+
+Man section headings are expressed with markdown level two
+headings. markdown(5) provides two syntaxes for level two
+headings. A hash prefix syntax:
+
+    ## HEADING TEXT
+
+Or, a dash underline syntax:
+
+    HEADING TEXT
+    ------------
+
+Section headings should be in all uppercase and may not contain
+other inline markup.
+
+Most manual pages include at least one of the `SYNOPSIS`,
+`DESCRIPTION`, and/or `OPTIONS` sections. Additional sections
+commonly included are `SYNTAX`, `ENVIRONMENT`, `HISTORY`, `RETURN
+VALUES`, `BUGS`, `SECURITY CONSIDERATIONS`, `STANDARDS` /
+`CONFORMING TO`, `AUTHOR`, and `COPYRIGHT`. Finally, most man
+pages end with a `SEE ALSO` section that references other manual
+pages and external documents.
+
+## INLINE MARKUP
+
+Man pages typically use a limited set of text formatting
+capabilities. There's basically <b>boldface</b> and
+<i>italics</i> (often displayed using <u>underline</u>). Ron
+uses the following bits of markdown(5) to accomplish this:
+
+  * <code>\`backticks\`</code>:
+    Code, flags, commands, and noun-like things; typically
+    displayed in in <b>boldface</b>. Note that all text included
+    within `backticks` is displayed literally; other inline markup
+    is not processed.
+  * `_`_underbars_`_`:
+    User-specified arguments, variables, or user input; typically
+    displayed in <u>underline</u>.
+  * `**double stars**`:
+    Like `backticks` but may contain other inline markup.
+
+Here is grep(1)'s DESCRIPTION section represented in `ron`:
+
+    `Grep` searches the named input _FILE_ (or standard input if
+    no files are named, or the file name `-` is given) for lines
+    containing a match to the given _PATTERN_. By default, `grep`
+    prints the matching lines.
+
+## DEFINITION LISTS
+
+Because definition lists are so often used in manual pages to
+describe arguments, options, and variables, the basic markdown(5)
+list syntax has been extended to support a definition list
+syntax.
+
+A definition list's syntax is exactly the same as markdown(5)'s
+unordered list syntax but requires that the first line of each
+list item be terminated with a colon "`:`". The first line
+(minus the colon) is the _term_; subsequent lines may be
+comprised of multiple paragraphs, code blocks, standard lists,
+and nested definition lists.
+
+An example definition list, taken from test(1)'s `DESCRIPTION`
+section:
+
+     The following primaries are used to construct expressions:
+
+       * `-b` _file_:
+         True if _file_ exists and is a block special file.
+
+       * `-c` _file_:
+         True if _file_ exists and is a character special file.
+
+       * `-d` _file_:
+         True if file exists and is a directory.
+
+The definition list syntax is intentionally backward compatible
+with markdown(5)'s list syntax. This allows `ron` documents to be
+piped through normal markdown processors with minor degradation
+in output formatting.
+
+## SEE ALSO
+
+ron(1), markdown(5), manpages(5)

data/ron.gemspec

@@ -0,0 +1,48 @@
+Gem::Specification.new do |s|
+  s.specification_version = 2 if s.respond_to? :specification_version=
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+
+  s.name = 'ron'
+  s.version = '0.1'
+  s.date = '2009-11-05'
+
+  s.description = "The opposite of roff"
+  s.summary     = "The opposite of roff"
+
+  s.authors = ["Ryan Tomayko"]
+  s.email = "rtomayko@gmail.com"
+
+  # = MANIFEST =
+  s.files = %w[
+    COPYING
+    README
+    Rakefile
+    bin/ron
+    lib/ron.rb
+    lib/ron/document.rb
+    lib/ron/layout.html
+    lib/ron/roff.rb
+    man/markdown.5.ron
+    man/ron.1.ron
+    man/ron.5.ron
+    ron.gemspec
+    test/document_test.rb
+    test/ron_test.rb
+    test/simple.ron
+  ]
+  # = MANIFEST =
+
+  s.executables = ['ron']
+  s.test_files = s.files.select { |path| path =~ /^test\/.*_test.rb/ }
+
+  s.extra_rdoc_files = %w[README COPYING]
+  s.add_dependency 'nokogiri',    '~> 1.4'
+  s.add_dependency 'rdiscount',   '~> 1.3'
+  s.add_development_dependency 'contest', '~> 0.1'
+
+  s.has_rdoc = true
+  s.homepage = "http://github.com/rtomayko/ron/"
+  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Ron"]
+  s.require_paths = %w[lib]
+  s.rubygems_version = '1.1.1'
+end

data/test/document_test.rb

@@ -0,0 +1,35 @@
+require 'contest'
+require 'ron/document'
+
+class DocumentTest < Test::Unit::TestCase
+  SIMPLE_FILE = "#{File.dirname(__FILE__)}/simple.ron"
+  HELLO_DATA = "# hello(1) -- hello world"
+
+  test "creating with a file" do
+    doc = Ron::Document.new(SIMPLE_FILE)
+    assert_equal File.read(SIMPLE_FILE), doc.data
+  end
+
+  test "creating with a string and a file" do
+    doc = Ron::Document.new('hello.1.ron') { HELLO_DATA }
+    assert_equal HELLO_DATA, doc.data
+  end
+
+  context "Document" do
+    setup do
+      @doc = Ron::Document.new('hello.1.ron') { HELLO_DATA }
+    end
+
+    should "load data" do
+      assert_equal HELLO_DATA, @doc.data
+    end
+
+    should "extract the name" do
+      assert_equal 'hello', @doc.name
+    end
+
+    should "extract the section" do
+      assert_equal '1', @doc.section
+    end
+  end
+end

data/test/ron_test.rb

@@ -0,0 +1,29 @@
+require 'contest'
+
+# ron command tests
+class RonTest < Test::Unit::TestCase
+  testdir = File.dirname(__FILE__)
+  bindir = File.dirname(testdir)
+  ENV['PATH'] = "#{bindir}:#{ENV['PATH']}"
+
+  SIMPLE_FILE = "#{File.dirname(__FILE__)}/simple.ron"
+
+  test "takes ron text on stdin and produces roff on stdout" do
+    output = `echo '# hello(1) -- hello world' | ron`
+    lines = output.split("\n")
+    assert_equal 7, lines.size
+    assert_equal %[.\\" generated with Ron], lines.shift 
+    assert_equal %[.\\" http://github.com/rtomayko/ron/], lines.shift
+    assert_equal %[.], lines.shift
+    assert_equal %[.TH "HELLO" 1 "" "" ""], lines.shift
+    assert_equal %[.], lines.shift
+    assert_equal %[.SH "NAME"], lines.shift
+    assert_equal %[\\fBhello\\fR \\-\\- hello world], lines.shift
+    assert_equal 0, lines.size
+  end
+
+  test "produces html instead of roff with the --html argument" do
+    output = `echo '# hello(1) -- hello world' | ron --html`
+    assert_match(/<h2 id="NAME">NAME<\/h2>/, output)
+  end
+end

data/test/simple.ron

@@ -0,0 +1,2 @@
+simple(7) -- a simple ron example
+=================================

metadata

@@ -0,0 +1,103 @@
+--- !ruby/object:Gem::Specification 
+name: ron
+version: !ruby/object:Gem::Version 
+  version: "0.1"
+platform: ruby
+authors: 
+- Ryan Tomayko
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-11-05 00:00:00 -08:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: nokogiri
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: "1.4"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: rdiscount
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: "1.3"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: contest
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: "0.1"
+    version: 
+description: The opposite of roff
+email: rtomayko@gmail.com
+executables: 
+- ron
+extensions: []
+
+extra_rdoc_files: 
+- README
+- COPYING
+files: 
+- COPYING
+- README
+- Rakefile
+- bin/ron
+- lib/ron.rb
+- lib/ron/document.rb
+- lib/ron/layout.html
+- lib/ron/roff.rb
+- man/markdown.5.ron
+- man/ron.1.ron
+- man/ron.5.ron
+- ron.gemspec
+- test/document_test.rb
+- test/ron_test.rb
+- test/simple.ron
+has_rdoc: true
+homepage: http://github.com/rtomayko/ron/
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --line-numbers
+- --inline-source
+- --title
+- Ron
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 2
+summary: The opposite of roff
+test_files: 
+- test/document_test.rb
+- test/ron_test.rb