Popularity
3.2
Growing
Activity
0.0
Stable
1,176
25
74

Description

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/ directory show off a wide range of ronn capabilities:

Code Quality Rank: L5
Monthly Downloads: 58,633
Programming language: Ruby
Tags: Documentation    
Latest version: v0.7.3

Ronn alternatives and similar libraries

Based on the "Documentation" category

  • sphinx

    6.4 9.8 L2 Ronn VS sphinx
    a tool that makes it easy to create intelligent and beautiful documentation
  • Beautiful docs

    is a documentation viewer based on markdown files.
  • documentation.js

    API documentation generator with support for ES2015+ and flow annotation.
  • docco

    is a quick-and-dirty, hundred-line-long, literate-programming-style documentation generator.
  • ESDoc

    4.7 0.0 L2 Ronn VS ESDoc
    is a good documentation generator for JavaScript.
  • dox

    4.3 1.8 L4 Ronn VS dox
    is a JavaScript documentation generator written with node. Dox no longer generates an opinionated structure or style for your docs, it simply gives you a JSON representation, allowing you to use markdown and JSDoc-style tags.
  • codecrumbs

    is a visual tool for learning and documenting a codebase by putting breadcrumbs in source code.
  • jsduck

    4.0 0.0 L4 Ronn VS jsduck
    API documentation generator made for Sencha JavaScript frameworks, but can be used for other frameworks too.
  • YUIDoc

    is a Node.js application that generates API documentation from comments in source, using a syntax similar to tools like Javadoc and Doxygen.
  • styledocco

    generates documentation and style guide documents from your stylesheets.
  • dexy

    2.1 6.1 L4 Ronn VS dexy
    is a free-form literate documentation tool for writing any kind of technical document incorporating code.
  • jsdox

    1.9 0.0 L4 Ronn VS jsdox
    is a JSDoc3 to Markdown documentation generator.
  • ip-num

    A TypeScript library for working with ASN, IPv4, and IPv6 numbers.
  • coddoc

    0.3 0.1 L4 Ronn VS coddoc
    is a jsdoc parsing library. Coddoc is different in that it is easily extensible by allowing users to add tag and code parsers through the use of coddoc.addTagHandler and coddoc.addCodeHandler. coddoc also parses source code to be used in APIs.
  • DevDocs

    is an all-in-one API documentation reader with a fast, organized, and consistent interface.

Do you think we are missing an alternative of Ronn or a related project?

Add another 'Documentation' Library

README

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/ directory show off a wide range of ronn capabilities:

As an alternative, you might want to check out pandoc which can also convert markdown into roff manual pages.

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) 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.

Copying

Ronn is Copyright (C) 2010 Ryan Tomayko See the file COPYING for information of licensing and distribution.