Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

clean up more references to ronn-format(7)

  • Loading branch information...
commit 42616b230091e5c11bfa2c0b2f613a0f2bf41656 1 parent 7500cc4
@rtomayko authored
View
112 README.md
@@ -1,46 +1,27 @@
-ronn -- the opposite of roff
-============================
+# Ronn
-## DESCRIPTION
-
-Ronn is a text format and toolchain for creating UNIX manpages. It converts
-markdown to standard UNIX roff manpages and formatted HTML manuals for the web.
+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
-includes extensions that provide features commonly found in manpages (definition
-lists, link notation, etc.). The ronn(5) manual page defines the format in
+syntax extensions for features commonly found in manpages (definition lists,
+link notation, etc.). The ronn-format(7) manual page defines the format in
detail.
-## DOCUMENTATION
-
-The `.ronn` files located under the `man/` directory show off a wide range of
-ronn capabilities and are the source of Ronn's own documentation. The source
-files and generated HTML / roff output files are available at:
+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) -
- convert markdown files to manpages.<br>
+ * [ronn(1)](http://rtomayko.github.com/ronn/ronn.1) command -
[source file](http://github.com/rtomayko/ronn/blob/master/man/ronn.1.ronn),
[roff output](http://github.com/rtomayko/ronn/blob/master/man/ronn.1)
- * [ronn(5)](http://rtomayko.github.com/ronn/ronn.5) -
- markdown-based text format for authoring manpages<br>
- [source file](http://github.com/rtomayko/ronn/blob/master/man/ronn.5.ronn),
- [roff output](http://github.com/rtomayko/ronn/blob/master/man/ronn.5)
-
-## INSTALL
-
-Install with Rubygems:
-
- $ [sudo] gem install ronn
- $ ronn --help
+ * [ronn-format(7)](http://rtomayko.github.com/ronn/ronn-format.7) -
+ [source file](http://github.com/rtomayko/ronn/blob/master/man/ronn-format.7.ronn),
+ [roff output](http://github.com/rtomayko/ronn/blob/master/man/ronn-format.7)
-Or, clone the git repository:
+[1]: http://github.com/rtomayko/ronn/tree/master/man
- $ git clone git://github.com/rtomayko/ronn.git
- $ PATH=ronn/bin:$PATH
- $ ronn --help
-
-## BASIC USAGE
+## Examples
Build roff and HTML output files for one or more input files:
@@ -48,10 +29,6 @@ Build roff and HTML output files for one or more input files:
roff: man/ronn.5
html: man/ronn.5.html
-View a roff manpage with man(1):
-
- $ man man/ronn.5
-
Generate only a standalone HTML version of one or more files:
$ ronn --html man/markdown.5.ronn
@@ -65,56 +42,53 @@ 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.
-## ABOUT
+## Background
-Some people say UNIX manual pages are a poor and outdated style of
-documentation. I disagree:
+Some think UNIX manual pages are a poor and outdated form of documentation. I
+disagree:
-- Man pages follow a well defined structure that's immediately familiar. This
- provides developers with a useful starting point when documenting new tools,
- libraries, and formats.
+- Manpages follow a well defined structure that's immediately familiar. This
+ gives developers a starting point when documenting new tools, libraries, and
+ formats.
-- Man pages get to the point. Because they're written in an inverted style, with
+- 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, man pages provide the best of both cheat sheet
+ other sources of information, manpages provide the best of both cheat sheet
and reference style documentation.
-- Man pages have extremely -- unbelievably -- limited text formatting
- capabilities. You get a couple of headings, lists, bold, underline and no
- more. This is a feature.
+- 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 man
- pages use only a single level. Unwieldy document hierarchies complicate
- otherwise good documentation. Feynman covered all of physics -- heavenly
- bodies through QED -- with only two levels of document hierarchy (_The Feynman
- Lectures on Physics_, 1970).
-
-- Man pages have a simple referencing syntax; e.g., sh(1), fork(2), markdown(7).
- HTML versions can use this to generate links between pages.
+- 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 man page display is typographically well thought out.
+- 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/man macro languages are highly extensible, fractured between multiple
-dialects, and include a bunch of device specific stuff irrelevant to modern
-publishing tools.
+The roff/mandoc/mdoc macro languages are highly extensible, fractured between
+multiple dialects, and include a bunch of device specific stuff irrelevant to
+modern publishing tools.
-Ronn aims to address many of the issues with manpage creation while preserving
-the things that makes manpages a great form of documentation.
+Ronn aims
-## COPYING
+## Copying
-Ronn is Copyright (C) 2009 [Ryan Tomayko](http://tomayko.com/about)<br>
+Ronn is Copyright (C) 2010 [Ryan Tomayko](http://tomayko.com/about)<br>
See the file COPYING for information of licensing and distribution.
-
-## SEE ALSO
-
-[ronn(1)](http://rtomayko.github.com/ronn/ronn.1),
-[ronn(5)](http://rtomayko.github.com/ronn/ronn.5),
-markdown(7)
View
16 man/ronn-format.7
@@ -23,14 +23,14 @@ 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 or
-underline\.
+boldface; <variable>, _emphasis_, *emphasis*, are displayed in italics
+(HTML) or underline (roff)\.
-Manual references like sh(1), markdown(7), roff(7), etc\. are displayed in
-boldface and hyperlinked in HTML output\.
+Manual references like sh(1), markdown(7), roff(7), etc\. are hyperlinked in
+HTML output\.
-Link to other sections like [STANDARDS][], [SEE ALSO][], or
-[WITH A DIFFERENT LINK TEXT][#SEE\-ALSO]\.
+Link to sections like [STANDARDS][], [SEE ALSO][], or [WITH A DIFFERENT LINK
+TEXT][#SEE\-ALSO]\.
Definition lists:
@@ -40,8 +40,6 @@ Definition lists:
* You can put whatever you *want* here, really:
Nesting and paragraph spacing are respected\.
-Markdown ordered and unordered lists too\.
-
Frequently used sections:
## OPTIONS
@@ -127,7 +125,7 @@ Also displayed in boldface\. Unlike backticks, inline markup is processed\. HTML
.
.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<\fR\.
+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)
View
16 man/ronn-format.7.ronn
@@ -16,14 +16,14 @@ ronn-format(7) -- manual authoring format based on Markdown
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 or
- underline.
+ boldface; <variable>, _emphasis_, *emphasis*, are displayed in italics
+ (HTML) or underline (roff).
- Manual references like sh(1), markdown(7), roff(7), etc. are displayed in
- boldface and hyperlinked in HTML output.
+ Manual references like sh(1), markdown(7), roff(7), etc. are hyperlinked in
+ HTML output.
- Link to other sections like [STANDARDS][], [SEE ALSO][], or
- [WITH A DIFFERENT LINK TEXT][#SEE-ALSO].
+ Link to sections like [STANDARDS][], [SEE ALSO][], or [WITH A DIFFERENT LINK
+ TEXT][#SEE-ALSO].
Definition lists:
@@ -33,8 +33,6 @@ ronn-format(7) -- manual authoring format based on Markdown
* You can put whatever you *want* here, really:
Nesting and paragraph spacing are respected.
- Markdown ordered and unordered lists too.
-
Frequently used sections:
## OPTIONS
@@ -103,7 +101,7 @@ Ronn uses the following bits of markdown(7) to accomplish this:
* `<anglequotes>` (non-compatible markdown extension):
User-specified arguments, variables, or user input. Typically displayed with
- <u>underline</u> in roff output. HTML output: `<var>`.
+ <u>underline</u> in roff output. HTML output: `<var/>`.
* `_`_underbars_`_` (markdown compatible):
Emphasis. May be used for literal option values. Typically displayed with
View
14 man/ronn.1
@@ -22,25 +22,25 @@
\fBronn\fR < \fIfile\fR
.
.SH "DESCRIPTION"
-\fBRonn\fR converts Markdown input to standard roff\-formatted UNIX manpages or manpage styled HTML\. The ronn(5) source format is based on markdown(7) but includes additional rules and syntax geared toward authoring manuals\.
+\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 UNIX 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\.
+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 output file generation to serving dynamically generated HTML manpages or viewing \fIfile\fR as with man(1)\.
+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\. The \fB\-\-html\fR and \fB\-\-fragment\fR options can be used to generate that format output instead of roff\.
+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 formatted as ronn(5) 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\.
+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 files, standard output, or directly to a man pager\.
+These options control whether output is written to file(s), standard output, or directly to a man pager\.
.
.TP
\fB\-m\fR, \fB\-\-man\fR
@@ -294,4 +294,4 @@ Used instead of \fBMANPAGER\fR when \fBMANPAGER\fR is not defined\.
Ronn is Copyright (C) 2009 Ryan Tomayko \fIhttp://tomayko\.com/about\fR
.
.SH "SEE ALSO"
-ronn(5), manpages(5), man(1), roff(7), groff(1), markdown(7)
+ronn\-format(7), manpages(5), man(1), roff(7), groff(1), markdown(7)
View
30 man/ronn.1.ronn
@@ -11,31 +11,29 @@ ronn(1) -- convert markdown files to manpages
## DESCRIPTION
-**Ronn** converts Markdown input to standard roff-formatted UNIX manpages or
-manpage styled HTML. The ronn(5) source format is based on markdown(7) but
-includes additional rules and syntax geared toward authoring manuals.
+**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 UNIX
-roff output files. The `--roff`, `--html`, and `--fragment` options dictate
-which output files are generated. Multiple format arguments may be specified to
+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 output file
+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. The `--html`
-and `--fragment` options can be used to generate that format output instead of
-roff.
+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 formatted as ronn(5) 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.
+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.
When building roff or HTML output files, destination filenames are determined by
taking the basename of the input <file> and adding the appropriate file
@@ -45,7 +43,7 @@ and `example.1.html` with HTML output.
## OPTIONS
-These options control whether output is written to files, standard output, or
+These options control whether output is written to file(s), standard output, or
directly to a man pager.
* `-m`, `--man`:
@@ -275,4 +273,4 @@ Ronn is Copyright (C) 2009 Ryan Tomayko <http://tomayko.com/about>
## SEE ALSO
-ronn(5), manpages(5), man(1), roff(7), groff(1), markdown(7)
+ronn-format(7), manpages(5), man(1), roff(7), groff(1), markdown(7)
Please sign in to comment.
Something went wrong with that request. Please try again.