ronn-0.7.3/0000755000175000017500000000000011643142677012446 5ustar virtualvirtualronn-0.7.3/metadata.yml0000644000175000017500000000747311643142677014764 0ustar virtualvirtual--- !ruby/object:Gem::Specification name: ronn version: !ruby/object:Gem::Version hash: 5 prerelease: false segments: - 0 - 7 - 3 version: 0.7.3 platform: ruby authors: - Ryan Tomayko autorequire: bindir: bin cert_chain: [] date: 2010-06-24 00:00:00 -07:00 default_executable: dependencies: - !ruby/object:Gem::Dependency name: hpricot prerelease: false requirement: &id001 !ruby/object:Gem::Requirement none: false requirements: - - ">=" - !ruby/object:Gem::Version hash: 59 segments: - 0 - 8 - 2 version: 0.8.2 type: :runtime version_requirements: *id001 - !ruby/object:Gem::Dependency name: rdiscount prerelease: false requirement: &id002 !ruby/object:Gem::Requirement none: false requirements: - - ">=" - !ruby/object:Gem::Version hash: 19 segments: - 1 - 5 - 8 version: 1.5.8 type: :runtime version_requirements: *id002 - !ruby/object:Gem::Dependency name: mustache prerelease: false requirement: &id003 !ruby/object:Gem::Requirement none: false requirements: - - ">=" - !ruby/object:Gem::Version hash: 3 segments: - 0 - 7 - 0 version: 0.7.0 type: :runtime version_requirements: *id003 description: Builds manuals email: rtomayko@gmail.com executables: - ronn extensions: [] extra_rdoc_files: - COPYING - AUTHORS files: - AUTHORS - CHANGES - COPYING - INSTALLING - README.md - Rakefile - bin/ronn - config.ru - lib/ronn.rb - lib/ronn/document.rb - lib/ronn/index.rb - lib/ronn/roff.rb - lib/ronn/server.rb - lib/ronn/template.rb - lib/ronn/template/80c.css - lib/ronn/template/dark.css - lib/ronn/template/darktoc.css - lib/ronn/template/default.html - lib/ronn/template/man.css - lib/ronn/template/print.css - lib/ronn/template/screen.css - lib/ronn/template/toc.css - lib/ronn/utils.rb - man/index.html - man/index.txt - man/ronn-format.7 - man/ronn-format.7.ronn - man/ronn.1 - man/ronn.1.ronn - ronn.gemspec - test/angle_bracket_syntax.html - test/angle_bracket_syntax.ronn - test/basic_document.html - test/basic_document.ronn - test/contest.rb - test/custom_title_document.html - test/custom_title_document.ronn - test/definition_list_syntax.html - test/definition_list_syntax.roff - test/definition_list_syntax.ronn - test/dots_at_line_start_test.roff - test/dots_at_line_start_test.ronn - test/entity_encoding_test.html - test/entity_encoding_test.roff - test/entity_encoding_test.ronn - test/index.txt - test/markdown_syntax.html - test/markdown_syntax.roff - test/markdown_syntax.ronn - test/middle_paragraph.html - test/middle_paragraph.roff - test/middle_paragraph.ronn - test/missing_spaces.roff - test/missing_spaces.ronn - test/pre_block_with_quotes.roff - test/pre_block_with_quotes.ronn - test/section_reference_links.html - test/section_reference_links.roff - test/section_reference_links.ronn - test/test_ronn.rb - test/test_ronn_document.rb - test/test_ronn_index.rb - test/titleless_document.html - test/titleless_document.ronn - test/underline_spacing_test.roff - test/underline_spacing_test.ronn has_rdoc: true homepage: http://rtomayko.github.com/ronn licenses: [] post_install_message: rdoc_options: - --line-numbers - --inline-source - --title - Ronn require_paths: - lib required_ruby_version: !ruby/object:Gem::Requirement none: false requirements: - - ">=" - !ruby/object:Gem::Version hash: 3 segments: - 0 version: "0" required_rubygems_version: !ruby/object:Gem::Requirement none: false requirements: - - ">=" - !ruby/object:Gem::Version hash: 3 segments: - 0 version: "0" requirements: [] rubyforge_project: rubygems_version: 1.3.7 signing_key: specification_version: 3 summary: Builds manuals test_files: [] ronn-0.7.3/README.md0000644000175000017500000000676011643142677013736 0ustar virtualvirtual# Ronn Ronn builds manuals. It converts simple, human readable textfiles to roff for terminal display, and also to HTML for the web. The source format includes all of Markdown but has a more rigid structure and syntax extensions for features commonly found in manpages (definition lists, link notation, etc.). The ronn-format(7) manual page defines the format in detail. The `*.ronn` files found in the [`man/`][1] directory show off a wide range of ronn capabilities: * [ronn(1)](http://rtomayko.github.com/ronn/ronn.1) command - [source file](http://github.com/rtomayko/ronn/blob/master/man/ronn.1.ronn), [roff output](http://github.com/rtomayko/ronn/blob/master/man/ronn.1) * [ronn-format(7)](http://rtomayko.github.com/ronn/ronn-format.7) - [source file](http://github.com/rtomayko/ronn/blob/master/man/ronn-format.7.ronn), [roff output](http://github.com/rtomayko/ronn/blob/master/man/ronn-format.7) [1]: http://github.com/rtomayko/ronn/tree/master/man ## Examples Build roff and HTML output files for one or more input files: $ ronn man/ronn.5.ronn roff: man/ronn.5 html: man/ronn.5.html Generate only a standalone HTML version of one or more files: $ ronn --html man/markdown.5.ronn html: man/markdown.5.html Build roff versions of all ronn files in a directory: $ ronn --roff man/*.ronn View a ronn file as if it were a manpage without building intermediate files: $ ronn --man man/markdown.5.ronn View roff output with man(1): $ man man/ronn.5 The [ronn(1)](http://rtomayko.github.com/ronn/ronn.1) manual page includes comprehensive documentation on `ronn` command line options. ## Background Some think UNIX manual pages are a poor and outdated form of documentation. I disagree: - Manpages follow a well defined structure that's immediately familiar. This gives developers a starting point when documenting new tools, libraries, and formats. - Manpages get to the point. Because they're written in an inverted style, with a SYNOPSIS section followed by additional detail, prose and references to other sources of information, manpages provide the best of both cheat sheet and reference style documentation. - Historically, manpages use an extremely -- unbelievably -- limited set of text formatting capabilities. You get a couple of headings, lists, bold, underline and no more. This is a feature. - Although two levels of section hierarchy are technically supported, most manpages use only a single level. Unwieldy document hierarchies complicate otherwise good documentation. Remember that Feynman covered all of physics -- heavenly bodies through QED -- with only two levels of document hierarchy (_The Feynman Lectures on Physics_, 1970). - The classical terminal manpage display is typographically well thought out. Big bold section headings, justified monospace text, nicely indented paragraphs, intelligently aligned definition lists, and an informational header and footer. - Manpages have a simple referencing syntax; e.g., sh(1), fork(2), markdown(7). HTML versions can use this to generate links between pages. Unfortunately, figuring out how to create a manpage is a fairly tedious process. The roff/mandoc/mdoc macro languages are highly extensible, fractured between multiple dialects, and include a bunch of device specific stuff irrelevant to modern publishing tools. Ronn aims ## Copying Ronn is Copyright (C) 2010 [Ryan Tomayko](http://tomayko.com/about)
See the file COPYING for information of licensing and distribution. ronn-0.7.3/bin/0000755000175000017500000000000011643142677013216 5ustar virtualvirtualronn-0.7.3/bin/ronn0000755000175000017500000001326311643142677014125 0ustar virtualvirtual#!/usr/bin/env ruby #/ Usage: ronn ... #/ ronn -m|--man #/ ronn -S|--server ... #/ ronn --pipe [...] #/ Convert ronn source s to roff or HTML manpage. In the first synopsis form, #/ build HTML and roff output files based on the input file names. #/ #/ Mode options alter the default behavior of generating files: #/ --pipe write to standard output instead of generating files #/ -m, --man show manual like with man(1) #/ -S, --server serve s at http://localhost:1207/ #/ #/ Format options control which files / formats are generated: #/ -r, --roff generate roff output #/ -5, --html generate entire HTML page with layout #/ -f, --fragment generate HTML fragment #/ --markdown generate post-processed markdown output #/ #/ Document attributes: #/ --date= published date in YYYY-MM-DD format (bottom-center) #/ --manual= name of the manual (top-center) #/ --organization= publishing group or individual (bottom-left) #/ #/ Misc options: #/ -w, --warnings show troff warnings on stderr #/ -W disable previously enabled troff warnings #/ --version show ronn version and exit #/ --help show this help message #/ #/ A named example.1.ronn generates example.1.html (HTML manpage) #/ and example.1 (roff manpage) by default. require 'date' require 'optparse' def usage puts File.readlines(__FILE__). grep(/^#\/.*/). map { |line| line.chomp[3..-1] }. join("\n") end ## # Libraries and LOAD_PATH shenanigans begin require 'rdiscount' require 'hpricot' require 'ronn' rescue LoadError => boom if boom.to_s =~ /ronn/ libdir = File.expand_path("../../lib", __FILE__).sub(%r|^#{Dir.pwd}/|, './') if File.directory?(libdir) && !$:.include?(libdir) warn "warn: #{boom}. adding #{libdir} to RUBYLIB ..." $:.unshift libdir retry end elsif !defined?(Gem) warn "warn: #{boom}. loading rubygems ..." require 'rubygems' retry end abort boom.to_s end ## # Argument defaults build = true view = false server = false formats = nil options = {} write_index = false styles = %w[man] groff = "groff -Wall -mtty-char -mandoc -Tascii" pager = ENV['MANPAGER'] || ENV['PAGER'] || 'more' ## # Environment variables %w[manual organization date].each do |attribute| value = ENV["RONN_#{attribute.upcase}"] next if value.nil? or value.empty? options[attribute] = value end ## # Argument parsing ARGV.options do |argv| # modes argv.on("--pipe") { build = server = false } argv.on("-b", "--build") { build = true; server = false } argv.on("-m", "--man") { build = server = false; view = true } argv.on("-S", "--server") { build = view = false; server = true } argv.on("-i", "--index") { write_index = true } # format options argv.on("-r", "--roff") { (formats ||= []) << 'roff' } argv.on("-5", "--html") { (formats ||= []) << 'html' } argv.on("-f", "--fragment") { (formats ||= []) << 'html_fragment' } argv.on("--markdown") { (formats ||= []) << 'markdown' } # html output options argv.on("-s", "--style=V") { |val| styles += val.split(/[, \n]+/) } # manual attribute options %w[name section manual organization date].each do |attribute| argv.on("--#{attribute}=VALUE") { |val| options[attribute] = val } end # misc argv.on("-w", "--warnings") { groff += ' -ww' } argv.on("-W") { groff += ' -Ww' } argv.on("-v", "--version") do require 'ronn' if Ronn.release? printf "Ronn v%s\n", Ronn::VERSION else printf "Ronn v%s (%s)\n", Ronn::VERSION, Ronn::REV end printf "http://github.com/rtomayko/ronn/tree/%s\n", Ronn.revision exit 0 end argv.on_tail("--help") { usage ; exit 0 } argv.parse! end ## # Modes, Formats, Options case when ARGV.empty? && $stdin.tty? usage exit 2 when ARGV.empty? && !server ARGV.push '-' build = false formats ||= %w[roff] when view formats ||= %w[roff] when build formats ||= %w[roff html] end formats ||= [] formats.delete('html') if formats.include?('html_fragment') options['date'] &&= Date.strptime(options['date'], '%Y-%m-%d') options['styles'] = styles ## # Server if server require 'ronn/server' Ronn::Server.run(ARGV, options) exit 0 end ## # Build Pipeline pid = nil wr = STDOUT documents = ARGV.map { |file| Ronn::Document.new(file, options) } documents.each do |doc| # setup the man pipeline if the --man option was specified if view && !build rd, wr = IO.pipe if pid = fork rd.close else wr.close STDIN.reopen rd exec "#{groff} | #{pager}" end end # write output for each format formats.each do |format| if build path = doc.path_for(format) case format when 'html' warn "%9s: %-43s%15s" % [format, path, '+' + doc.styles.join(',')] when 'roff', 'html_fragment', 'markdown' warn "%9s: %-43s" % [format, path] end output = doc.convert(format) File.open(path, 'wb') { |f| f.puts(output) } if format == 'roff' if view system "man #{path}" else system "#{groff} <#{path} >/dev/null" end end else output = doc.convert(format) wr.puts(output) end end # wait for children to exit if pid wr.close Process.wait end end # Write index.txt files if write_index indexes = documents.map { |doc| doc.index }.uniq indexes.each do |index| File.open(index.path, 'wb') do |fd| fd.puts(index.to_text) end end end ronn-0.7.3/ronn.gemspec0000644000175000017500000000507011643142677014771 0ustar virtualvirtualGem::Specification.new do |s| s.name = 'ronn' s.version = '0.7.3' s.date = '2010-06-24' s.description = "Builds manuals" s.summary = "Builds manuals" s.homepage = "http://rtomayko.github.com/ronn" s.authors = ["Ryan Tomayko"] s.email = "rtomayko@gmail.com" # = MANIFEST = s.files = %w[ AUTHORS CHANGES COPYING INSTALLING README.md Rakefile bin/ronn config.ru lib/ronn.rb lib/ronn/document.rb lib/ronn/index.rb lib/ronn/roff.rb lib/ronn/server.rb lib/ronn/template.rb lib/ronn/template/80c.css lib/ronn/template/dark.css lib/ronn/template/darktoc.css lib/ronn/template/default.html lib/ronn/template/man.css lib/ronn/template/print.css lib/ronn/template/screen.css lib/ronn/template/toc.css lib/ronn/utils.rb man/index.html man/index.txt man/ronn-format.7 man/ronn-format.7.ronn man/ronn.1 man/ronn.1.ronn ronn.gemspec test/angle_bracket_syntax.html test/angle_bracket_syntax.ronn test/basic_document.html test/basic_document.ronn test/contest.rb test/custom_title_document.html test/custom_title_document.ronn test/definition_list_syntax.html test/definition_list_syntax.roff test/definition_list_syntax.ronn test/dots_at_line_start_test.roff test/dots_at_line_start_test.ronn test/entity_encoding_test.html test/entity_encoding_test.roff test/entity_encoding_test.ronn test/index.txt test/markdown_syntax.html test/markdown_syntax.roff test/markdown_syntax.ronn test/middle_paragraph.html test/middle_paragraph.roff test/middle_paragraph.ronn test/missing_spaces.roff test/missing_spaces.ronn test/pre_block_with_quotes.roff test/pre_block_with_quotes.ronn test/section_reference_links.html test/section_reference_links.roff test/section_reference_links.ronn test/test_ronn.rb test/test_ronn_document.rb test/test_ronn_index.rb test/titleless_document.html test/titleless_document.ronn test/underline_spacing_test.roff test/underline_spacing_test.ronn ] # = MANIFEST = s.executables = ['ronn'] s.test_files = s.files.select { |path| path =~ /^test\/.*_test.rb/ } s.extra_rdoc_files = %w[COPYING AUTHORS] s.add_dependency 'hpricot', '>= 0.8.2' s.add_dependency 'rdiscount', '>= 1.5.8' s.add_dependency 'mustache', '>= 0.7.0' s.has_rdoc = true s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Ronn"] s.require_paths = %w[lib] s.rubygems_version = '1.1.1' end ronn-0.7.3/CHANGES0000644000175000017500000001504511643142677013446 0ustar virtualvirtualRonn CHANGES ============ Version 0.7.3 (2010 June 24) ---------------------------- * Fixed a major bug in roff output due to overly aggressive doublequote escaping. Paragraphs and code blocks were not being displayed if they included a double-quote character. (rtomayko, pawelz) Version 0.7.0 (2010 June 21) ---------------------------- * HTML: Manual references (like 'grep(1)', 'ls(1)', etc.) are now hyperlinked based on a set of name -> URL mappings defined in an index.txt file. The index may also define links to things that aren't manuals for use in markdown reference-style links. See the ronn(1) manual on LINK INDEXES for more inforation: (rtomayko) * ROFF: Fixed a bug where multiple dot characters (.) at the beginning of a line were not being escaped properly and were not displayed when viewed in the terminal. (rtomayko) * ROFF: Non-breaking space characters ( ) can now be used to control line wrap in roff output. (rtomayko) * ROFF: Named HTML entities like •, ™, ©, and — are now converted to their roff escaped equivalents. (rtomayko) * An undocumented --markdown format option argument has been added to ronn(1). When given, ronn generates a .
.markdown file with the post-processed markdown text. This is mostly useful for debugging but may be useful for converting ronn-format to 100% compatible markdown text. (rtomayko) * The ronn(5) manpage is now known as ronn-format(7) (section 5 is limited to configuration files and stuff like that historically). The old ronn(7) manpage, which was really just the README, has been removed. (rtomayko) * Performance improvements. Fixed a few cases where HTML was being reparsed needlessly, tuned dom selectors, ... (rtomayko) Version 0.6.6 (2010 June 13) ---------------------------- Small bug fix release fixes whitespace stripping between adjacent inline elements in roff output (adamv, rtomayko) Version 0.6 (2010 June 13) -------------------------- Features: * HTML: New styling system: ronn --style=toc,print program.1.ronn ronn -s dark,toc,/path/to/custom.css man/*.ronn The --style (-s) option takes a list of CSS stylesheets to embed into the generated HTML. Stylesheets are inserted in the order specified and can use the cascade to add or remove visual elements. Ronn ships with a few built in styles: toc, dark, 80c, and print. You can insert your own by giving the path or manipulating the RONN_STYLE environment variable. See ronn(1) for full details on all of these things (rtomayko) * HTML: It's now possible to generate a Table Of Contents of manpage sections. The TOC is disabled by default. To enable it: ronn --style=toc file.ronn (sunaku) * HTML: The RONN_LAYOUT environment variable can be used to apply a custom mustache layout template: RONN_LAYOUT=mine.mustache ronn man/great-program.1.ronn See lib/ronn/template/default.html for default markup and features (defunkt) * HTML: All heading elements include page anchor id attributes to make it possible to link to a specific manpage section (sunaku) * HTML: Markdown reference links can be used to refer to sections. To link to the SEE ALSO section of the current manpage, use: [SEE ALSO][], or [to control the link text][SEE ALSO], or even [use the relative URL](#SEE-ALSO). (rtomayko) * HTML: 80 character terminal style: ronn -s 80c file.ronn -- precisely emulates a 80c terminal (sunaku) * HTML: Various appearance changes to the default stylesheet: smaller type with consistent vertical baseline; darker type for more contrast; em, var, and u are italic instead of underline (rtomayko) * HTML: Various print stylesheet tweaks, including hyperlinks and layout enhancements (sunaku) * ROFF: ronn --warnings (-w) shows troff warnings on stderr when building or viewing manuals. (rtomayko) * ROFF: Ordered lists. (sunaku) * ROFF: URLs for hyperlinks are shown immediately after hyperlink text. (sunaku) * The RONN_MANUAL, RONN_ORGANIZATION, and RONN_DATE environment variables establish the default values of the --manual, --organization, and --date options (rtomayko) Bugs: * ROFF: Don't crash with empty preformatted blocks (sunaku) * ROFF: A whole bunch of weird whitespace related problems in roff output, such as the first line of definition lists being indented by two characters (rtomayko) * ROFF: All ['".] characters are backslash escaped in roff output. These characters are used for various roff macro syntax (rtomayko) Deprecations, Obsoletions: * The ronn(1) command line interface has changed in ways that are not backward-compatible with previous versions of ronn. The --build option is assumed when one or more .ronn files is given on the command line. Previous versions write generated content to standard output with no explicit --build options. The default behavior when no files are given remains the same as previous versions: ronn source text is read from stdin and roff is written to stdout. See `ronn --help' or the ronn(1) manual for more on command line interface changes. (rtomayko, defunkt) * HTML: Ronn no longer uses a specific monospace font-family; the system default monospace font is used instead. Use 'ronn --style' to set up a font stack (rtomayko) * HTML: The following HTML elements are deprecated and will be removed at some point: div#man, div#man ol.man, div#man ol.head, div#man ol.man. The .mp, .man-decor, .man-head, .man-foot, .man-title, and .man-navigation classes should be used instead (rtomayko) * The markdown(5) manpage is no longer shipped with the ronn package. It is shipped with the latest version of rdiscount, however. (rtomayko, sunaku) 0.5 (2010 April 24) ------------------- * Fixed a bug in roff output where multiple successive newlines were being collapsed into a single newline in preformatted output. * Hexadecimal and decimal entity references generated by the Markdown to HTML conversion are now properly decoded into normal characters in roff output. * The compatibility shims that allowed the ronn command to be invoked as "ron", and the ronn library to be required as "ron", have been removed. 0.4 (2010 March 08) ------------------- * Ron has been renamed "Ronn", including the "ronn" command and the "ronn" library. Compatibility shims are included in this release but will be removed in the next release. * The hpricot library is now used for HTML hackery instead of the nokogiri library. The hpricot library is preferred because it doesn't depend on external system dependencies. ronn-0.7.3/config.ru0000644000175000017500000000043111643142677014261 0ustar virtualvirtual#\ -p 1207 $: << File.expand_path('../lib', __FILE__) require 'ronn' require 'ronn/server' # use Rack::Lint options = { :styles => %w[man toc], :organization => "Ronn v#{Ronn::VERSION}" } files = Dir['man/*.ronn'] + Dir['test/*.ronn'] run Ronn::Server.new(files, options) ronn-0.7.3/lib/0000755000175000017500000000000011643142677013214 5ustar virtualvirtualronn-0.7.3/lib/ronn.rb0000755000175000017500000000313111643142677014516 0ustar virtualvirtual# Ronn is a humane text format and toolchain for authoring manpages (and # things that appear as manpages from a distance). Use it to build / # install standard UNIX roff(7) formatted manpages or to generate # beautiful HTML manpages. module Ronn autoload :Document, 'ronn/document' autoload :Index, 'ronn/index' autoload :Template, 'ronn/template' autoload :Roff, 'ronn/roff' autoload :Server, 'ronn/server' # Create a new Ronn::Document for the given ronn file. See # Ronn::Document.new for usage information. def self.new(filename, attributes={}, &block) Document.new(filename, attributes, &block) end # truthy when this a release (\d.\d.\d) version. def self.release? revision != '' && !revision.include?('-') end # version: 0.6.11 # # A semantic version number based on the git revision. The third element # of the version is incremented by the commit offset, such that version # 0.6.6-5-gdacd74b => 0.6.11 def self.version ver = revision[/^[0-9.-]+/].split(/[.-]/).map { |p| p.to_i } ver[2] += ver.pop while ver.size > 3 ver.join('.') end # revision: 0.6.6-5-gdacd74b # revision: 0.6.25 # # The string revision as reported by: git-describe --tags. This is just the # tag name when a tag references the HEAD commit (0.6.25). When the HEAD # commit is not tagged, this is a "--" string: # - closest tag name # - number of commits ahead of # - 7c short SHA1 for HEAD def self.revision REV end # value generated by: rake rev REV = '0.7.3' VERSION = version end ronn-0.7.3/lib/ronn/0000755000175000017500000000000011643142677014170 5ustar virtualvirtualronn-0.7.3/lib/ronn/index.rb0000644000175000017500000000726211643142677015633 0ustar virtualvirtualrequire 'ronn' module Ronn # Maintains a list of links / references to manuals and other resources. class Index include Enumerable attr_reader :path attr_reader :references # Retrieve an Index for , where is a directory or normal # file. The index is loaded from the corresponding index.txt file if # one exists. def self.[](path) (@indexes ||= {})[index_path_for_file(path)] ||= Index.new(index_path_for_file(path)) end def self.index_path_for_file(file) File.expand_path( if File.directory?(file) File.join(file, 'index.txt') else File.join(File.dirname(file), 'index.txt') end ) end def initialize(path, &bk) @path = path @references = [] @manuals = {} if block_given? read! yield elsif exist? read! File.read(path) end end # Determine whether the index file exists. def exist? File.exist?(path) end # Load index data from a string. def read!(data) data.each_line do |line| line = line.strip.gsub(/\s*#.*$/, '') if !line.empty? name, url = line.split(/ +/, 2) @references << reference(name, url) end end end ## # Enumerable and friends def each(&bk) references.each(&bk) end def size references.size end def first references.first end def last references.last end def empty? references.empty? end def [](name) references.find { |ref| ref.name == name } end def reference(name, path) Reference.new(self, name, path) end def <<(path) raise ArgumentError, "local paths only" if path =~ /(https?|mailto):/ return self if any? { |ref| ref.path == File.expand_path(path) } relative_path = relative_to_index(path) @references << \ if path =~ /\.ronn?$/ reference manual(path).reference_name, relative_path else reference File.basename(path), relative_path end self end def add_manual(manual) @manuals[File.expand_path(manual.path)] = manual self << manual.path end def manual(path) @manuals[File.expand_path(path)] ||= Document.new(path) end def manuals select { |ref| ref.relative? && ref.ronn? }. map { |ref| manual(ref.path) } end ## # Converting def to_text map { |ref| [ref.name, ref.location].join(' ') }.join("\n") end def to_a references end def to_h to_a.map { |doc| doc.to_hash } end def relative_to_index(path) path = File.expand_path(path) index_dir = File.dirname(File.expand_path(self.path)) path.sub(/^#{index_dir}\//, '') end end # An individual index reference. A reference can point to one of a few types # of locations: # # - URLs: "http://man.cx/crontab(5)" # - Relative paths to ronn manuals: "crontab.5.ronn" # # The #url method should be used to obtain the href value for HTML. class Reference attr_reader :name attr_reader :location def initialize(index, name, location) @index = index @name = name @location = location end def manual? name =~ /\([0-9]\w*\)$/ end def ronn? location =~ /\.ronn?$/ end def remote? location =~ /^(?:https?|mailto):/ end def relative? !remote? end def url if remote? location else location.chomp('.ronn') + '.html' end end def path File.expand_path(location, File.dirname(@index.path)) if relative? end end end ronn-0.7.3/lib/ronn/utils.rb0000644000175000017500000000307211643142677015657 0ustar virtualvirtualrequire 'set' require 'cgi' module Ronn module Utils # All HTML 4 elements and some that are in common use. HTML = %w[ a abbr acronym address applet area b base basefont bdo big blockquote body br button caption center cite code col colgroup dd del dfn dir div dl dt em fieldset font form frame frameset h1 h2 h3 h4 h5 h6 head hr html i iframe img input ins isindex kbd label legend li link map menu meta noframes noscript object ol optgroup option p param pre q s samp script select small span strike strong style sub sup table tbody td textarea tfoot th thead title tr tt u ul var ].to_set # Block elements. HTML_BLOCK = %w[ blockquote body colgroup dd div dl dt fieldset form frame frameset h1 h2 h3 h4 h5 h6 hr head html iframe li noframes noscript object ol optgroup option p param pre script select style table tbody td textarea tfoot th thead title tr tt ul ].to_set # Inline elements HTML_INLINE = HTML - HTML_BLOCK # Elements that don't have a closing tag. HTML_EMPTY = %w[area base basefont br col hr input link meta].to_set def block_element?(name) HTML_BLOCK.include?(name) end def inline_element?(name) HTML_INLINE.include?(name) end def empty_element?(name) HTML_EMPTY.include?(name) end def html_element?(name) HTML.include?(name) end def child_of?(node, tag) while node return true if node.name && node.name.downcase == tag node = node.parent end false end end end ronn-0.7.3/lib/ronn/document.rb0000644000175000017500000003343111643142677016337 0ustar virtualvirtualrequire 'time' require 'cgi' require 'hpricot' require 'rdiscount' require 'ronn/roff' require 'ronn/template' require 'ronn/utils' module Ronn # The Document class can be used to load and inspect a ronn document # and to convert a ronn document into other formats, like roff or # HTML. # # Ronn files may optionally follow the naming convention: # ".
.ronn". The and
are used in # generated documentation unless overridden by the information # extracted from the document's name section. class Document include Ronn::Utils # Path to the Ronn document. This may be '-' or nil when the Ronn::Document # object is created with a stream. attr_reader :path # The raw input data, read from path or stream and unmodified. attr_reader :data # The index used to resolve man and file references. attr_accessor :index # The man pages name: usually a single word name of # a program or filename; displayed along with the section in # the left and right portions of the header as well as the bottom # right section of the footer. attr_accessor :name # The man page's section: a string whose first character # is numeric; displayed in parenthesis along with the name. attr_accessor :section # Single sentence description of the thing being described # by this man page; displayed in the NAME section. attr_accessor :tagline # The manual this document belongs to; center displayed in # the header. attr_accessor :manual # The name of the group, organization, or individual responsible # for this document; displayed in the left portion of the footer. attr_accessor :organization # The date the document was published; center displayed in # the document footer. attr_accessor :date # Array of style modules to apply to the document. attr_accessor :styles # Create a Ronn::Document given a path or with the data returned by # calling the block. The document is loaded and preprocessed before # the intialize method returns. The attributes hash may contain values # for any writeable attributes defined on this class. def initialize(path=nil, attributes={}, &block) @path = path @basename = path.to_s =~ /^-?$/ ? nil : File.basename(path) @reader = block || lambda do |f| if ['-', nil].include?(f) STDIN.read else File.read(f) end end @data = @reader.call(path) @name, @section, @tagline = sniff @styles = %w[man] @manual, @organization, @date = nil @markdown, @input_html, @html = nil @index = Ronn::Index[path || '.'] @index.add_manual(self) if path && name attributes.each { |attr_name,value| send("#{attr_name}=", value) } end # Generate a file basename of the form ".
." # for the given file extension. Uses the name and section from # the source file path but falls back on the name and section # defined in the document. def basename(type=nil) type = nil if ['', 'roff'].include?(type.to_s) [path_name || @name, path_section || @section, type]. compact.join('.') end # Construct a path for a file near the source file. Uses the # Document#basename method to generate the basename part and # appends it to the dirname of the source document. def path_for(type=nil) if @basename File.join(File.dirname(path), basename(type)) else basename(type) end end # Returns the part of the path, or nil when no path is # available. This is used as the manual page name when the # file contents do not include a name section. def path_name @basename[/^[^.]+/] if @basename end # Returns the
part of the path, or nil when # no path is available. def path_section $1 if @basename.to_s =~ /\.(\d\w*)\./ end # Returns the manual page name based first on the document's # contents and then on the path name. def name @name || path_name end # Truthful when the name was extracted from the name section # of the document. def name? !@name.nil? end # Returns the manual page section based first on the document's # contents and then on the path name. def section @section || path_section end # True when the section number was extracted from the name # section of the document. def section? !@section.nil? end # The name used to reference this manual. def reference_name name + (section && "(#{section})").to_s end # Truthful when the document started with an h1 but did not follow # the "() -- " convention. We assume this is some kind # of custom title. def title? !name? && tagline end # The document's title when no name section was defined. When a name section # exists, this value is nil. def title @tagline if !name? end # The date the man page was published. If not set explicitly, # this is the file's modified time or, if no file is given, # the current time. def date return @date if @date return File.mtime(path) if File.exist?(path) Time.now end # Retrieve a list of top-level section headings in the document and return # as an array of +[id, text]+ tuples, where +id+ is the element's generated # id and +text+ is the inner text of the heading element. def toc @toc ||= html.search('h2[@id]').map { |h2| [h2.attributes['id'], h2.inner_text] } end alias section_heads toc # Styles to insert in the generated HTML output. This is a simple Array of # string module names or file paths. def styles=(styles) @styles = (%w[man] + styles).uniq end # Sniff the document header and extract basic document metadata. Return a # tuple of the form: [name, section, description], where missing information # is represented by nil and any element may be missing. def sniff html = Markdown.new(data[0, 512]).to_html heading, html = html.split("\n", 2) return [nil, nil, nil] if html.nil? case heading when /([\w_.\[\]~+=@:-]+)\s*\((\d\w*)\)\s*-+\s*(.*)/ # name(section) -- description [$1, $2, $3] when /([\w_.\[\]~+=@:-]+)\s+-+\s+(.*)/ # name -- description [$1, nil, $2] else # description [nil, nil, heading.sub('

', '')] end end # Preprocessed markdown input text. def markdown @markdown ||= process_markdown! end # A Hpricot::Document for the manual content fragment. def html @html ||= process_html! end # Convert the document to :roff, :html, or :html_fragment and # return the result as a string. def convert(format) send "to_#{format}" end # Convert the document to roff and return the result as a string. def to_roff RoffFilter.new( to_html_fragment(wrap_class=nil), name, section, tagline, manual, organization, date ).to_s end # Convert the document to HTML and return the result as a string. def to_html if layout = ENV['RONN_LAYOUT'] if !File.exist?(layout_path = File.expand_path(layout)) warn "warn: can't find #{layout}, using default layout." layout_path = nil end end template = Ronn::Template.new(self) template.context.push :html => to_html_fragment(wrap_class=nil) template.render(layout_path || 'default') end # Convert the document to HTML and return the result # as a string. The HTML does not include , , # or " ].join("\n ") end def remote_stylesheet(name, media='all') path = File.expand_path("../template/#{name}.css", __FILE__) "" end def stylesheet(path, media='all') inline_stylesheet(name, media) end end end ronn-0.7.3/lib/ronn/server.rb0000644000175000017500000000374611643142677016035 0ustar virtualvirtualrequire 'ronn' require 'rack' require 'sinatra/base' module Ronn # Ronn HTTP server. Serves a list of .ronn files as HTML. The options Hash is # passed to Ronn::Document.new on each invocation. # # Use Ronn::Server.new to create a Rack app. See the config.ru file in the # root of the Ronn distribution for example usage. # # Ronn::Server.run starts a server on port module Server def self.new(files, options={}) files = Dir[files] if files.respond_to?(:to_str) raise ArgumentError, "no files" if files.empty? Sinatra.new do set :show_exceptions, true set :public, File.expand_path(__FILE__, '../templates') set :static, false set :views, File.expand_path(__FILE__, '../templates') get '/' do files.map do |f| base = File.basename(f, '.ronn') "
  • #{escape_html(base)}
    • " end end def styles params[:styles] ||= params[:style] case when params[:styles].respond_to?(:to_ary) params[:styles] when params[:styles] params[:styles].split(/[, ]+/) else [] end end files.each do |file| basename = File.basename(file, '.ronn') get "/#{basename}.html" do options = options.merge(:styles => styles) %w[date manual organization].each do |attribute| next if !params[attribute] options[attribute] = params[attribute] end Ronn::Document.new(file, options).to_html end get "/#{basename}.roff" do content_type 'text/plain+roff' Ronn::Document.new(file, options.dup).to_roff end end end end def self.run(files, options={}) new(files, options).run!( :server => %w[mongrel thin webrick], :port => 1207, :logging => true ) end end end ronn-0.7.3/lib/ronn/roff.rb0000644000175000017500000001677411643142677015470 0ustar virtualvirtualrequire 'hpricot' require 'ronn/utils' module Ronn class RoffFilter include Ronn::Utils # Convert Ronn HTML to roff. def initialize(html, name, section, tagline, manual=nil, version=nil, date=nil) @buf = [] title_heading name, section, tagline, manual, version, date doc = Hpricot(html) remove_extraneous_elements! doc normalize_whitespace! doc block_filter doc write "\n" end def to_s @buf.join.gsub(/[ \t]+$/, '') end protected def previous(node) if node.respond_to?(:previous) prev = node.previous prev = prev.previous until prev.nil? || prev.elem? prev end end def title_heading(name, section, tagline, manual, version, date) comment "generated with Ronn/v#{Ronn.version}" comment "http://github.com/rtomayko/ronn/tree/#{Ronn.revision}" return if name.nil? macro "TH", %["#{escape(name.upcase)}" "#{section}" "#{date.strftime('%B %Y')}" "#{version}" "#{manual}"] end def remove_extraneous_elements!(doc) doc.traverse_all_element do |node| if node.comment? || node.procins? || node.doctype? || node.xmldecl? node.parent.children.delete(node) end end end def normalize_whitespace!(node) case when node.kind_of?(Array) || node.kind_of?(Hpricot::Elements) node.to_a.dup.each { |ch| normalize_whitespace! ch } when node.text? preceding, following = node.previous, node.next content = node.content.gsub(/[\n ]+/m, ' ') if preceding.nil? || block_element?(preceding.name) || preceding.name == 'br' content.lstrip! end if following.nil? || block_element?(following.name) || following.name == 'br' content.rstrip! end if content.empty? node.parent.children.delete(node) else node.content = content end when node.elem? && node.name == 'pre' # stop traversing when node.elem? && node.children normalize_whitespace! node.children when node.elem? # element has no children when node.doc? normalize_whitespace! node.children else warn "unexpected node during whitespace normalization: %p", node end end def block_filter(node) if node.kind_of?(Array) || node.kind_of?(Hpricot::Elements) node.each { |ch| block_filter(ch) } elsif node.doc? block_filter(node.children) elsif node.text? warn "unexpected text: %p", node elsif node.elem? case node.name when 'div' block_filter(node.children) when 'h1' # discard when 'h2' macro "SH", quote(escape(node.html)) when 'h3' macro "SS", quote(escape(node.html)) when 'p' prev = previous(node) if prev && %w[dd li].include?(node.parent.name) macro "IP" elsif prev && !%w[h1 h2 h3].include?(prev.name) macro "P" end inline_filter(node.children) when 'pre' prev = previous(node) indent = prev.nil? || !%w[h1 h2 h3].include?(prev.name) macro "IP", %w["" 4] if indent macro "nf" write "\n" inline_filter(node.children) macro "fi" macro "IP", %w["" 0] if indent when 'dl' macro "TP" block_filter(node.children) when 'dt' prev = previous(node) macro "TP" unless prev.nil? inline_filter(node.children) write "\n" when 'dd' if node.at('p') block_filter(node.children) else inline_filter(node.children) end write "\n" when 'ol', 'ul' block_filter(node.children) macro "IP", %w["" 0] when 'li' case node.parent.name when 'ol' macro "IP", %W["#{node.position + 1}." 4] when 'ul' macro "IP", %w["\(bu" 4] end if node.at('p|ol|ul|dl|div') block_filter(node.children) else inline_filter(node.children) end write "\n" else warn "unrecognized block tag: %p", node.name end else fail "unexpected node: #{node.inspect}" end end def inline_filter(node) return unless node # is an empty node if node.kind_of?(Array) || node.kind_of?(Hpricot::Elements) node.each { |ch| inline_filter(ch) } elsif node.text? text = node.to_html.dup write escape(text) elsif node.elem? case node.name when 'span' inline_filter(node.children) when 'code' if child_of?(node, 'pre') inline_filter(node.children) else write '\fB' inline_filter(node.children) write '\fR' end when 'b', 'strong', 'kbd', 'samp' write '\fB' inline_filter(node.children) write '\fR' when 'var', 'em', 'i', 'u' write '\fI' inline_filter(node.children) write '\fR' when 'br' macro 'br' when 'a' if node.classes.include?('man-ref') inline_filter(node.children) elsif node.has_attribute?('data-bare-link') write '\fI' inline_filter(node.children) write '\fR' else inline_filter(node.children) write ' ' write '\fI' write escape(node.attributes['href']) write '\fR' end else warn "unrecognized inline tag: %p", node.name end else fail "unexpected node: #{node.inspect}" end end def macro(name, value=nil) writeln ".\n.#{[name, value].compact.join(' ')}" end HTML_ROFF_ENTITIES = { '•' => '\(bu', '<' => '<', '>' => '>', ' ' => '\~', '©' => '\(co', '”' => '\(rs', '—' => '\(em', '®' => '\(rg', '&sec;' => '\(sc', '≥' => '\(>=', '≤' => '\(<=', '≠' => '\(!=', '≡' => '\(==' } def escape(text) return text.to_s if text.nil? || text.empty? ent = HTML_ROFF_ENTITIES text = text.dup text.gsub!(/&#x([0-9A-Fa-f]+);/) { $1.to_i(16).chr } # hex entities text.gsub!(/&#(\d+);/) { $1.to_i.chr } # dec entities text.gsub!('\\', '\e') # backslash text.gsub!(/['.-]/) { |m| "\\#{m}" } # control chars text.gsub!(/(&[A-Za-z]+;)/) { ent[$1] || $1 } # named entities text.gsub!('&', '&') # amps text end def quote(text) "\"#{text.gsub(/"/, '\\"')}\"" end # write text to output buffer def write(text) return if text.nil? || text.empty? # lines cannot start with a '.'. insert zero-width character before. if text[0,2] == '\.' && (@buf.last && @buf.last[-1] == ?\n) @buf << '\&' end @buf << text end # write text to output buffer on a new line. def writeln(text) write "\n" if @buf.last && @buf.last[-1] != ?\n write text write "\n" end def comment(text) writeln %[.\\" #{text}] end def warn(text, *args) $stderr.puts "warn: #{text}" % args end end end ronn-0.7.3/lib/ronn/template/0000755000175000017500000000000011643142677016003 5ustar virtualvirtualronn-0.7.3/lib/ronn/template/print.css0000644000175000017500000000023211643142677017646 0ustar virtualvirtual.mp { max-width:none } .man-navigation { display:none !important } .mp a[href]:not([href^="#"]):not([data-bare-link]):after { content:" " attr(href); } ronn-0.7.3/lib/ronn/template/dark.css0000644000175000017500000000103111643142677017431 0ustar virtualvirtual.mp, body#manpage { background:#080706; color:#888; } .mp, .mp code, .mp pre, .mp pre code, .mp tt, .mp kbd, .mp samp { color:#aaa } .mp h1, .mp h2, .mp h3, .mp h4 { color:#fff } .man-decor, .man-decor ol li { color:#666 } .mp code, .mp strong, .mp b { color:#fff } .mp em, .mp var, .mp u { color:#ddd } .mp pre code { color:#ddd } .mp a, .mp a:link, .mp a:hover, .mp a code, .mp a pre, .mp a tt, .mp a kbd, .mp a samp { color:#fff } ronn-0.7.3/lib/ronn/template/toc.css0000644000175000017500000000105411643142677017302 0ustar virtualvirtual/* toc.css - enable table of contents */ .man-navigation { display:block !important; position:fixed; top:0; left:113ex; /* .mp width + padding */ height:100%; width:100%; padding:48px 0 0 0; border-left:1px solid #dbdbdb; background:#eee; } .man-navigation a, .man-navigation a:hover, .man-navigation a:link, .man-navigation a:visited { display:block; margin:0; padding:5px 2px 5px 30px; color:#999; text-decoration:none; } .man-navigation a:hover { color:#111; text-decoration:underline; } ronn-0.7.3/lib/ronn/template/man.css0000644000175000017500000000503011643142677017266 0ustar virtualvirtual/* man.css - core manpage styles */ /* STRUCTURE, INDENT, MARGINS */ body#manpage { margin:0 } .mp { max-width:100ex; padding:0 9ex 1ex 4ex; } .mp p, .mp pre, .mp ul, .mp ol, .mp dl { margin:0 0 20px 0 } .mp h2 { margin:10px 0 0 0 } .mp > p, .mp > pre, .mp > ul, .mp > ol, .mp > dl { margin-left:8ex } .mp h3 { margin:0 0 0 4ex } .mp dt { margin:0; clear:left } .mp dt.flush { float:left; width:8ex } .mp dd { margin:0 0 0 9ex } .mp h1, .mp h2, .mp h3, .mp h4 { clear:left } .mp pre { margin-bottom:20px } .mp pre+h2, .mp pre+h3 { margin-top:22px } .mp h2+pre, .mp h3+pre { margin-top:5px } .mp img { display:block;margin:auto } .mp h1.man-title { display:none } /* FONTS */ .mp, .mp code, .mp pre, .mp tt, .mp kbd, .mp samp, .mp h3, .mp h4 { font-family:monospace; font-size:14px; line-height:1.42857142857143; } .mp h2 { font-size:16px; line-height:1.25; } .mp h1 { font-size:20px; line-height:2; } /* TEXT STYLES */ .mp { text-align:justify; background:#fff; } .mp, .mp code, .mp pre, .mp pre code, .mp tt, .mp kbd, .mp samp { color:#131211 } .mp h1, .mp h2, .mp h3, .mp h4 { color:#030201 } .mp u { text-decoration:underline; } .mp code, .mp strong, .mp b { font-weight:bold; color:#131211; } .mp em, .mp var { font-style:italic; color:#232221; text-decoration:none; } /* LINKS */ .mp a, .mp a:link, .mp a:hover, .mp a code, .mp a pre, .mp a tt, .mp a kbd, .mp a samp { color:#0000ff } .mp b.man-ref { font-weight:normal;color:#434241 } /* PREFORMATTED BLOCKS */ .mp pre { padding:0 4ex } .mp pre code { font-weight:normal;color:#434241 } .mp h2+pre, h3+pre { padding-left:0 } /* DOCUMENT HEADER AND FOOTER AREAS */ ol.man-decor, ol.man-decor li { margin:3px 0 10px 0; padding:0; float:left; width:33%; list-style-type:none; text-transform:uppercase; color:#999; letter-spacing:1px; } ol.man-decor { width:100% } ol.man-decor li.tl { text-align:left } ol.man-decor li.tc { text-align:center; letter-spacing:4px } ol.man-decor li.tr { text-align:right; float:right } ronn-0.7.3/lib/ronn/template/default.html0000644000175000017500000000201111643142677020307 0ustar virtualvirtual {{ title }} {{{ stylesheet_tags }}}
    1. {{ page_name }}
    2. {{ manual }}
    3. {{ page_name }}
    {{{ html }}}
    1. {{ organization }}
    2. {{ date }}
    3. {{ page_name }}
    ronn-0.7.3/lib/ronn/template/darktoc.css0000644000175000017500000000052711643142677020150 0ustar virtualvirtual/* darktoc.css - enable table of contents */ .man-navigation { border-left:2px solid #222; background-color:#131211; } .man-navigation a, .man-navigation a:hover, .man-navigation a:link, .man-navigation a:visited { color:#777; text-decoration:none; } .man-navigation a:hover { color:#fff; text-decoration:underline; } ronn-0.7.3/lib/ronn/template/screen.css0000644000175000017500000000507411643142677020002 0ustar virtualvirtual/* STRUCTURE, INDENT, MARGINS */ body { margin:0 } #man { max-width:88ex; padding:0 2ex 1ex 2ex } #man p, #man pre, #man ul, #man ol, #man dl { margin:0 0 20px 0 } #man h2 { margin:10px 0 0 0 } #man > p, #man > pre, #man > ul, #man > ol, #man > dl { margin-left:8ex } #man h3 { margin:0 0 0 4ex } #man dt { margin:0; clear:left } #man dt.flush { float:left; width:8ex } #man dd { margin:0 0 0 9ex } #man h1, #man h2, #man h3, #man h4 { clear:left } #man pre { margin-bottom:20px } #man pre+h2, #man pre+h3 { margin-top:22px } #man h2+pre, #man h3+pre { margin-top:5px } #man img { display:block;margin:auto } #man h1.man-title { display:none } /* FONTS */ #man, #man code, #man pre, #man tt, #man kbd, #man samp, #man h3, #man h4 { font-family:monospace; font-size:14px; line-height:1.42857142857143; } #man h2, #man ol.man { font-size:16px; line-height:1.25 } #man h1 { font-size:20px; line-height:2; } /* TEXT STYLES */ #man { text-align:justify; background:#fff; } #man, #man code, #man pre, #man pre code, #man tt, #man kbd, #man samp { color:#131211 } #man h1, #man h2, #man h3, #man h4 { color:#030201 } #man ol.man, #man ol.man li { color:#636261 } #man code, #man strong, #man b { font-weight:bold; color:#131211; } #man em, #man var, #man u { font-style:italic; color:#434241; text-decoration:none; } #man pre { background:#edeceb; padding:5px 1ex; border-left:1ex solid #ddd; } #man pre code { font-weight:normal; background:inherit; } /* DOCUMENT HEADER AND FOOTER AREAS */ #man ol.man, #man ol.man li { margin:3px 0 10px 0; padding:0; float:left; width:33%; list-style-type:none; text-transform:uppercase; color:#999; letter-spacing:1px; } #man ol.man { width:100% } #man ol.man li.tl { text-align:left } #man ol.man li.tc { text-align:center; letter-spacing:4px } #man ol.man li.tr { text-align:right; float:right } /* SECTION TOC NAVIGATION */ #man div.man-navigation { position:fixed; top:0; left:96ex; height:100%; width:100%; padding:1ex 0 0 2ex; border-left:0.25ex solid #DCDCDC; background-color: #F5F5F5; } #man div.man-navigation a { display:block; margin-bottom:1.5ex } ronn-0.7.3/lib/ronn/template/80c.css0000644000175000017500000000027711643142677017115 0ustar virtualvirtual/* 80c.css - condense width to emulate a classical 80 character terminal */ .mp { max-width:86ex } /* .mp width + padding */ .man-navigation { left:101ex } ronn-0.7.3/COPYING0000644000175000017500000000213211643142677013477 0ustar virtualvirtual Copyright (C) 2009 Ryan Tomayko Permission is hereby granted, free of charge, to any person ob- taining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restric- tion, including without limitation the rights to use, copy, modi- fy, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is fur- nished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONIN- FRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ronn-0.7.3/AUTHORS0000644000175000017500000000046511643142677013523 0ustar virtualvirtual# This is a list of people who have contributed code or ideas to ronn -- for # copyright purposes or whatever. Ryan Tomayko Chris Wanstrath Suraj N. Kurapati Hallison Batista ronn-0.7.3/INSTALLING0000644000175000017500000000102711643142677014035 0ustar virtualvirtualRonn is currently distributed mainly as a gem package. Install with rubygems: $ gem install ronn $ ronn --help Tarballs available at: $ curl -L http://github.com/rtomayko/ronn/downloads/0.6.6 | tar xvzf - $ cd rtomayko-r* $ ruby setup.rb The hpricot, mustache, and rdiscount packages are required. Hacking? Clone the git repository and put ronn/bin on your PATH: $ git clone git://github.com/rtomayko/ronn.git $ PATH=$(pwd)/ronn/bin:$PATH $ ronn --help ronn-0.7.3/man/0000755000175000017500000000000011643142677013221 5ustar virtualvirtualronn-0.7.3/man/ronn-format.70000644000175000017500000001165711643142677015565 0ustar virtualvirtual.\" generated with Ronn/v0.7.0 .\" http://github.com/rtomayko/ronn/tree/0.7.0 . .TH "RONN\-FORMAT" "7" "June 2010" "Ronn 0.7.0" "Ronn Manual" . .SH "NAME" \fBronn\-format\fR \- manual authoring format based on Markdown . .SH "SYNOPSIS" . .nf name(1) \-\- short, single\-sentence description ============================================= ## SYNOPSIS `name` [\.\.\.] ## DESCRIPTION A normal paragraph\. This can span multiple lines and is terminated with two or more line endings \-\- just like Markdown\. Inline markup for `code`, `user input`, and **strong** are displayed boldface; , _emphasis_, *emphasis*, are displayed in italics (HTML) or underline (roff)\. Manual references like sh(1), markdown(7), roff(7), etc\. are hyperlinked in HTML output\. Link to sections like [STANDARDS][], [SEE ALSO][], or [WITH A DIFFERENT LINK TEXT][#SEE\-ALSO]\. Definition lists: * `\-a`, `\-\-argument`=[]: One or more paragraphs describing the argument\. * You can put whatever you *want* here, really: Nesting and paragraph spacing are respected\. Frequently used sections: ## OPTIONS ## SYNTAX ## ENVIRONMENT ## RETURN VALUES ## STANDARDS ## SECURITY CONSIDERATIONS ## BUGS ## HISTORY ## AUTHOR ## COPYRIGHT ## SEE ALSO . .fi . .SH "DESCRIPTION" The ronn(1) command converts text in a simple markup to UNIX manual pages\. The syntax includes all Markdown formatting features, plus conventions for expressing the structure and various notations present in standard UNIX manpages\. . .P Not all roff(7) typesetting features can be expressed using ronn syntax\. . .SH "MANPAGE TITLE" Manpages have a \fIname\fR, \fIsection\fR, and a one\-line \fIdescription\fR\. Files must start with a level one heading defining these attributes: . .IP "" 4 . .nf ls(1) \-\- list directory contents ================================ . .fi . .IP "" 0 . .P Indicates that the manpage is named \fBls\fR in manual section \fB1\fR (\"user commands\")\. . .SH "SECTION HEADINGS" Man section headings are expressed with markdown level two headings\. There are two syntaxes for level two headings\. . .P Hash prefix syntax: . .IP "" 4 . .nf ## HEADING TEXT . .fi . .IP "" 0 . .P Dash underline syntax: . .IP "" 4 . .nf HEADING TEXT \-\-\-\-\-\-\-\-\-\-\-\- . .fi . .IP "" 0 . .P Section headings should be all uppercase and may not contain inline markup\. . .SH "INLINE MARKUP" Manpages have a limited set of text formatting capabilities\. There\'s basically \fBboldface\fR and \fIitalics\fR (often displayed using \fIunderline\fR)\. Ronn uses the following bits of markdown(7) to accomplish this: . .TP \fB`backticks`\fR (markdown compatible) Code, flags, commands, and noun\-like things; typically displayed in in \fBboldface\fR\. All text included within \fBbackticks\fR is displayed literally; other inline markup is not processed\. HTML output: \fB\fR\. . .TP \fB**double\-stars**\fR (markdown compatible) Also displayed in boldface\. Unlike backticks, inline markup is processed\. HTML output: \fB\fR\. . .TP \fB\fR (non\-compatible markdown extension) User\-specified arguments, variables, or user input\. Typically displayed with \fIunderline\fR in roff output\. HTML output: \fB\fR\. . .TP \fB_\fR\fIunderbars\fR\fB_\fR (markdown compatible) Emphasis\. May be used for literal option values\. Typically displayed with \fIunderline\fR in roff output\. HTML output: \fB\fR\. . .P Here is grep(1)\'s DESCRIPTION section represented in \fBronn\fR: . .IP "" 4 . .nf `Grep` searches the named input (or standard input if no files are named, or the file name `\-` is given) for lines containing a match to the given \. By default, `grep` prints the matching lines\. . .fi . .IP "" 0 . .SH "DEFINITION LISTS" The definition list syntax is compatible with markdown\'s unordered list syntax but requires that the first line of each list item be terminated with a colon \"\fB:\fR\" character\. The contents of the first line is the \fIterm\fR; subsequent lines may be comprised of multiple paragraphs, code blocks, standard lists, and nested definition lists\. . .P An example definition list, taken from BSD test(1)\'s \fIDESCRIPTION\fR section: . .IP "" 4 . .nf The following primaries are used to construct expressions: * `\-b` : True if exists and is a block special file\. * `\-c` : True if _file_ exists and is a character special file\. * `\-d` : True if file exists and is a directory\. . .fi . .IP "" 0 . .SH "LINKS" All markdown(7) linking features are supported\. . .P Markdown reference\-style links can be used to link to specific sections by name: . .IP "" 4 . .nf ## SECTION 1 See the following section\. ## SECTION 2 See [SECTION 1][] or [to put it another way][SECTION 1]\. . .fi . .IP "" 0 . .P The anchor name would be \fB#SECTION\-1\fR and \fB#SECTION\-2\fR\. All non\-word characters are removed and spaces are replaced by dashes\. . .SH "SEE ALSO" ronn(1), markdown(7), roff(7) ronn-0.7.3/man/index.html0000644000175000017500000000441711643142677015224 0ustar virtualvirtual Ronn

    Ronn

    Builds manuals

    Auxiliary

    README, INSTALLING, CHANGES, COPYING, AUTHORS

    Manuals

    ronn(1)
    manual authoring tool
    ronn-format(7)
    markdown-based text format for authoring manpages

    See Also

    manpages(5), markdown(7), man(1), roff(7), groff(1), mustache(5)

    Copyright © 2010 Ryan Tomayko

    ronn-0.7.3/man/ronn-format.7.ronn0000644000175000017500000001121411643142677016525 0ustar virtualvirtualronn-format(7) -- manual authoring format based on Markdown =========================================================== ## SYNOPSIS name(1) -- short, single-sentence description ============================================= ## SYNOPSIS `name` [...] ## DESCRIPTION A normal paragraph. This can span multiple lines and is terminated with two or more line endings -- just like Markdown. Inline markup for `code`, `user input`, and **strong** are displayed boldface; , _emphasis_, *emphasis*, are displayed in italics (HTML) or underline (roff). Manual references like sh(1), markdown(7), roff(7), etc. are hyperlinked in HTML output. Link to sections like [STANDARDS][], [SEE ALSO][], or [WITH A DIFFERENT LINK TEXT][#SEE-ALSO]. Definition lists: * `-a`, `--argument`=[]: One or more paragraphs describing the argument. * You can put whatever you *want* here, really: Nesting and paragraph spacing are respected. Frequently used sections: ## OPTIONS ## SYNTAX ## ENVIRONMENT ## RETURN VALUES ## STANDARDS ## SECURITY CONSIDERATIONS ## BUGS ## HISTORY ## AUTHOR ## COPYRIGHT ## SEE ALSO ## DESCRIPTION The ronn(1) command converts text in a simple markup to UNIX manual pages. The syntax includes all Markdown formatting features, plus conventions for expressing the structure and various notations present in standard UNIX manpages. Not all roff(7) typesetting features can be expressed using ronn syntax. ## MANPAGE TITLE Manpages have a ,
    , and a one-line . Files must start with a level one heading defining these attributes: ls(1) -- list directory contents ================================ Indicates that the manpage is named `ls` in manual section `1` ("user commands"). ## SECTION HEADINGS Man section headings are expressed with markdown level two headings. There are two syntaxes for level two headings. Hash prefix syntax: ## HEADING TEXT Dash underline syntax: HEADING TEXT ------------ Section headings should be all uppercase and may not contain inline markup. ## INLINE MARKUP Manpages have a limited set of text formatting capabilities. There's basically boldface and italics (often displayed using underline). Ronn uses the following bits of markdown(7) to accomplish this: * \`backticks\` (markdown compatible): Code, flags, commands, and noun-like things; typically displayed in in boldface. All text included within `backticks` is displayed literally; other inline markup is not processed. HTML output: ``. * `**double-stars**` (markdown compatible): Also displayed in boldface. Unlike backticks, inline markup is processed. HTML output: ``. * `` (non-compatible markdown extension): User-specified arguments, variables, or user input. Typically displayed with underline in roff output. HTML output: ``. * `_`_underbars_`_` (markdown compatible): Emphasis. May be used for literal option values. Typically displayed with underline in roff output. HTML output: ``. Here is grep(1)'s DESCRIPTION section represented in `ronn`: `Grep` searches the named input (or standard input if no files are named, or the file name `-` is given) for lines containing a match to the given . By default, `grep` prints the matching lines. ## DEFINITION LISTS The definition list syntax is compatible with markdown's unordered list syntax but requires that the first line of each list item be terminated with a colon "`:`" character. The contents of the first line is the ; subsequent lines may be comprised of multiple paragraphs, code blocks, standard lists, and nested definition lists. An example definition list, taken from BSD test(1)'s *DESCRIPTION* section: The following primaries are used to construct expressions: * `-b` : True if exists and is a block special file. * `-c` : True if _file_ exists and is a character special file. * `-d` : True if file exists and is a directory. ## LINKS All markdown(7) linking features are supported. Markdown reference-style links can be used to link to specific sections by name: ## SECTION 1 See the following section. ## SECTION 2 See [SECTION 1][] or [to put it another way][SECTION 1]. The anchor name would be `#SECTION-1` and `#SECTION-2`. All non-word characters are removed and spaces are replaced by dashes. ## SEE ALSO ronn(1), markdown(7), roff(7) ronn-0.7.3/man/ronn.1.ronn0000644000175000017500000002540011643142677015233 0ustar virtualvirtualronn(1) -- convert markdown files to manpages ============================================= ## SYNOPSIS `ronn` [...] ...
    `ronn` `-m`|`--man` ...
    `ronn` `-S`|`--server` ...
    `ronn` `--pipe`
    `ronn` < ## DESCRIPTION **Ronn** converts textfiles to standard roff-formatted UNIX manpages or HTML. ronn-format(7) is based on markdown(7) but includes additional rules and syntax geared toward authoring manuals. In its default mode, `ronn` converts one or more input s to HTML or roff output files. The `--roff`, `--html`, and `--fragment` options dictate which output files are generated. Multiple format arguments may be specified to generate multiple output files. Output files are named after and written to the same directory as input s. The `--server` and `--man` options change the output behavior from file generation to serving dynamically generated HTML manpages or viewing as with man(1). With no arguments, `ronn` acts as simple filter. Ronn source text is read from standard input and roff output is written to standard output. Use the `--html`, `--roff`, and/or `--fragment` options to select the output format. ## FILES The `ronn` command expects input to be valid ronn-format(7) text. Source files are typically named .
    .ronn (e.g., `example.1.ronn`). The and
    should match the name and section defined in the 's heading. When building roff or HTML output files, destination filenames are determined by taking the basename of the input and adding the appropriate file extension (or removing the file extension in the case of roff output). For example, executing `ronn example.1.ronn` generates `example.1` with roff output and `example.1.html` with HTML output. ## OPTIONS These options control whether output is written to file(s), standard output, or directly to a man pager. * `-m`, `--man`: Don't generate files, display s 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. * `-S`, `--server`: Don't generate files, start an HTTP server at and serve dynamically generated HTML for the set of input s. A file named *example.2.ronn* is served as */example.2.html*. There's also an index page at the root with links to each . The server respects the `--style` and document attribute options (`--manual`, `--date`, etc.). These same options can be varied at request time by giving them as query parameters: `?manual=FOO&style=dark,toc` *NOTE: The builtin server is designed to assist in the process of writing and styling manuals. It is in no way recommended as a general purpose web server.* * `--pipe`: Don't generate files, write generated output to standard output. This is the default behavior when ronn source text is piped in on standard input and no arguments are provided. Format options control the files `ronn` generates, or the output format when the `--pipe` argument is specified. When no format options are given, both `--roff` and `--html` are assumed. * `-r`, `--roff`: Generate roff output. This is the default behavior when no s are given and ronn source text is read from standard input. * `-5`, `--html`: Generate output in HTML format. * `-f`, `--fragment`: Generate output in HTML format but only the document fragment, not the header, title, or footer. Document attributes displayed in the header and footer areas of generated content are specified with these options. (These values may also be set via the [ENVIRONMENT][].) * `--manual`=: The name of the manual this man page belongs to; is prominently displayed top-center in the header area. * `--organization`=: The name of the group, organization, or individual responsible for publishing the document; is displayed in the bottom-left footer area. * `--date`=: The document's published date; must be formatted `YYYY-MM-DD` and is displayed in the bottom-center footer area. The mtime is used when no is given, or the current time when no is available. HTML output can be customized through the use of CSS stylesheets: * `--style`=[,]...: The list of CSS stylesheets to apply to the document. Multiple arguments may be specified, but must be separated by commas or spaces. When is a simple word, search for files named `.css` in all directories listed in the [`RONN_STYLE`](#ENVIRONMENT) environment variable, and then search internal styles. When includes a _/_ character, use it as the full path to a stylesheet file. Internal styles are _man_ (included by default), _toc_, and _80c_. See [STYLES][] for descriptions of features added by each module. Miscellaneous options: * `-w`, `--warnings`: Show troff warnings on standard error when performing roff conversion. Warnings are most often the result of a bug in ronn's HTML to roff conversion logic. * `-W`: Disable troff warnings. Warnings are disabled by default. This option can be used to revert the effect of a previous `-w` argument. * `-v`, `--version`: Show ronn version and exit. ## LINK INDEXES When generating HTML output, `ronn` hyperlinks manual references (like `grep(1)`, `ls(1)`, `markdown(7)`) in source text based on reference name to URL mappings defined in an `index.txt` file. Each line of the index file describes a single reference link, with whitespace separating the reference's from its . Blank lines are allowed; lines beginning with a `#` character are ignored: # manuals included in this project: whisky(1) whisky.1.ronn tango(5) tango.5.ronn # external manuals grep(1) http://man.cx/grep(1) ls(1) http://man.cx/ls(1) # other URLs for use with markdown reference links src http://github.com/ The is an absolute or relative URL that usually points at an HTML version of manpage. It's possible to define references for things that aren't manpages. All manuals in an individual directory share the references defined in that directory's `index.txt` file. Index references may be used explicitly in Markdown reference style links using the syntax: `[``][``]`, where is the link text and is a reference name defined in the index. ## STYLES The `--style` option selects a list of CSS stylesheets to include in the generated HTML. Styles are applied in the order defined, so each can use the cascade to override previously defined styles. ### Builtin Stylesheets These styles are included with the distribution: * `man`: Basic manpage styles: typography, definition lists, indentation. This is always included regardless of `--style` argument. It is however possible to replace the default `man` module with a custom one by placing a `man.css` file on the `RONN_STYLE` path. * `print`: Basic print stylesheet. The generated `