pax_global_header00006660000000000000000000000064134105632620014514gustar00rootroot0000000000000052 comment=7e233727be56e259634de7d6744471446a259f0e ronn-ng-0.8.0/000077500000000000000000000000001341056326200130775ustar00rootroot00000000000000ronn-ng-0.8.0/.gitignore000066400000000000000000000003011341056326200150610ustar00rootroot00000000000000# We want to track the RubyMine project in the repo !.idea /.idea/workspace.xml /man/*.html /pkg /test/*.wrong ronn.1 ronn.5 ronn.7 ronn*.markdown ronn*.html Gemfile.lock ronn-ng-*.gem .bundleronn-ng-0.8.0/.idea/000077500000000000000000000000001341056326200140575ustar00rootroot00000000000000ronn-ng-0.8.0/.idea/.rakeTasks000066400000000000000000000005071341056326200160120ustar00rootroot00000000000000 ronn-ng-0.8.0/.idea/encodings.xml000066400000000000000000000002071341056326200165510ustar00rootroot00000000000000 ronn-ng-0.8.0/.idea/inspectionProfiles/000077500000000000000000000000001341056326200177365ustar00rootroot00000000000000ronn-ng-0.8.0/.idea/inspectionProfiles/Project_Default.xml000066400000000000000000000020511341056326200235300ustar00rootroot00000000000000 ronn-ng-0.8.0/.idea/misc.xml000066400000000000000000000005731341056326200155410ustar00rootroot00000000000000 ronn-ng-0.8.0/.idea/modules.xml000066400000000000000000000004121341056326200162460ustar00rootroot00000000000000 ronn-ng-0.8.0/.idea/ronn-ng.iml000066400000000000000000000057521341056326200161510ustar00rootroot00000000000000 ronn-ng-0.8.0/.idea/vagrant.xml000066400000000000000000000003301341056326200162370ustar00rootroot00000000000000 ronn-ng-0.8.0/.idea/vcs.xml000066400000000000000000000002641341056326200153760ustar00rootroot00000000000000 ronn-ng-0.8.0/.rubocop.yml000066400000000000000000000015561341056326200153600ustar00rootroot00000000000000AllCops: TargetRubyVersion: 2.3 # To get fixed Layout/AlignHash: Enabled: false Metrics/BlockLength: Enabled: false Metrics/LineLength: Enabled: false Metrics/ParameterLists: Enabled: false Metrics/AbcSize: Enabled: false Metrics/CyclomaticComplexity: Enabled: false Metrics/PerceivedComplexity: Enabled: false Security/Eval: Enabled: false # test_ronn_document fails when it uses safe_load Security/YAMLLoad: Enabled: false # Permanently disabled - I don't care about these. Layout/EmptyLineAfterGuardClause: Enabled: false Metrics/BlockNesting: Enabled: false Metrics/ClassLength: Enabled: false Metrics/MethodLength: Enabled: false Style/FrozenStringLiteralComment: Enabled: false Style/RegexpLiteral: Enabled: false Style/PerlBackrefs: Enabled: false Style/Semicolon: Enabled: false Style/WordArray: Enabled: false ronn-ng-0.8.0/.travis.yml000066400000000000000000000003151341056326200152070ustar00rootroot00000000000000language: ruby rvm: - 2.3 - 2.4 - 2.5 install: - bundle install --with development script: - bundle exec rake test - bundle exec rake package - bundle exec rake man - bundle exec rubocopronn-ng-0.8.0/AUTHORS000066400000000000000000000005461341056326200141540ustar00rootroot00000000000000# 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 Andrew Janke ronn-ng-0.8.0/CHANGES000066400000000000000000000157721341056326200141060ustar00rootroot00000000000000Ronn-NG CHANGES =============== Version 0.8.0 (2018 Dec 25) --------------------------- * Added tables support. (apjanke) * Lint & Rubocop fixes. (apjanke) * Added --output-dir option. (apjanke) * Support file names with periods in the name section. (apjanke) * Migrated from Hpricot to Nokogiri. (apjanke) Version 0.7.4 (2018 Dec 22) --------------------------- * Forked Ronn-NG from original Ronn. (apjanke) * Minor bug fixes: #4, #5 (apjanke) Original Ronn 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-ng-0.8.0/Gemfile000066400000000000000000000000461341056326200143720ustar00rootroot00000000000000source 'https://rubygems.org' gemspec ronn-ng-0.8.0/INSTALLING.md000066400000000000000000000047571341056326200151020ustar00rootroot00000000000000Ronn-NG Installation ==================== ## Installation Process ### From a Package Manager The best way to install Ronn-NG is with a package manager. This is currently only supported on macOS, with [Homebrew](http://brew.sh). To install with `brew`: ``` brew tap apjanke/ronn-ng brew install --HEAD ronn-ng ``` ### From RubyGems Ronn-NG is distributed as a gem package, which can be used if you don't have a supported package manager. Install with rubygems: ``` gem install ronn-ng ronn --help ``` Ronn-NG includes completion definitions for bash and zsh, but these are not installed into the system locations as part of the gem. You will need to figure out how to install those into your system to make them available in your shell. A decent way to do this is probably to add symlinks to your system shell completion directories pointing at the files in the installed gem. In Zsh, you can do something like this: ``` ronn_dist_dir=$(dirname $(dirname $(gem which ronn-ng))) ronn_zsh_dir="$ronn_dist_dir/completion/zsh" ln -s "$ronn_zsh_dir/_ronn" /usr/local/share/zsh/site-functions ``` In Bash, something like this: ``` ronn_dist_dir=$(dirname $(dirname $(gem which ronn-ng))) ronn_bash_dir="$ronn_dist_dir/completion/bash" ln -s "$ronn_bash_dir/ronn" /usr/local/etc/bash_completion.d ``` You will need to redo these steps each time you upgrade `ronn-ng` or install it into a different Ruby environment. Sorry for the inconvenience; this seems to be a limitation of the `gem` installation mechanism. If that `gem which` stuff doesn't work for you, you can `gem install gem-path` and use `gem path ronn-ng` instead. ## Building from Source Hacking? Install Ronn-NG from source. Clone the git repository and put ronn/bin on your PATH: ``` git clone git://github.com/apjanke/ronn-ng PATH=$(pwd)/ronn-ng/bin:$PATH ``` The following gems are required for ronn-ng development: * nokogiri * mustache * rdiscount * rubocop * sinatra * rack * rake * test-unit ``` gem install nokogiri mustache rdiscount rubocop sinatra rack rake test-unit ``` Or install them with bundler using the project's gem definition: ``` bundle install --with development ``` Then you should be able to make changes directly to your cloned repo and have them be reflected in your active `ronn` command. ## Legacy Versions Historical Ronn tarballs available at [the original Ronn repo](http://github.com/rtomayko/ronn/downloads). ``` curl -L http://github.com/rtomayko/ronn/downloads/0.6.6 | tar xvzf - cd rtomayko-r* ruby setup.rb ``` ronn-ng-0.8.0/LICENSE.txt000066400000000000000000000022111341056326200147160ustar00rootroot00000000000000The MIT License Copyright (C) 2009 Ryan Tomayko Copyright (C) 2018 Andrew Janke Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished 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 NONINFRINGEMENT. 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-ng-0.8.0/README.md000066400000000000000000000107641341056326200143660ustar00rootroot00000000000000# Ronn-NG Ronn-NG is a new, currently-maintained fork of the defunct [original Ronn project](https://github.com/rtomayko/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/apjanke/ronn-ng/blob/master/man/ronn.1.ronn), [roff output](http://github.com/apjanke/ronn-ng/blob/master/man/ronn.1) * [ronn-format(7)](http://rtomayko.github.com/ronn/ronn-format.7) - [source file](http://github.com/apjanke/ronn-ng/blob/master/man/ronn-format.7.ronn), [roff output](http://github.com/apjanke/ronn-ng/blob/master/man/ronn-format.7) [1]: http://github.com/apjanke/ronn-ng/tree/master/man As an alternative, you might want to check out [pandoc](http://johnmacfarlane.net/pandoc/) which can also convert markdown into roff manual pages. ## Installation Install with Homebrew on macOS: ``` brew tap apjanke/ronn-ng brew install ronn-ng ``` See [INSTALLING.md][] for details on other systems and installation methods. ## 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. ## Requirements Ruby 2.3 or newer. ## Project Management The project home page is at https://github.com/apjanke/ronn-ng. Bug reports, feature requests, and patch submissions are welcome. Ronn-NG was forked from the original Ronn project in 2018 after Ronn development had been defunct for a couple years, and Andrew wanted some bugs fixed. ## License and Copying MIT License. Ronn is Copyright (C) 2010 [Ryan Tomayko](http://tomayko.com/about). New Ronn-NG material is Copyright (c) 2018 [Andrew Janke](https://apjanke.net) and other contributors. See the file LICENSE.txt for information of licensing and distribution. ## Build Status ![Travis build status](https://travis-ci.com/apjanke/ronn-ng.svg?branch=master) ronn-ng-0.8.0/Rakefile000066400000000000000000000101661341056326200145500ustar00rootroot00000000000000require 'rake/clean' require 'date' task default: :test ROOTDIR = File.expand_path(__dir__).sub(/#{Dir.pwd}(?=\/)/, '.') LIBDIR = "#{ROOTDIR}/lib".freeze BINDIR = "#{ROOTDIR}/bin".freeze task :environment do $LOAD_PATH.unshift ROOTDIR unless $LOAD_PATH.include?(ROOTDIR) $LOAD_PATH.unshift LIBDIR unless $LOAD_PATH.include?(LIBDIR) require_library 'nokogiri' require_library 'rdiscount' ENV['RUBYLIB'] = $LOAD_PATH.join(':') ENV['PATH'] = "#{BINDIR}:#{ENV['PATH']}" end desc 'Run tests' task test: :environment do $LOAD_PATH.unshift "#{ROOTDIR}/test" Dir['test/test_*.rb'].each { |f| require(f) } end desc 'Start the server' task server: :environment do if system('type shotgun >/dev/null 2>&1') exec 'shotgun config.ru' else require 'ronn/server' Ronn::Server.run('man/*.ronn') end end desc 'Build the manual' task man: :environment do require 'ronn' ENV['RONN_MANUAL'] = 'Ronn Manual' ENV['RONN_ORGANIZATION'] = "Ronn-NG #{Ronn.revision}" sh 'ronn -w -s toc -r5 --markdown man/*.ronn' end desc 'Publish to GitHub pages' task pages: :man do puts '----------------------------------------------' puts 'Rebuilding pages ...' verbose(false) do rm_rf 'pages' push_url = `git remote show origin`.grep(/Push.*URL/).first[/git@.*/] sh " set -e git fetch -q origin rev=$(git rev-parse origin/gh-pages) git clone -q -b gh-pages . pages cd pages git reset --hard $rev rm -f ronn*.html index.html cp -rp ../man/ronn*.html ../man/index.txt ../man/index.html ./ git add -u ronn*.html index.html index.txt git commit -m 'rebuild manual' git push #{push_url} gh-pages ", verbose: false end end # PACKAGING ============================================================ # Rev Ronn::VERSION task :rev do rev = ENV['REV'] || `git describe --tags`.chomp data = File.read('lib/ronn.rb') data.gsub!(/^( *)REV *=.*/, "\\1REV = '#{rev}'") File.open('lib/ronn.rb', 'wb') { |fd| fd.write(data) } puts "revision: #{rev}" puts "version: #{`ruby -Ilib -rronn -e 'puts Ronn::VERSION'`}" end require 'rubygems' @spec = eval(File.read('ronn-ng.gemspec')) def package(ext = '') "pkg/ronn-ng-#{@spec.version}" + ext end desc 'Build packages' task package: %w[.gem .tar.gz].map { |ext| package(ext) } desc 'Build and install as local gem' task install: package('.gem') do sh "gem install #{package('.gem')}" end directory 'pkg/' CLOBBER.include('pkg') file package('.gem') => %w[pkg/ ronn-ng.gemspec] + @spec.files do |f| sh 'gem build ronn-ng.gemspec' mv File.basename(f.name), f.name end file package('.tar.gz') => %w[pkg/] + @spec.files do |f| sh <<-SH git archive --prefix=ronn-#{source_version}/ --format=tar HEAD | gzip > #{f.name} SH end def source_version @source_version ||= `ruby -Ilib -rronn -e 'puts Ronn::VERSION'`.chomp end file 'ronn-ng.gemspec' => FileList['{lib,test,bin}/**', 'Rakefile'] do |f| # read spec file and split out manifest section spec = File.read(f.name) head, _manifest, tail = spec.split(" # = MANIFEST =\n") # replace version and date head.sub!(/\.version = '.*'/, ".version = '#{source_version}'") head.sub!(/\.date = '.*'/, ".date = '#{Date.today}'") # determine file list from git ls-files files = `git ls-files` .split("\n") .sort .reject { |file| file =~ /^\./ } .reject { |file| file =~ /^doc/ } .map { |file| " #{file}" } .join("\n") # piece file back together and write... manifest = " s.files = %w[\n#{files}\n ]\n" spec = [head, manifest, tail].join(" # = MANIFEST =\n") File.open(f.name, 'w') { |io| io.write(spec) } puts "updated #{f.name}" end # Misc =============================================================== def require_library(name) require name rescue LoadError => boom unless defined?(Gem) warn "warn: #{boom}. trying again with rubygems." require 'rubygems' retry end abort "fatal: the '#{name}' library is required (gem install #{name})" end # make .wrong test files right task :right do Dir['test/*.wrong'].each do |file| dest = file.sub(/\.wrong$/, '') mv file, dest end end ronn-ng-0.8.0/bin/000077500000000000000000000000001341056326200136475ustar00rootroot00000000000000ronn-ng-0.8.0/bin/ronn000077500000000000000000000144421341056326200145560ustar00rootroot00000000000000#!/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/ # / --port run server at specified port instead of 1207 # / -o, --output-dir write generated files to specified directory # / # / 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[4..-1] } .join("\n") end ## # Libraries and LOAD_PATH shenanigans begin require 'rdiscount' require 'nokogiri' require 'ronn' rescue LoadError => boom if boom.to_s =~ /ronn/ libdir = File.expand_path('../lib', __dir__).sub(%r{^#{Dir.pwd}/}, './') if File.directory?(libdir) && !$LOAD_PATH.include?(libdir) # warn "warn: #{boom}. adding #{libdir} to RUBYLIB ..." $LOAD_PATH.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 port_arg = nil formats = nil options = {} write_index = false styles = %w[man] groff = 'groff -Wall -mtty-char -mandoc -Tascii -t' pager = ENV['MANPAGER'] || ENV['PAGER'] || 'more -is' output_dir = nil ## # Environment variables %w[manual organization date].each do |attribute| value = ENV["RONN_#{attribute.upcase}"] next if value.nil? || 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 } argv.on('-o', '--output-dir=V') { |val| output_dir = val } argv.on('--port=V') { |val| port_arg = val } # 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' } argv.on('--yaml') { (formats ||= []) << 'yaml' } # 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-NG v%s\n", Ronn::VERSION else printf "Ronn-NG v%s (%s)\n", Ronn::VERSION, Ronn::REV end printf "http://github.com/apjanke/ronn-ng/tree/%s\n", Ronn.revision exit 0 end argv.on_tail('--help') { usage; exit 0 } argv.parse! end ## # Modes, Formats, Options if ARGV.empty? && $stdin.tty? usage exit 2 elsif ARGV.empty? && !server ARGV.push '-' build = false formats ||= %w[roff] elsif view formats ||= %w[roff] elsif 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 options['outdir'] = output_dir unless port_arg.nil? begin options['port'] = Integer(port_arg) rescue ArgumentError warn "Error: invalid port number: '#{port_arg}'" exit 1 end end ## # 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 pid = fork if pid rd.close else wr.close STDIN.reopen rd exec "#{groff} | #{pager}" end end # write output for each format formats.each do |fmt| if build path = doc.path_for(fmt) case fmt when 'html' warn format('%9s: %-43s%15s', fmt, path, '+' + doc.styles.join(',')) when 'roff', 'html_fragment', 'markdown' warn format('%9s: %-43s', fmt, path) end output = doc.convert(fmt) File.open(path, 'wb') { |f| f.puts(output) } if fmt == 'roff' if view system "man #{path}" else system "#{groff} <#{path} >/dev/null" end end else output = doc.convert(fmt) 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(&:index).uniq indexes.each do |index| File.open(index.path, 'wb') do |fd| fd.puts(index.to_text) end end end ronn-ng-0.8.0/completion/000077500000000000000000000000001341056326200152505ustar00rootroot00000000000000ronn-ng-0.8.0/completion/bash/000077500000000000000000000000001341056326200161655ustar00rootroot00000000000000ronn-ng-0.8.0/completion/bash/ronn000066400000000000000000000011261341056326200170640ustar00rootroot00000000000000# Bash completion script for ronn(1) from Ronn-NG _ronn() { local cur prev words cword _init_completion -n = || return COMREPLY=() cur=${COMP_WORDS[COMP_CWORD]} case "$prev" in --help|--version|-!(-*)'?') return ;; -o|--output-dir|-!(-*)e) _filedir -d return ;; esac if [[ "$cur" == -* ]]; then COMREPLY=( $( compgen -W '--pipe -m --man -S --server --port -o --output-dir -r --roff -5 --html -f --fragment --markdown --date --manual --organization -w --warnings -W --version --help')) return fi _filedir return 0 } && complete -F _ronn ronn # ex: filetype=shronn-ng-0.8.0/completion/zsh/000077500000000000000000000000001341056326200160545ustar00rootroot00000000000000ronn-ng-0.8.0/completion/zsh/_ronn000066400000000000000000000023041341056326200171110ustar00rootroot00000000000000#compdef ronn # Zsh completion definitions for ronn, from Ronn-NG _arguments -C -s -S \ '(--pipe)--pipe[write to standard output instead of generating files]' \ '(-m --man)'{-m,--man}'[show manual like with man]' \ '(-S --server)'{-S,--server}'[serve s at http://localhost:1207/]' \ '(--port)--port[run server at specified port instead of 1207]:Port Number' \ '(-o --output-dir)'{-o,--output-dir}'[write generated files to specified directory]:Output Directory:_dirs' \ '(-r --roff)'{-r,--roff}'[generate roff output]' \ '(-5 --html)'{-5,--html}'[generate entire HTML page with layout]' \ '(-f --fragment)'{-f,--fragment}'[generate HTML fragment]' \ '(--markdown)--markdown[generate post-processed markdown output]' \ '(--date)--date[published date in YYYY-MM-DD format]:Date' \ '(--manual)--manual[name of the manual]:Manual Name' \ '(--organization)--organization[publishing group or individual]:Organization Name' \ '(-w --warnings)'{-w,--warnings}'[show troff warnings on stderr]' \ '(-W)-W[disable previously enabled troff warnings]' \ '(--version)--version[show ronn version and exit]' \ '(--help)--help[show help message and exit]' \ '*:input files:_files' \ && ret=0 ronn-ng-0.8.0/config.ru000066400000000000000000000004261341056326200147160ustar00rootroot00000000000000#\ -p 1207 $LOAD_PATH << File.expand_path('lib', __dir__) 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-ng-0.8.0/doc-src/000077500000000000000000000000001341056326200144315ustar00rootroot00000000000000ronn-ng-0.8.0/doc-src/Developer-Guide.md000066400000000000000000000015101341056326200177300ustar00rootroot00000000000000Ronn-NG Developer's Guide ========================= ## Release checklist * Update the version in files * ronn-ng.gemspec * `lib/ronn.rb` * Update `CHANGES` with the release date * Regenerate the man pages with `rake man` * Run the tests one last time! `rake test` * Commit the updated files * Tag the release: `git tag vX.Y.Z` * `git push --tags` * Build and deploy the gem to RubyGems * ??? * TODO: Announce the release somewhere After the release, start development on the next release: * Update the version in files * ronn-ng.gemspec * `lib/ronn.rb` * Update `CHANGES` with a new section for the next release * Regenerate the man pages again: `rake man` * Commit and push ## Running tests `rake test` will run all the tests. Do `RONN_QUIET_TEST=1 rake test` for shorter output that omits the possibly-long diff outputs.ronn-ng-0.8.0/doc-src/legacy-issue-comments.txt000066400000000000000000000000001341056326200213750ustar00rootroot00000000000000ronn-ng-0.8.0/lib/000077500000000000000000000000001341056326200136455ustar00rootroot00000000000000ronn-ng-0.8.0/lib/ronn.rb000077500000000000000000000032631341056326200151550ustar00rootroot00000000000000# 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(&: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 # or edit manually; I'm not sure of how rake rev interacts with git # tags -apjanke REV = '0.8.0'.freeze VERSION = version end ronn-ng-0.8.0/lib/ronn/000077500000000000000000000000001341056326200146215ustar00rootroot00000000000000ronn-ng-0.8.0/lib/ronn/document.rb000066400000000000000000000410301341056326200167620ustar00rootroot00000000000000require 'time' require 'cgi' require 'nokogiri' require 'rdiscount' require 'ronn/index' 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_writer :name # The man page's section: a string whose first character # is numeric; displayed in parenthesis along with the name. attr_writer :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_writer :date # Array of style modules to apply to the document. attr_reader :styles # Output directory to write files to attr_accessor :outdir # 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 @outdir File.join(@outdir, basename(type)) elsif @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 return unless @basename parts = @basename.split('.') parts.pop if parts.last.casecmp('ronn').zero? parts.pop if parts.last =~ /^\d+$/ parts.join('.') 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. 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. 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. A string whose first character # is numeric; displayed in parenthesis along with the 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 unless 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. Center displayed in the document footer. 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'].content.upcase, 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], :no_superscript).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 Nokogiri DocumentFragment 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(nil), name, section, tagline, manual, organization, date ).to_s end # Convert the document to HTML and return the result as a string. # The returned string is a complete HTML document. def to_html layout = ENV['RONN_LAYOUT'] layout_path = nil if layout layout_path = File.expand_path(layout) unless File.exist?(layout_path) 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(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-ng-0.8.0/lib/ronn/template/000077500000000000000000000000001341056326200164345ustar00rootroot00000000000000ronn-ng-0.8.0/lib/ronn/template/80c.css000066400000000000000000000002771341056326200175460ustar00rootroot00000000000000/* 80c.css - condense width to emulate a classical 80 character terminal */ .mp { max-width:86ex } /* .mp width + padding */ .man-navigation { left:101ex } ronn-ng-0.8.0/lib/ronn/template/dark.css000066400000000000000000000010311341056326200200620ustar00rootroot00000000000000.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-ng-0.8.0/lib/ronn/template/darktoc.css000066400000000000000000000005271341056326200206010ustar00rootroot00000000000000/* 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-ng-0.8.0/lib/ronn/template/default.html000066400000000000000000000020151341056326200207440ustar00rootroot00000000000000 {{ title }} {{{ stylesheet_tags }}}
  1. {{ page_name }}
  2. {{ manual }}
  3. {{ page_name }}
{{{ html }}}
  1. {{ organization }}
  2. {{ date }}
  3. {{ page_name }}
