nronn 0.10.1.pre2

data/lib/ronn/template/screen.css

@@ -0,0 +1,105 @@
+/* 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 }

data/lib/ronn/template/toc.css

@@ -0,0 +1,27 @@
+/* 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;
+}

data/lib/ronn/template.rb

@@ -0,0 +1,173 @@
+require 'mustache'
+
+module Ronn
+  # A Mustache Template for HTML formatting.
+  class Template < Mustache
+    self.template_path = File.dirname(__FILE__) + '/template'
+    self.template_extension = 'html'
+
+    def initialize(document, style_path = ENV['RONN_STYLE'].to_s.split(':'))
+      super()
+      @document = document
+      @style_path = style_path + [Template.template_path]
+    end
+
+    def render(template = 'default')
+      super template[0, 1] == '/' ? File.read(template) : partial(template)
+    end
+
+    ##
+    # Basic document attributes
+
+    def name
+      @document.name
+    end
+
+    def section
+      @document.section
+    end
+
+    def tagline
+      @document.tagline
+    end
+    alias tagline? tagline
+
+    def name_and_section?
+      name && section
+    end
+
+    def title
+      if !name_and_section? && tagline
+        tagline
+      else
+        [page_name, tagline].compact.join(' - ')
+      end
+    end
+
+    def custom_title?
+      !name_and_section? && tagline
+    end
+
+    def page_name
+      if section
+        "#{name}(#{section})"
+      else
+        name
+      end
+    end
+
+    def generator
+      "nRonn/v#{Ronn.version} (https://github.com/n-ronn/nronn/tree/#{Ronn.revision})"
+    end
+
+    def manual
+      @document.manual
+    end
+
+    def organization
+      @document.organization
+    end
+
+    def date
+      @document.date.strftime('%B %Y')
+    end
+
+    def wrap_class_name
+      'mp'
+    end
+
+    ##
+    # Section TOCs
+
+    def section_heads
+      @document.section_heads.map do |id, text|
+        {
+          id:   id,
+          text: text
+        }
+      end
+    end
+
+    ##
+    # Styles
+
+    # Array of style module names as given on the command line.
+    def styles
+      @document.styles
+    end
+
+    # Array of stylesheet info hashes.
+    def stylesheets
+      styles.zip(style_files).map do |name, path|
+        base = File.basename(path, '.css')
+        raise "style not found: #{style.inspect}" if path.nil?
+        {
+          name:  name,
+          path:  path,
+          base:  File.basename(path, '.css'),
+          media: base =~ /(print|screen)$/ ? $1 : 'all'
+        }
+      end
+    end
+
+    # All embedded stylesheets.
+    def stylesheet_tags
+      stylesheets
+        .map { |style| inline_stylesheet(style[:path], style[:media]) }
+        .join("\n  ")
+    end
+
+    attr_accessor :style_path
+
+    # Array of expanded stylesheet file names. If a file cannot be found, the
+    # resulting array will include nil elements in positions corresponding to
+    # the stylesheets array.
+    def style_files
+      styles.map do |name|
+        next name if name.include?('/')
+        style_path
+          .reject     { |p| p.strip.empty? }
+          .map     { |p| File.join(p, "#{name}.css") }
+          .detect  { |file| File.exist?(file) }
+      end
+    end
+
+    # Array of style names for which no file could be found.
+    def missing_styles
+      style_files
+        .zip(files)
+        .select { |_style, file| file.nil? }
+        .map    { |style, _file| style }
+    end
+
+    ##
+    # TEMPLATE CSS LOADING
+
+    def inline_stylesheet(path, media = 'all')
+      data = File.read(path)
+      data.gsub!(%r{/\*.+?\*/}m, '')   # comments
+      data.gsub!(/([;{,]) *\n/m, '\1') # end-of-line whitespace
+      data.gsub!(/\n{2,}/m, "\n")      # collapse lines
+      data.gsub!(/[; ]+\}/, '}')       # superfluous trailing semi-colons
+      data.gsub!(/([{;,+])[ ]+/, '\1') # whitespace around things
+      data.gsub!(/[ \t]+/m, ' ')       # coalescing whitespace elsewhere
+      data.gsub!(/^/, '  ')            # indent
+      data.strip!
+      [
+        "<style type='text/css' media='#{media}'>",
+        "/* style: #{File.basename(path, '.css')} */",
+        data,
+        '</style>'
+      ].join("\n  ")
+    end
+
+    def remote_stylesheet(name, media = 'all')
+      path = File.expand_path("../template/#{name}.css", __FILE__)
+      "<link rel='stylesheet' type='text/css' media='#{media}' href='#{path}'>"
+    end
+
+    def stylesheet(_path, media = 'all')
+      inline_stylesheet(name, media)
+    end
+  end
+end

data/lib/ronn/utils.rb

@@ -0,0 +1,57 @@
+require '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

data/lib/ronn.rb

@@ -0,0 +1,47 @@
+# 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
+
+  # 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
+
+  # The string revision as reported by: git-describe --tags. This is just the
+  # tag name when a tag references the HEAD commit (e.g. 0.6.25). When the HEAD
+  # commit is not tagged, this is a "<tag>-<offset>-<sha1>" string:
+  #   <tag>    - closest tag name
+  #   <offset> - number of commits ahead of <tag>
+  #   <sha1>   - 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.10.1.pre1'.freeze
+  VERSION = version
+end

data/man/index.html

@@ -0,0 +1,78 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Ronn</title>
+  <style>
+    body {
+      font-size:24px;
+      line-height:1.5;
+      font-family:georgia,serif;
+      color:#555;
+    }
+    div#index {
+      width:28em;
+      margin:0 auto;
+    }
+    h1 {
+      text-align:center;
+      font-weight:normal;
+      color:#000;
+      margin-bottom:0;
+      letter-spacing:-3px;
+    }
+    h3 {
+      text-align:center;
+      font-weight:normal;
+      color:#444;
+      margin-top:-20px;
+      margin-bottom:40px;
+    }
+    h4 {
+      font-weight:normal;
+      font-size:26px;
+      color:#111;
+    }
+    p, dl    { margin-left:40px }
+    .aux     { font-family:monospace;font-size:20px;letter-spacing:1px; }
+    .also    { font-size:18px }
+    .copy    { font-size:16px;text-align:center;color:#111 }
+    .man-ref { font-family:monospace;letter-spacing:-2px; }
+  </style>
+</head>
+<body>
+<div id='index'>
+  <h1>Ronn</h1>
+  <h3>Builds manuals</h3>
+
+  <h4>Auxiliary</h4>
+  <p class='aux'>
+    <a href='http://github.com/apjanke/ronn-ng#readme'>README</a>,
+    <a href='http://github.com/apjanke/ronn-ng/blob/master/INSTALLING#files'>INSTALLING</a>,
+    <a href='http://github.com/apjanke/ronn-ng/blob/master/CHANGES#files'>CHANGES</a>,
+    <a href='http://github.com/apjanke/ronn-ng/blob/master/COPYING#files'>COPYING</a>,
+    <a href='http://github.com/apjanke/ronn-ng/blob/master/AUTHORS#files'>AUTHORS</a>
+  </p>
+
+  <h4>Manuals</h4>
+  <dl>
+    <dt><a class='man-ref' href='ronn.1.html'>ronn(1)</a></dt>
+    <dd>manual authoring tool</dd>
+
+    <dt><a class='man-ref' href='ronn-format.7.html'>ronn-format(7)</a></dt>
+    <dd>markdown-based text format for authoring manpages</dd>
+  </dl>
+
+  <h4>See Also</h4>
+  <p class='also'>
+    <a class='man-ref' href="http://developer.apple.com/mac/library/documentation/Darwin/Reference/ManPages/man5/manpages.5.html">manpages(5)</a>,
+    <a class='man-ref' href="http://daringfireball.net/projects/markdown/syntax">markdown(7)</a>,
+    <a class='man-ref' href="http://man.cx/man(1)">man(1)</a>,
+    <a class='man-ref' href="http://man.cx/roff(7)">roff(7)</a>,
+    <a class='man-ref' href="http://man.cx/groff(1)">groff(1)</a>,
+    <a class='man-ref' href="http://mustache.github.com/mustache.5.html">mustache(5)</a>
+  </p>
+
+  <p class='copy'>Copyright &copy; 2010 Ryan Tomayko, &copy; 2018 Andrew Janke</p>
+</div>
+</body>
+</html>

data/man/index.txt

@@ -0,0 +1,15 @@
+# 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

data/man/ronn-format.7

@@ -0,0 +1,145 @@
+.\" generated with nRonn/v0.10.1
+.\" https://github.com/n-ronn/nronn/tree/0.10.1.pre1
+.TH "RONN\-FORMAT" "7" "December 2018" "nRonn 0.10.1.pre1" "Ronn Manual"
+.SH "NAME"
+\fBronn\-format\fR \- manual authoring format based on Markdown
+.SH "SYNOPSIS"
+.nf
+name(1) \-\- short, single\-sentence description
+=============================================
+
+## SYNOPSIS
+
+`name` [<optional>\|\.\|\.\|\.] <flags>
+
+## 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; <variable>, _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`=[<value>]:
+    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\e`backticks\e`\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<code>\fR\.
+.TP
+\fB**double\-stars**\fR (markdown compatible)
+Also displayed in boldface\. Unlike backticks, inline markup is processed\. HTML output: \fB<strong>\fR\.
+.TP
+\fB<anglequotes>\fR (non\-compatible markdown extension)
+User\-specified arguments, variables, or user input\. Typically displayed with \fIunderline\fR in roff output\. HTML output: \fB<var/>\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<em>\fR\.
+.P
+Here is grep(1)'s DESCRIPTION section represented in \fBronn\fR:
+.IP "" 4
+.nf
+`Grep` searches the named input <FILE> (or standard input if
+no files are named, or the file name `\-` is given) for lines
+containing a match to the given <PATTERN>\. By default, `grep`
+prints the matching lines\.
+.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` <file>:
+     True if <file> exists and is a block special file\.
+
+   * `\-c` <file>:
+     True if _file_ exists and is a character special file\.
+
+   * `\-d` <file>:
+     True if file exists and is a directory\.
+.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)