ThirdMirrors
/
cheatsheets
mirror of https://gitee.com/Hawkin99/cheatsheets.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Fix ronn stuff

This commit is contained in:
Rico Sta. Cruz 2015-04-18 04:24:29 +08:00
parent ff87f62b94
commit 387b29c730
2 changed files with 397 additions and 21 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

349
ronn.1 Normal file
View File

@ -0,0 +1,349 @@
.TH "RONN" "1" "April 2015" "" ""
.SH "NAME"
\fBronn\fR \- convert markdown files to manpages
.SH SYNOPSIS
.P
\fBronn\fR [<format>\|\.\.\.] <file>\|\.\.\.
.br
\fBronn\fR \fB\-m\fR|\fB\-\-man\fR <file>\|\.\.\.
.br
\fBronn\fR \fB\-S\fR|\fB\-\-server\fR <file>\|\.\.\.
.br
\fBronn\fR \fB\-\-pipe\fR <file>
.br
\fBronn\fR < <file>
.SH DESCRIPTION
.P
\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 <file>s 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 <file>s\.
.P
The \fB\-\-server\fR and \fB\-\-man\fR options change the output behavior from file
generation to serving dynamically generated HTML manpages or viewing <file> as
with man(1)\.
.P
With no <file> 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
.P
The \fBronn\fR command expects input to be valid ronn\-format(7) text\. Source files
are typically named <name>\|\.<section>\|\.ronn (e\.g\., \fBexample\.1\.ronn\fR)\. The <name>
and <section> should match the name and section defined in the <file>\|'s heading\.
.P
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 \fBronn example\.1\.ronn\fR generates \fBexample\.1\fR with roff output
and \fBexample\.1\.html\fR with HTML output\.
.SH OPTIONS
.P
These options control whether output is written to file(s), standard output, or
directly to a man pager\.
.P
\fB\-m\fR, \fB\-\-man\fR
: 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 \fBMANPAGER\fR
environment variable\.
.RS 0
.IP \(bu 2
\fB\-S\fR, \fB\-\-server\fR:
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
\fIexample\.2\.ronn\fR is served as \fI/example\.2\.html\fR\|\. There's also an index page
at the root with links to each <file>\|\.
The server respects the \fB\-\-style\fR and document attribute options
(\fB\-\-manual\fR, \fB\-\-date\fR, etc\.)\. These same options can be varied at request
time by giving them as query parameters: \fB?manual=FOO&style=dark,toc\fR
\fINOTE: 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\.\fR
.IP \(bu 2
\fB\-\-pipe\fR:
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\.
.RE
.P
Format options control the files \fBronn\fR generates, or the output format when the
\fB\-\-pipe\fR argument is specified\. When no format options are given, both \fB\-\-roff\fR
and \fB\-\-html\fR are assumed\.
.RS 0
.IP \(bu 2
\fB\-r\fR, \fB\-\-roff\fR:
Generate roff output\. This is the default behavior when no <file>s are given
and ronn source text is read from standard input\.
.IP \(bu 2
\fB\-5\fR, \fB\-\-html\fR:
Generate output in HTML format\.
.IP \(bu 2
\fB\-f\fR, \fB\-\-fragment\fR:
Generate output in HTML format but only the document fragment, not the
header, title, or footer\.
.RE
.P
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][]\.)
.RS 0
.IP \(bu 2
\fB\-\-manual\fR=<manual>:
The name of the manual this man page belongs to; <manual> is prominently
displayed top\-center in the header area\.
.IP \(bu 2
\fB\-\-organization\fR=<name>:
The name of the group, organization, or individual responsible for
publishing the document; <name> is displayed in the bottom\-left footer area\.
.IP \(bu 2
\fB\-\-date\fR=<date>:
The document's published date; <date> must be formatted \fBYYYY\-MM\-DD\fR 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\.
.RE
.P
HTML output can be customized through the use of CSS stylesheets:
.RS 0
.IP \(bu 2
\fB\-\-style\fR=<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>\fB\|\.css\fR in all
directories listed in the \fBRONN_STYLE\fR \fI#ENVIRONMENT\fR environment variable,
and then search internal styles\.
When <module> includes a \fI/\fR character, use it as the full path to a
stylesheet file\.
Internal styles are \fIman\fR (included by default), \fItoc\fR, and \fI80c\fR\|\. See
[STYLES][] for descriptions of features added by each module\.
.RE
.P
Miscellaneous options:
.RS 0
.IP \(bu 2
\fB\-w\fR, \fB\-\-warnings\fR:
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\.
.IP \(bu 2
\fB\-W\fR:
Disable troff warnings\. Warnings are disabled by default\. This option can be
used to revert the effect of a previous \fB\-w\fR argument\.
.IP \(bu 2
\fB\-v\fR, \fB\-\-version\fR:
Show ronn version and exit\.
.RE
.SH LINK INDEXES
.P
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 <id> from its
.P
<location>\|\. Blank lines are allowed; lines beginning with a \fB#\fR character are
ignored:
.P
.RS 2
.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
.RE
.P
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\.
.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<text>\fB][\fR<id>\fB]\fR, where
.P
<text> is the link text and <id> is a reference name defined in the index\.
.SH STYLES
.P
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 Builtin Stylesheets
.P
These styles are included with the distribution:
.RS 0
.IP \(bu 2
\fBman\fR:
Basic manpage styles: typography, definition lists, indentation\. This is
always included regardless of \fB\-\-style\fR argument\. It is however possible to
replace the default \fBman\fR module with a custom one by placing a \fBman\.css\fR
file on the \fBRONN_STYLE\fR path\.
.IP \(bu 2
\fBprint\fR:
Basic print stylesheet\. The generated \fB<style>\fR tag includes a
\fBmedia=print\fR attribute\.
.IP \(bu 2
\fBtoc\fR:
Enables the Table of Contents navigation\. The TOC markup is included in
generated HTML by default but hidden with an inline \fBdisplay:none\fR style
rule; the \fBtoc\fR module turns it on and applies basic TOC styles\.
.IP \(bu 2
\fBdark\fR:
Light text on a dark background\.
.IP \(bu 2
\fB80c\fR:
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\.
.RE
.SS Custom Stylesheets
.P
Writing custom stylesheets is straight\-forward\. The following core selectors
allow targeting all generated elements:
.RS 0
.IP \(bu 2
\fB\|\.mp\fR:
The manual page container element\. Present on full documents and document
fragments\.
.IP \(bu 2
\fBbody#manpage\fR:
Signifies that the page was fully\-generated by Ronn and contains a single
manual page (\fB\|\.mp\fR element)\.
.IP \(bu 2
\fB\|\.man\-decor\fR:
The three\-item heading and footing elements both have this class\.
.IP \(bu 2
\fB\|\.man\-head\fR, \fB\|\.man\-foot\fR:
The heading and footing, respectively\.
.IP \(bu 2
\fB\|\.man\-title\fR:
The main \fB<h1>\fR element\. Hidden by default unless the manual has no <name>
or <section> attributes\.
.RE
.P
See the builtin style sources \fIhttp://github\.com/rtomayko/ronn/tree/master/lib/ronn/template\fR for examples\.
.P
.RS 2
.nf
"Builtin Stylesheet \.css files"
.fi
.RE
.SH EXAMPLES
.P
Build roff and HTML output files and view the roff manpage using man(1):
.P
.RS 2
.nf
$ ronn some\-great\-program\.1\.ronn
roff: some\-great\-program\.1
html: some\-great\-program\.1\.html
$ man \./some\-great\-program\.1
.fi
.RE
.P
Build only the roff manpage for all \fB\|\.ronn\fR files in the current directory:
.P
.RS 2
.nf
$ ronn \-\-roff *\.ronn
roff: mv\.1
roff: ls\.1
roff: cd\.1
roff: sh\.1
.fi
.RE
.P
Build only the HTML manpage for a few files and apply the \fBdark\fR and \fBtoc\fR
stylesheets:
.P
.RS 2
.nf
$ ronn \-\-html \-\-style=dark,toc mv\.1\.ronn ls\.1\.ronn
html: mv\.1\.html
html: ls\.1\.html
.fi
.RE
.P
Generate roff output on standard output and write to file:
.P
.RS 2
.nf
$ ronn <hello\.1\.ronn >hello\.1
.fi
.RE
.P
View a ronn file in the same way as man(1) without building a roff file:
.P
.RS 2
.nf
$ ronn \-\-man hello\.1\.ronn
.fi
.RE
.P
Serve HTML manpages at http://localhost:1207/ for all \fB*\.ronn\fR files
under a \fBman/\fR directory:
.P
.RS 2
.nf
$ ronn \-\-server man/*\.ronn
$ open http://localhost:1207/
.fi
.RE
.SH ENVIRONMENT
.RS 0
.IP \(bu 2
\fBRONN_MANUAL\fR:
A default manual name to be displayed in the top\-center header area\.
The \fB\-\-manual\fR option takes precedence over this value\.
.IP \(bu 2
\fBRONN_ORGANIZATION\fR:
The default manual publishing group, organization, or individual to be
displayed in the bottom\-left footer area\. The \fB\-\-organization\fR option takes
precedence over this value\.
.IP \(bu 2
\fBRONN_DATE\fR:
The default manual date in \fBYYYY\-MM\-DD\fR format\. Displayed in the
bottom\-center footer area\. The \fB\-\-date\fR option takes precedence over this
value\.
.IP \(bu 2
\fBRONN_STYLE\fR:
A \fBPATH\fR\-style list of directories to check for stylesheets given to the
\fB\-\-style\fR option\. Directories are separated by a \fI:\fR; blank entries are
ignored\. Use \fI\|\.\fR to include the current working directory\.
.IP \(bu 2
\fBMANPAGER\fR:
The paging program used for man pages\. This is typically set to
something like 'less \-is'\.
.IP \(bu 2
\fBPAGER\fR:
Used instead of \fBMANPAGER\fR when \fBMANPAGER\fR is not defined\.
.RE
.SH BUGS
.P
\fBRonn\fR is written in Ruby and depends on hpricot and rdiscount, extension
libraries that are non\-trivial to install on some systems\. A more portable
version of this program would be welcome\.
.SH COPYRIGHT
.P
Ronn is Copyright (C) 2009 Ryan Tomayko http://tomayko\.com/about
.SH SEE ALSO
.P
groff(1), man(1), pandoc(1), manpages(5), markdown(7), roff(7), ronn\-format(7)

69
ronn.md
View File

@ -2,7 +2,7 @@
title: Ronn title: Ronn
--- ---
Ronn generates Man pages. See [ronn(1)](http://rtomayko.github.io/ronn/ronn.1.html), [ronn-format(7)](http://rtomayko.github.com/ronn/ronn-format.7.html), [rtomayko/ronn](https://github.com/rtomayko/ronn). Ronn generates Man pages. See [ronn(1)](http://rtomayko.github.io/ronn/ronn.1.html), [ronn-format(7)](http://rtomayko.github.com/ronn/ronn-format.7.html). Also see it on GitHub: [rtomayko/ronn](https://github.com/rtomayko/ronn).
{:.center.brief-intro} {:.center.brief-intro}
```sh ```sh
@ -17,25 +17,6 @@ ronn -m foo.1.md # view as manpage
``` ```
{:.light} {:.light}
### Other options
```sh
--pipe # write to stdout
--server, -S # serve in http://localhost:1207
--html, -5 # default
--fragment, -f # html without header/title/footer
--style toc,80c # toc (table of contents)
# 80c (use 80c instead of 100c)
# print (include print stylesheet)
# dark
--manual="MY MANUAL" # shown on top-center
--organization="RONN 0.7.0" # shown on bottom-left
--date="YYYY-MM-DD" # shown on bottom-center
```
## Basic template ## Basic template
```markdown ```markdown
@ -63,6 +44,11 @@ Indent examples with 4 spaces.
$ ls $ ls
$ ls -la $ ls -la
## COPYRIGHT
**PROJECTNAME** is copyright (c) 2015, Rico Sta. Cruz. Released under the MIT
license.
## SEE ALSO ## SEE ALSO
ronn-format(7), ronn(1) ronn-format(7), ronn(1)
@ -80,12 +66,12 @@ Underline: <variable> _emphasis_ *emphasis*
``` ```
Manual references: sh(1) markdown(7) Manual references: sh(1) markdown(7)
Sections: [STANDARDS][], [SEE ALSO][], [DIFFERENT TEXT][#SEE-ALSO] Sections: [STANDARDS][], [SEE ALSO][], [DIFFERENT TEXT][#SEE-ALSO]
URL: [URL link](http://github.com/rstacruz)
``` ```
## Frequently-used sections ## Frequently-used sections
```markdown ```markdown
## NAME
## SYNOPSIS ## SYNOPSIS
## DESCRIPTION ## DESCRIPTION
## OPTIONS ## OPTIONS
@ -101,6 +87,25 @@ Sections: [STANDARDS][], [SEE ALSO][], [DIFFERENT TEXT][#SEE-ALSO]
## SEE ALSO ## SEE ALSO
``` ```
## Other CLI options
```sh
--pipe # write to stdout
--server, -S # serve in http://localhost:1207
--html, -5 # default
--fragment, -f # html without header/title/footer
--style=toc,80c # toc (table of contents)
# 80c (use 80c instead of 100c)
# print (include print stylesheet)
# dark
--manual="MY MANUAL" # shown on top-center
--organization="RONN 0.7.0" # shown on bottom-left
--date="YYYY-MM-DD" # shown on bottom-center
```
## Sections ## Sections
See [Man page sections](http://www.december.com/unix/ref/mansec.html) (december.com). See [Man page sections](http://www.december.com/unix/ref/mansec.html) (december.com).
@ -114,3 +119,25 @@ See [Man page sections](http://www.december.com/unix/ref/mansec.html) (december.
| `6` | Games | | `6` | Games |
| `7` | Misc | | `7` | Misc |
| `8` | System administration commands and procedures | | `8` | System administration commands and procedures |
## JavaScript version
See [marked-man](https://github.com/kapouer/marked-man).
```sh
npm install -g marked-man
marked-man foo.1.md > foo.1
```
{:.light}
### Differences
* No definition lists
* Can't use `<br>`
### Mantastic
[mantastic](http://mantastic.herokuapp.com/) is a hosted service.
```
curl -F page=@mymanpage.md http://mantastic.herokuapp.com
```