ronn-ng-0.8.0/lib/ronn/template/man.css000066400000000000000000000050301341056326200177170ustar00rootroot00000000000000/* 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-ng-0.8.0/lib/ronn/template/print.css000066400000000000000000000002321341056326200202770ustar00rootroot00000000000000.mp { max-width:none } .man-navigation { display:none !important } .mp a[href]:not([href^="#"]):not([data-bare-link]):after { content:" " attr(href); } ronn-ng-0.8.0/lib/ronn/template/screen.css000066400000000000000000000050741341056326200204330ustar00rootroot00000000000000/* 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-ng-0.8.0/lib/ronn/template/toc.css000066400000000000000000000010541341056326200177330ustar00rootroot00000000000000/* 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-ng-0.8.0/lib/ronn/utils.rb000066400000000000000000000032031341056326200163040ustar00rootroot00000000000000require 'set' require 'cgi' module Ronn # Miscellaneous utilities. 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 return false if node.document? node = node.parent end false end end end ronn-ng-0.8.0/man/000077500000000000000000000000001341056326200136525ustar00rootroot00000000000000ronn-ng-0.8.0/man/index.html000066400000000000000000000044631341056326200156560ustar00rootroot00000000000000 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, © 2018 Andrew Janke

ronn-ng-0.8.0/man/index.txt000066400000000000000000000010061341056326200155170ustar00rootroot00000000000000# manuals ronn(1) ronn.1.ronn ronn(5) ronn.5.ronn ronn(7) ronn.7.ronn # external manuals roff(7) http://man.cx/roff(7) grep(1) http://man.cx/grep(1) groff(1) http://man.cx/groff(1) sh(1) http://man.cx/sh(1posix) test(1) http://man.cx/test(1) fork(2) http://man.cx/fork(2) man(1) http://man.cx/man(1) markdown(7) http://daringfireball.net/projects/markdown/syntax manpages(5) http://developer.apple.com/mac/library/documentation/Darwin/Reference/ManPages/man5/manpages.5.html ronn-ng-0.8.0/man/ronn-format.7000066400000000000000000000115241341056326200162070ustar00rootroot00000000000000.\" generated with Ronn-NG/v0.8.0 .\" http://github.com/apjanke/ronn-ng/tree/0.8.0 .TH "RONN\-FORMAT" "7" "December 2018" "Ronn-NG 0.8.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-ng-0.8.0/man/ronn-format.7.ronn000066400000000000000000000112141341056326200171560ustar00rootroot00000000000000ronn-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-ng-0.8.0/man/ronn.1000066400000000000000000000276711341056326200147250ustar00rootroot00000000000000.\" generated with Ronn-NG/v0.8.0 .\" http://github.com/apjanke/ronn-ng/tree/0.8.0 .TH "RONN" "1" "December 2018" "Ronn-NG 0.8.0" "Ronn Manual" .SH "NAME" \fBronn\fR \- convert markdown files to manpages .SH "SYNOPSIS" \fBronn\fR [\fIformat\fR\|\.\|\.\|\.] \fIfile\fR\|\.\|\.\|\. .br \fBronn\fR \fB\-m\fR|\fB\-\-man\fR \fIfile\fR\|\.\|\.\|\. .br \fBronn\fR \fB\-S\fR|\fB\-\-server\fR \fIfile\fR\|\.\|\.\|\. .br \fBronn\fR \fB\-\-pipe\fR \fIfile\fR .br \fBronn\fR < \fIfile\fR .SH "DESCRIPTION" \fBRonn\fR 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\. .P In its default mode, \fBronn\fR converts one or more input \fIfile\fRs to HTML or roff output files\. The \fB\-\-roff\fR, \fB\-\-html\fR, and \fB\-\-fragment\fR 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 \fIfile\fRs\. .P The \fB\-\-server\fR and \fB\-\-man\fR options change the output behavior from file generation to serving dynamically generated HTML manpages or viewing \fIfile\fR as with man(1)\. .P With no \fIfile\fR arguments, \fBronn\fR acts as simple filter\. Ronn source text is read from standard input and roff output is written to standard output\. Use the \fB\-\-html\fR, \fB\-\-roff\fR, and/or \fB\-\-fragment\fR options to select the output format\. .SH "FILES" The \fBronn\fR command expects input to be valid ronn\-format(7) text\. Source files are typically named \fIname\fR\.\fIsection\fR\.ronn (e\.g\., \fBexample\.1\.ronn\fR)\. The \fIname\fR and \fIsection\fR should match the name and section defined in the \fIfile\fR\'s heading\. .P When building roff or HTML output files, destination filenames are determined by taking the basename of the input \fIfile\fR and adding the appropriate file extension (or removing the file extension in the case of roff output)\. For example, executing \fBronn example\.1\.ronn\fR generates \fBexample\.1\fR with roff output and \fBexample\.1\.html\fR with HTML output\. .SH "OPTIONS" These options control whether output is written to file(s), standard output, or directly to a man pager\. .IP "\[ci]" 4 \fB\-m\fR, \fB\-\-man\fR: Don\'t generate files, display \fIfile\fRs 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 \fBMANPAGER\fR environment variable\. .IP "\[ci]" 4 \fB\-S\fR, \fB\-\-server\fR: Don\'t generate files, start an HTTP server at \fIhttp://localhost:1207/\fR and serve dynamically generated HTML for the set of input \fIfile\fRs\. A file named \fIexample\.2\.ronn\fR is served as \fI/example\.2\.html\fR\. There\'s also an index page at the root with links to each \fIfile\fR\. .IP The server respects the \fB\-\-style\fR and document attribute options (\fB\-\-manual\fR, \fB\-\-date\fR, etc\.)\. These same options can be varied at request time by giving them as query parameters: \fB?manual=FOO&style=dark,toc\fR .IP \fINOTE: 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\.\fR .IP "\[ci]" 4 \fB\-\-port\fR=\fIport\fR When used with \fB\-S\fR/\fB\-\-server\fR, runs the server at the specified port instead of the default port 1207\. .IP "\[ci]" 4 \fB\-\-pipe\fR: 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 \fIfile\fR arguments are provided\. .IP "\[ci]" 4 \fB\-o\fR=\fIdirectory\fR, \fB\-\-output\-dir\fR=\fIdirectory\fR: Write generated files to the specified directory instead of the default location\. .IP "" 0 .P Format options control the files \fBronn\fR generates, or the output format when the \fB\-\-pipe\fR argument is specified\. When no format options are given, both \fB\-\-roff\fR and \fB\-\-html\fR are assumed\. .TP \fB\-r\fR, \fB\-\-roff\fR Generate roff output\. This is the default behavior when no \fIfile\fRs are given and ronn source text is read from standard input\. .TP \fB\-5\fR, \fB\-\-html\fR Generate output in HTML format\. .TP \fB\-f\fR, \fB\-\-fragment\fR Generate output in HTML format but only the document fragment, not the header, title, or footer\. .P 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 \fIENVIRONMENT\fR\.) .TP \fB\-\-manual\fR=\fImanual\fR The name of the manual this man page belongs to; \fImanual\fR is prominently displayed top\-center in the header area\. .TP \fB\-\-organization\fR=\fIname\fR The name of the group, organization, or individual responsible for publishing the document; \fIname\fR is displayed in the bottom\-left footer area\. .TP \fB\-\-date\fR=\fIdate\fR The document\'s published date; \fIdate\fR must be formatted \fBYYYY\-MM\-DD\fR and is displayed in the bottom\-center footer area\. The \fIfile\fR mtime is used when no \fIdate\fR is given, or the current time when no \fIfile\fR is available\. .P HTML output can be customized through the use of CSS stylesheets: .TP \fB\-\-style\fR=\fImodule\fR[,\fImodule\fR]\|\.\|\.\|\. The list of CSS stylesheets to apply to the document\. Multiple \fImodule\fR arguments may be specified, but must be separated by commas or spaces\. .IP When \fImodule\fR is a simple word, search for files named \fImodule\fR\fB\.css\fR in all directories listed in the \fI\fBRONN_STYLE\fR\fR environment variable, and then search internal styles\. .IP When \fImodule\fR includes a \fI/\fR character, use it as the full path to a stylesheet file\. .IP Internal styles are \fIman\fR (included by default), \fItoc\fR, and \fI80c\fR\. See \fISTYLES\fR for descriptions of features added by each module\. .P Miscellaneous options: .TP \fB\-w\fR, \fB\-\-warnings\fR 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\. .TP \fB\-W\fR Disable troff warnings\. Warnings are disabled by default\. This option can be used to revert the effect of a previous \fB\-w\fR argument\. .TP \fB\-v\fR, \fB\-\-version\fR Show ronn version and exit\. .SH "LINK INDEXES" When generating HTML output, \fBronn\fR hyperlinks manual references (like \fBgrep(1)\fR, \fBls(1)\fR, \fBmarkdown(7)\fR) in source text based on reference name to URL mappings defined in an \fBindex\.txt\fR file\. Each line of the index file describes a single reference link, with whitespace separating the reference\'s \fIid\fR from its \fIlocation\fR\. Blank lines are allowed; lines beginning with a \fB#\fR character are ignored: .IP "" 4 .nf # 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/ .fi .IP "" 0 .P The \fIlocation\fR 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\. .P All manuals in an individual directory share the references defined in that directory\'s \fBindex\.txt\fR file\. Index references may be used explicitly in Markdown reference style links using the syntax: \fB[\fR\fItext\fR\fB][\fR\fIid\fR\fB]\fR, where \fItext\fR is the link text and \fIid\fR is a reference name defined in the index\. .SH "STYLES" The \fB\-\-style\fR 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\. .SS "Builtin Stylesheets" These styles are included with the distribution: .TP \fBman\fR Basic manpage styles: typography, definition lists, indentation\. This is always included regardless of \fB\-\-style\fR argument\. It is however possible to replace the default \fBman\fR module with a custom one by placing a \fBman\.css\fR file on the \fBRONN_STYLE\fR path\. .TP \fBprint\fR Basic print stylesheet\. The generated \fB