Permalink
Browse files

document link indexes in ronn(1)

  • Loading branch information...
1 parent da46247 commit a1338dc4a69cbcedffc26024b16049a20f1af4f5 @rtomayko committed Jun 21, 2010
Showing with 67 additions and 10 deletions.
  1. +32 −4 man/ronn.1
  2. +35 −6 man/ronn.1.ronn
View
@@ -7,7 +7,7 @@
\fBronn\fR \- convert markdown files to manpages
.
.SH "SYNOPSIS"
-\fBronn\fR [\fIoptions\fR] \fIfile\fR\.\.\.
+\fBronn\fR [\fIformat\fR\.\.\.] \fIfile\fR\.\.\.
.
.br
\fBronn\fR \fB\-m\fR|\fB\-\-man\fR \fIfile\fR\.\.\.
@@ -91,7 +91,7 @@ The name of the group, organization, or individual responsible for publishing th
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 variously:
+HTML output can be customized through the use of CSS stylesheets:
.
.TP
\fB\-\-style\fR=\fImodule\fR[,\fImodule\fR]\.\.\.
@@ -121,10 +121,38 @@ Disable troff warnings\. Warnings are disabled by default\. This option can be u
\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 "Internal Stylesheets"
+.SS "Builtin Stylesheets"
These styles are included with the distribution:
.
.TP
@@ -171,7 +199,7 @@ The heading and footing, respectively\.
The main \fB<h1>\fR element\. Hidden by default unless the manual has no \fIname\fR or \fIsection\fR attributes\.
.
.P
-See the internal style sources \fIhttp://github\.com/rtomayko/ronn/tree/master/lib/ronn/template\fR for examples\.
+See the builtin style sources \fIhttp://github\.com/rtomayko/ronn/tree/master/lib/ronn/template\fR for examples\.
.
.SH "EXAMPLES"
Build roff and HTML output files and view the roff manpage using man(1):
View
@@ -3,7 +3,7 @@ ronn(1) -- convert markdown files to manpages
## SYNOPSIS
-`ronn` [<options>] <file>...<br>
+`ronn` [<format>...] <file>...<br>
`ronn` `-m`|`--man` <file>...<br>
`ronn` `-S`|`--server` <file>...<br>
`ronn` `--pipe` <file><br>
@@ -103,7 +103,7 @@ the [ENVIRONMENT][].)
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 variously:
+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>
@@ -133,13 +133,42 @@ Miscellaneous options:
* `-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 http://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.
-### Internal Stylesheets
+### Builtin Stylesheets
These styles are included with the distribution:
@@ -189,10 +218,10 @@ allow targeting all generated elements:
The main `<h1>` element. Hidden by default unless the manual has no <name>
or <section> attributes.
-See the [internal style sources][internal] for examples.
+See the [builtin style sources][builtin] for examples.
-[internal]: http://github.com/rtomayko/ronn/tree/master/lib/ronn/template
- "internal stylesheet sources"
+[builtin]: http://github.com/rtomayko/ronn/tree/master/lib/ronn/template
+ "Builtin Stylesheet .css files"
## EXAMPLES

0 comments on commit a1338dc

Please sign in to comment.