nronn 0.10.1.pre2

data/man/ronn.1.ronn

@@ -0,0 +1,316 @@
+ronn(1) -- convert markdown files to manpages
+=============================================
+
+## SYNOPSIS
+
+`ronn` [<format>...] <file>...<br>
+`ronn` `-m`|`--man` <file>...<br>
+`ronn` `-S`|`--server` <file>...<br>
+`ronn` `--pipe` <file><br>
+`ronn` &lt; <file><br>
+`ronn` `-E`|`--encoding` <encoding> ...
+
+## 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 <file>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 <file>s.
+
+The `--server` and `--man` options change the output behavior from file
+generation to serving dynamically generated HTML manpages or viewing <file> as
+with man(1).
+
+With no <file> 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 <name>.<section>.ronn (e.g., `example.1.ronn`).  The <name>
+and <section> should match the name and section defined in the <file>'s heading.
+
+Source files must be in UTF-8 encoding, or the encoding specified by the
+`-E`/`--encoding` option, regardless of the locale that `ronn` is running under.
+
+When building roff or HTML output files, destination filenames are determined by
+taking the basename of the input <file> and adding the appropriate file
+extension (or removing the file extension in the case of roff output).  For
+example, 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 <file>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 <http://localhost:1207/> and
+    serve dynamically generated HTML for the set of input <file>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 <file>.
+
+    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.*
+
+  * `--port`=<port>
+    When used with `-S`/`--server`, runs the server at the specified port instead
+    of the default port 1207.
+
+  * `--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
+    <file> arguments are provided.
+
+  * `-o`=<directory>, `--output-dir`=<directory>:
+    Write generated files to the specified directory instead of the default
+    location.
+  
+  * `-E`=<encoding>, `--encoding`=<encoding:
+    Specify the encoding that input files are in. Default is UTF-8, regardless
+    of user's locale settings. Input sent to STDIN is always treated as UTF-8,
+    regardless of whether `-E` is passed.
+
+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 <file>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`=<manual>:
+    The name of the manual this man page belongs to; <manual> is prominently
+    displayed top-center in the header area.
+
+  * `--organization`=<name>:
+    The name of the group, organization, or individual responsible for
+    publishing the document; <name> is displayed in the bottom-left footer area.
+
+  * `--date`=<date>:
+    The document's published date; <date> must be formatted `YYYY-MM-DD` and is
+    displayed in the bottom-center footer area. The <file> mtime is used when no
+    <date> is given, or the current time when no <file> is available.
+
+HTML output can be customized through the use of CSS stylesheets:
+
+  * `--style`=<module>[,<module>]...:
+    The list of CSS stylesheets to apply to the document. Multiple <module>
+    arguments may be specified, but must be separated by commas or spaces.
+
+    When <module> is a simple word, search for files named <module>`.css` in all
+    directories listed in the [`RONN_STYLE`](#ENVIRONMENT) environment variable,
+    and then search internal styles.
+
+    When <module> 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 <id> from its
+<location>. 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          https://github.com/
+
+The <location> 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: `[`<text>`][`<id>`]`, where
+<text> is the link text and <id> 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 `<style>` tag includes a
+     `media=print` attribute.
+
+   * `toc`:
+     Enables the Table of Contents navigation. The TOC markup is included in
+     generated HTML by default but hidden with an inline `display:none` style
+     rule; the `toc` module turns it on and applies basic TOC styles.
+
+   * `dark`:
+     Light text on a dark background.
+
+   * `80c`:
+     Changes the display width to mimic the display of a classic 80 character
+     terminal. The default display width causes lines to wrap at a gratuitous
+     100 characters.
+
+### Custom Stylesheets
+
+Writing custom stylesheets is straight-forward. The following core selectors
+allow targeting all generated elements:
+
+   * `.mp`:
+     The manual page container element. Present on full documents and document
+     fragments.
+
+   * `body#manpage`:
+     Signifies that the page was fully-generated by Ronn and contains a single
+     manual page (`.mp` element).
+
+   * `.man-decor`:
+     The three-item heading and footing elements both have this class.
+
+   * `.man-head`, `.man-foot`:
+     The heading and footing, respectively.
+
+   * `.man-title`:
+     The main `<h1>` element. Hidden by default unless the manual has no <name>
+     or <section> attributes.
+
+See the [builtin style sources][builtin] for examples.
+
+[builtin]: https://github.com/n-ronn/nronn/tree/master/lib/ronn/template
+          "Builtin Stylesheet .css files"
+
+## EXAMPLES
+
+Build roff and HTML output files and view the roff manpage using man(1):
+
+    $ ronn some-great-program.1.ronn
+    roff: some-great-program.1
+    html: some-great-program.1.html
+    $ man ./some-great-program.1
+
+Build only the roff manpage for all `.ronn` files in the current directory:
+
+    $ ronn --roff *.ronn
+    roff: mv.1
+    roff: ls.1
+    roff: cd.1
+    roff: sh.1
+
+Build only the HTML manpage for a few files and apply the `dark` and `toc`
+stylesheets:
+
+    $ ronn --html --style=dark,toc mv.1.ronn ls.1.ronn
+    html: mv.1.html
+    html: ls.1.html
+
+Generate roff output on standard output and write to file:
+
+    $ ronn <hello.1.ronn >hello.1
+
+View a ronn file in the same way as man(1) without building a roff file:
+
+    $ ronn --man hello.1.ronn
+
+Serve HTML manpages at <http://localhost:1207/> for all `*.ronn` files
+under a `man/` directory:
+
+    $ ronn --server man/*.ronn
+    $ open http://localhost:1207/
+
+
+## ENVIRONMENT
+
+  * `RONN_MANUAL`:
+    A default manual name to be displayed in the top-center header area.
+    The `--manual` option takes precedence over this value.
+
+  * `RONN_ORGANIZATION`:
+    The default manual publishing group, organization, or individual to be
+    displayed in the bottom-left footer area. The `--organization` option takes
+    precedence over this value.
+
+  * `RONN_DATE`:
+    The default manual date in `YYYY-MM-DD` format. Displayed in the
+    bottom-center footer area. The `--date` option takes precedence over this
+    value.
+
+  * `RONN_STYLE`:
+    A `PATH`-style list of directories to check for stylesheets given to the
+    `--style` option. Directories are separated by a _:_; blank entries are
+    ignored. Use _._ to include the current working directory.
+
+  * `MANPAGER`:
+    The paging program used for man pages. This is typically set to
+    something like 'less -is'.
+
+  * `PAGER`:
+    Used instead of `MANPAGER` when `MANPAGER` is not defined.
+
+## COPYRIGHT
+
+See [LICENSE.txt](./LICENSE.txt)
+
+## SEE ALSO
+
+groff(1), man(1), pandoc(1), manpages(5), markdown(7), roff(7), ronn-format(7)

data/nronn.gemspec

@@ -0,0 +1,136 @@
+Gem::Specification.new do |s|
+  s.name = 'nronn'
+  s.version = '0.10.1.pre2'
+  s.date = '2022-08-01'
+  s.required_ruby_version = '>= 2.4'
+
+  s.summary     = 'Builds man pages from Markdown'
+  s.description = 'nronn builds manuals in HTML and Unix man page format from Markdown.'
+  s.homepage    = 'https://github.com/n-ronn/ronn'
+  s.license     = 'MIT'
+
+  s.authors     = ['Takuya Noguchi']
+  s.email       = ['']
+
+  s.metadata = {
+    'bug_tracker_uri'   => 'https://github.com/n-ronn/nronn/issues',
+    'source_code_uri'   => 'https://github.com/n-ronn/nronn',
+    'changelog_uri'     => 'https://github.com/n-ronn/nronn/blob/master/CHANGES'
+  }
+
+  # = MANIFEST =
+  s.files = %w[
+    AUTHORS
+    CHANGES
+    Gemfile
+    Gemfile.lock
+    INSTALLING.md
+    LICENSE.txt
+    README.md
+    Rakefile
+    bin/ronn
+    completion/bash/ronn
+    completion/zsh/_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
+    nronn.gemspec
+    test/angle_bracket_syntax.html
+    test/angle_bracket_syntax.roff
+    test/angle_bracket_syntax.ronn
+    test/backticks.html
+    test/backticks.ronn
+    test/basic_document.html
+    test/basic_document.ronn
+    test/circumflexes.ronn
+    test/code_blocks.html
+    test/code_blocks.roff
+    test/code_blocks.ronn
+    test/code_blocks_regression
+    test/code_blocks_regression.html
+    test/code_blocks_regression.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/ellipses.roff
+    test/ellipses.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/nested_list.ronn
+    test/nested_list_with_code.html
+    test/nested_list_with_code.roff
+    test/nested_list_with_code.ronn
+    test/ordered_list.html
+    test/ordered_list.roff
+    test/ordered_list.ronn
+    test/page.with.periods.in.name.5.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/single_quotes.html
+    test/single_quotes.roff
+    test/single_quotes.ronn
+    test/tables.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[LICENSE.txt AUTHORS]
+  s.add_dependency 'kramdown',              '~> 2.1'
+  s.add_dependency 'kramdown-parser-gfm',   '~> 1.0.1'
+  s.add_dependency 'mustache',              '~> 1.0'
+  s.add_dependency 'nokogiri',              '~> 1.11', '>= 1.11.0'
+  s.add_development_dependency 'rack',      '~> 2.2',  '>= 2.2.3'
+  s.add_development_dependency 'rake',      '~> 12.3', '>= 12.3.3'
+  s.add_development_dependency 'rubocop',   '~> 0.88', '>= 0.88.0'
+  s.add_development_dependency 'sinatra',   '~> 2.0',  '>= 2.0.8'
+  s.add_development_dependency 'test-unit', '~> 3.3',  '>= 3.3.6'
+
+  s.rdoc_options = ['--line-numbers', '--inline-source', '--title', 'Ronn']
+  s.require_paths = %w[lib]
+end

data/test/angle_bracket_syntax.html

@@ -0,0 +1,27 @@
+<div class='mp'>
+
+<h2 id="NAME">NAME</h2>
+<p class="man-name">
+  <code>angle_bracket_syntax</code> - <span class="man-whatis">angle bracket syntax test</span>
+</p>
+<p>A <var>WORD</var> in angle brackets is converted to <var>WORD</var>,</p>
+
+<pre><code>except when &lt;WORD&gt; is
+part of a preformatted
+code block,
+</code></pre>
+
+<p>or when <code>&lt;WORD&gt;</code> is enclosed in backticks.</p>
+
+<p>or when <var>WORD</var> has a <dot.> or <colon>.</colon></dot.></p>
+
+<h2 id="Escaping-angle-brackets">Escaping angle brackets</h2>
+
+<p>You can escape &lt;angle&gt; &lt;brackets&gt; with backslashes, since we're using GitHub Flavored Markdown.</p>
+
+<p>Example:</p>
+
+<p><code>pxzgrep</code> [<code>-p</code>&lt;n&gt;] [<code>-V</code>] [&lt;xzgrep options&gt;] &lt;pattern&gt; &lt;file1&gt; &lt;file2&gt; [&lt;more files&gt;]</p>
+
+<p>(Though really you should just put that in a fenced code block.)</p>
+</div>

data/test/angle_bracket_syntax.roff

@@ -0,0 +1,24 @@
+.TH "ANGLE_BRACKET_SYNTAX" "5" "January 1979" ""
+.SH "NAME"
+\fBangle_bracket_syntax\fR \- angle bracket syntax test
+.P
+A \fIWORD\fR in angle brackets is converted to \fIWORD\fR,
+.IP "" 4
+.nf
+except when <WORD> is
+part of a preformatted
+code block,
+.fi
+.IP "" 0
+.P
+or when \fB<WORD>\fR is enclosed in backticks\.
+.P
+or when \fIWORD\fR has a
+.SH "Escaping angle brackets"
+You can escape <angle> <brackets> with backslashes, since we're using GitHub Flavored Markdown\.
+.P
+Example:
+.P
+\fBpxzgrep\fR [\fB\-p\fR<n>] [\fB\-V\fR] [<xzgrep options>] <pattern> <file1> <file2> [<more files>]
+.P
+(Though really you should just put that in a fenced code block\.)

data/test/angle_bracket_syntax.ronn

@@ -0,0 +1,22 @@
+angle_bracket_syntax(5) -- angle bracket syntax test
+====================================================
+
+A <WORD> in angle brackets is converted to <var>WORD</var>,
+
+    except when <WORD> is
+    part of a preformatted
+    code block,
+
+or when `<WORD>` is enclosed in backticks.
+
+or when <WORD> has a <dot.> or <foo:colon>.
+
+## Escaping angle brackets
+
+You can escape \<angle\> \<brackets\> with backslashes, since we're using GitHub Flavored Markdown.
+
+Example:
+
+`pxzgrep` [`-p`\<n\>] [`-V`] [\<xzgrep options\>] \<pattern\> \<file1\> \<file2\> [\<more files\>]
+
+(Though really you should just put that in a fenced code block.)

data/test/backticks.html

@@ -0,0 +1,14 @@
+<div class='mp'>
+
+<h2 id="NAME">NAME</h2>
+<p class="man-name">
+  <code>backticks</code> - <span class="man-whatis">testing the link index with backticks</span>
+</p>
+<p><a class="man-ref" href="http://man.cx/grep(1)">grep<span class="s">(1)</span></a></p>
+
+<p><a class="man-ref" href="http://man.cx/grep(1)"><code>grep</code><span class="s">(1)</span></a></p>
+
+<p><span class="man-ref">man<span class="s">(1)</span></span></p>
+
+<p><span class="man-ref"><code>man</code><span class="s">(1)</span></span></p>
+</div>

data/test/backticks.ronn

@@ -0,0 +1,10 @@
+backticks(7) -- testing the link index with backticks
+=====================================================
+
+grep(1)
+
+`grep`(1)
+
+man(1)
+
+`man`(1)

data/test/basic_document.html

@@ -0,0 +1,8 @@
+<div class='mp'>
+
+<h2 id="NAME">NAME</h2>
+<p class="man-name">
+  <code>simple</code> - <span class="man-whatis">a simple ronn example</span>
+</p>
+<p>This document created by ronn.</p>
+</div>

data/test/basic_document.ronn

@@ -0,0 +1,4 @@
+simple(7) -- a simple ronn example
+=================================
+
+This document created by ronn.

data/test/circumflexes.ronn

@@ -0,0 +1 @@
+y = 2^x

data/test/code_blocks.html

@@ -0,0 +1,38 @@
+<div class='mp'>
+
+<h1 id="Example-Code-Blocks">Example Code Blocks</h1>
+<h2 id="Basic-code-block">Basic code block</h2>
+
+<pre><code>Hello, world!
+</code></pre>
+
+<h2 id="Language-identified-code-blocks">Language-identified code blocks</h2>
+
+<pre><code class="language-html">&lt;html&gt;
+  &lt;head&gt;
+    &lt;title&gt;Hello, world!&lt;/title&gt;
+  &lt;/head&gt;
+  &lt;body&gt;
+    Hello, world!
+  &lt;/body&gt;
+&lt;/html&gt;
+</code></pre>
+
+<h2 id="Interspersed-code-blocks-and-text">Interspersed code blocks and text</h2>
+
+<p>Some text.</p>
+
+<pre><code>Some code.
+</code></pre>
+
+<p>Here's some &lt;pre&gt; text.</p>
+
+<pre>
+    This is pre text.
+</pre>
+
+<p>Some more text.</p>
+
+<pre><code>Some more code.
+</code></pre>
+</div>

data/test/code_blocks.roff

@@ -0,0 +1,38 @@
+.TH "CODE_BLOCKS" "" "January 1979" ""
+.SH "Basic code block"
+.nf
+Hello, world!
+.fi
+.SH "Language\-identified code blocks"
+.nf
+<html>
+  <head>
+    <title>Hello, world!</title>
+  </head>
+  <body>
+    Hello, world!
+  </body>
+</html>
+.fi
+.SH "Interspersed code blocks and text"
+Some text\.
+.IP "" 4
+.nf
+Some code\.
+.fi
+.IP "" 0
+.P
+Here's some <pre> text\.
+.IP "" 4
+.nf
+    This is pre text\.
+.fi
+.IP "" 0
+.P
+Some more text\.
+.IP "" 4
+.nf
+Some more code\.
+.fi
+.IP "" 0
+

data/test/code_blocks.ronn

@@ -0,0 +1,41 @@
+Example Code Blocks
+===================
+
+## Basic code block
+
+```
+Hello, world!
+```
+
+## Language-identified code blocks
+
+```html
+<html>
+  <head>
+    <title>Hello, world!</title>
+  </head>
+  <body>
+    Hello, world!
+  </body>
+</html>
+```
+
+## Interspersed code blocks and text
+
+Some text.
+
+```
+Some code.
+```
+
+Here's some &lt;pre> text.
+
+<pre>
+    This is pre text.
+</pre>
+
+Some more text.
+
+```
+Some more code.
+```