The tests are basically non-existent at this point.

All the manpages I see in Linux have only one dash separating the subject from the tagline:

man - an interface to the on-line reference manuals
cat - concatenate files and print on the standard output
sh - shell, the standard command language interpreter

But Ronn 0.5 forces two dashes (even if I write a single dash). Shouldn't it follow prior convention?

Easier to read and DRY.

I'm pretty sure the TOC should be on the left in the default layout. The problem I'm having is that it makes it really hard to create a decent right margin. This is basically what it looks like right now:

The right margin feels way too tight because of the 8ex indent on the left. When I try to open it up, it looks a little better but throws off the consistent alignment of the heading elements:

If we move it to the left, the problem goes away, although its possible other things won't work right in that config. For instance, I think the left-aligned text in the TOC looks great flush against the manpage right edge.

Just an example of input file that is not rendered correctly:

a(1)
====

* `toggle_status`
  - Toggle the display of the status bar.
* `spawn <executable> <additional args>` TODO explain path-alike expansion

I'm getting warn: unrecognized block tag: "code" message and broken man output. HTML looks ok.

Note that the following input file renders correctly:

a(1)
====

* `abc`
  - def

* `toggle_status`
  - Toggle the display of the status bar.
* `spawn <executable> <additional args>` TODO explain path-alike expansion

Since 0.4 ronn escapes the letters between < > and the result looks like garbage in manpages. Maybe this is caused by rdiscount, but still it's not what I expect to see in a manpage.

Example:

% cat foo.1.ron

## Foobar

Random junk

## Bugreport

Report bugs to <[email protected]>

% cat foo.1

.\" generated with Ronn/v0.4.1
.\" http://github.com/rtomayko/ronn/
.
.TH "FOO" "1" "March 2010" "" ""
.
.SH "NAME"
\fBfoo\fR \-\-
.
.SH "Foobar"
Random junk
.
.SH "Bugreport"
Report bugs to \fIdummy@email.com\fR

"Remember that Feynman covered all of physics -- heavenly bodies through QED -- with only two levels of document hierarchy (The Feynman Lectures on Physics, 1970)."

Just to be historically fair, it was Leighton and Sands who did that. Feynman gave his lectures verabally, and those other guys wrote them up.

definition lists should have the option to have the form in markdown
* word:" "
is made up of letters.

The plain text appears the same but the html that is generated looks more like a definition list does in a man page. This is nice if you don't want the ronn generated html and still want to generate html from your markdown source. Also, there should at least be a warning or something so the program does not just fail to work without giving any idea as to why.

The problem was explained to me on irc as,

"looking at the code, it suggests your document has a 'dd' element, without any descending 'p' elements and no children and it expects one of those cases and doesn't check for errors"

Switch HTML library from hpricot to Nokogiri.

I am just using:

docs/api.html: docs/api.md
ronn -5 --html $< > $@

however its outputting the page twice in the same api.html file

Just try to generate manpage from the following file:
t(1) - test
===========

## test

    [ "$11" ]

Note that, html is generated correctly.

I have an implicit Markdown <pre> block (created by 4 space prefix) containing blank lines (which still have the 4 space prefix). In Ronn 0.5's HTML output, the blank lines are preserved correctly, but in the Roff output, the blank lines are squashed into a single blank line.

I want to be able to provide a custom layout template when building full-page HTML versions of man pages. I want to write templates in mustache:

ron --html --layout=sexy.mustache whisky.7.ron

While I appreciate the elegance of running ronn FILE and having roff or whatever printed to the terminal, I think the more useful default command would be this:

ronn -b5 FILE

That is, -b5 was assumed. Because when I run that, and I see ronn has taken my .markdown or .ronn file and converted it into a beautiful page, I already like this new tool and I think we may have a future together.

Because that is how I felt when I discovered -b5.

Anyway, I think that should be the default.

Ronn 0.6.6 has very nice styling for pre blocks:
background: #EDECEB;
border-left: 1ex solid #DDD;
padding: 5px 1ex;

Newer versions removed this styling, making it harder to distinguish between prose and code examples (pre blocks).

Please revive the old pre styling!

Code blocks are currently rendered without indent and run up against the previous paragraph, so there's really nothing distinguishing them from normal text.

Are you sure you have to escape all dots in roff? I'm not a roff expert by any stretch of the imagination but as far as I can tell this shouldn't be necessary.

See "gzcat /usr/share/man/man7/roff.7.gz | less" for reference.

The dot escaping was introduced in 6a410d9 and looks like it should have been a fix for #21.

But since you have to check for dots at the beginning of a line anyway – which you do since 11cbb86 – you should be ok without the dot escaping.

Am I missing something or do you want me to send you a patch?

While it is nice to have a manpage for markdown, only a markdown implementation should have a markdown manpage. This is just asking for name/file clashses. Maybe, include it with ronn(7) or ronn(5).

Steps to reproduce:

    $ curl -sO https://github.com/defunkt/hub/raw/c2e575fa/man/hub.1.ronn
    $ ronn hub.1.ronn &> /dev/null
    $ man --warnings -l hub.1 >/dev/null
    <standard input>:228: warning: macro `..' not defined
    $

Also, if you use man to view the generated manpage, the "hardcore forking action" is completely missing:

    $ groff -T ascii ./hub.1 | grep hardcore
    $

The correct way to display ellipses in roff is something like this: |.|.|.

(An example for this can be seen in the source for the nroff(1) manpage.)

I'm getting the following test failure with ruby 1.8.7 (2011-12-28 patchlevel 357) [x86_64-linux], most likely caused by the less predictable hash ordering introduced in that patch level:

  1) Failure:
test_section_reference_links_HTML(RonnTest) [/var/tmp/portage/app-text/ronn-0.7.3/work/ruby18/ronn-0.7.3/test/test_ronn.rb:81]:
--- /var/tmp/portage/app-text/ronn-0.7.3/work/ruby18/ronn-0.7.3/test/section_reference_links.html   2012-01-16 20:13:35.971658835 +0100
+++ /var/tmp/portage/app-text/ronn-0.7.3/work/ruby18/ronn-0.7.3/test/section_reference_links.html.wrong 2012-01-16 20:13:43.803311607 +0100
@@ -10,8 +10,8 @@

 <h2 id="SECTION-2">SECTION 2</h2>

-<p>See <a href="#SECTION-1" title="SECTION 1" data-bare-link="true">SECTION 1</a>
-or <a href="#SECTION-1" title="SECTION 1" data-bare-link="true">to put it another way</a>
-or even <a href="#SECTION-1" data-bare-link="true">link this</a></p>
+<p>See <a data-bare-link="true" title="SECTION 1" href="#SECTION-1">SECTION 1</a>
+or <a data-bare-link="true" title="SECTION 1" href="#SECTION-1">to put it another way</a>
+or even <a data-bare-link="true" href="#SECTION-1">link this</a></p>

Import the awesome JS functionality found in the node.js API manual as a Ronn template:
http://nodejs.org/api.html

On April 18, 2010, evaryont wrote:
A request based off this: What about detecting headings and providing links to them throughout the document? I just notice a lot of "See CONFIGURATION", so having CONFIGURATION link to the proper heading would be great. To do so would require keeping a list of all the headings, then doing a gsub(/FOO/, "FOO).

I should be able to go to manpage.html#OPTIONS.

There's now a right-side TOC included by default in HTML output, courtesy of sunaku. Example here.

I'd like to add an option to the ronn command that would disable this for the simple, non-TOC display.

There's also some issues with page width, especially with code examples and preformatted blocks. I'd like to consider using a non-fixed layout and maybe moving it over to the left. The man.cx layout and node.js manual are good examples of what alternative takes on a TOC.

For now, we ought to get a basic option in for turning the TOC off and then we can address some of the other stuff with custom layouts when that lands.

See: http://gist.github.com/436893

http://gist.github.com/436888

Expected "0.6.0"

Let's say I have this synopsis:

  ## SYNOPSIS

`gem man` <GEM>
`gem man` --latest <GEM>
`gem man` --exact <GEM>
`gem man` --list

Whether the four commands are listed on their own lines or the same line is determined by the presence of trailing whitespace. This is probably the only thing that sucks about Markdown.

Should SYNOPSIS sections be magical and do The Right Thing regardless of trailing whitespace?

I like to write references to other manual pages as page(section) because this comes closest in both raw Markdown (as seen on GitHub) and non-linked Roff output to the visual style of most standard manual pages. Specifically, that the page name is shown bold (or in my terminal's case, colored) and the section is not.

Desired: http://devstructure.github.com/contractor/blueprint-create.1.html
Close, but no cigar: http://devstructure.github.com/doubledown/doubledown.1.html

Here's an idea: in the HTML output, why not match /\w+\(\d\)/ and link to that man on man.cx? (Like what man.cx already does, see dash(1) 'SEE ALSO')

Convert   and whitespace inside of <nobr> tags to \~ escapes in roff:

       \~     Unbreakable  space  that  stretches  like a normal inter-word space when a line is
              adjusted.

It's nice to be able to control this for roff output since the default wrapping can be weird in some cases.

The HTML header is just a the name(sect) in a H1. Make it look exactly like the terminal display. Also, there's no footer in the HTML output. We'll need that too.

example:

abc(1)
=====

* `spawn <executable> <additional args>` TODO explain path-alike expansion
  - Runs a command; see EXTERNAL SCRIPTS for details.

but this one works:

abc(1)
=====

* `spawn <executable> <additional args>` TODO explain path-alike expansion

When running the following example through ron, the middle paragraph (“Always use…”) is ommited from the output. This happens with both manpage output as HTML output.

test(1) -- just a ron test
==========================

## TEST

Foo

Always use `attr_reader`, `attr_writer` or `attr_accessor`. Do not use `for...in`; use each instead. Do not use `and`/`or`; use `&&`/`||` instead.

Bar

This results in a HTML page or man page that looks somewhat like this:

TEST
        Foo

        Bar

When leaving out the last paragraph (Bar), the missing paragraph turns up.

Man page references should be displayed in boldface on the terminal and in HTML. We'll need to do some kind of autolinking in the future but simple formatting would be nice for now.

I've had at least two people ask if they could use "my" man page HTML from the mustache site for their own documentation. If ronn advertised itself it would be helpful. Give the people what they want.

Switch markdown library from rdiscount to Redcarpet.

(Sorry for my english.)

I create nested list, e.g.

# test(1) -- test

## TEST

* foo:
  Blablabla.

* bar:
  Blablabla.

  - bar-foo:
    Bububu.

  - bar-baz:
    Bububu.

* baz:
  Blablabla.

output is

.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "TEST" "1" "December 2011" "" ""
.
.SH "NAME"
\fBtest\fR \- test
.
.SH "TEST"
.
.TP
foo
Blablabla\.
.
.TP
bar
Blablabla\.
.
.TP
bar\-foo
Bububu\.
.
.TP
bar\-baz
Bububu\.

.
.TP
baz
Blablabla\.

There is no nested list here.

-s is not documented in the help page or the man page.
In the man page you atleast find --style, but not the short form.

While dots at the beginning of a line are escaped correctly, the check in the write method does not catch all cases where there are spaces in front of the dot in a NF:

$ man --warnings test/markdown_syntax.roff > /dev/null
<standard input>:1450: warning: macro `dot' not defined
    (possibly missing space after `do')
$ groff -T ascii test/markdown_syntax.roff 2>/dev/null | grep dot
$

The readme file ends rather abruptly. Did you intend to list what Ronn aims to do?

http://github.com/defunkt/ron/commit/4afd1d5771f6be25ef0986094f77e7e5814c27ba

"Ron" was already taken by Caleb Clausen's Ruby Object Notation projec. I've agreed to hand over the all lowercase "ron" name in gemcutter so people don't accidentally install the wrong gem.

single quotes should appear as '
or else man thinks it's a macro.

There's no support for either list in roff yet.

I do:

$ RONN_STYLE='./.config/ronn'; ronn -br5 --organization=PROUTILS --style='man,toc,center' --manual='Roll Manual' man/*.ronn

And get:

roff: man/roll-copy.1                            
html: man/roll-copy.1.html                       +man,toc,center
/usr/lib/ruby/gems/1.8/gems/ronn-0.7.3/lib/ronn/template.rb:100:in `basename': can't convert nil into String (TypeError)
from /usr/lib/ruby/gems/1.8/gems/ronn-0.7.3/lib/ronn/template.rb:100:in `stylesheets'
from /usr/lib/ruby/gems/1.8/gems/ronn-0.7.3/lib/ronn/template.rb:99:in `map'
from /usr/lib/ruby/gems/1.8/gems/ronn-0.7.3/lib/ronn/template.rb:99:in `stylesheets'
from /usr/lib/ruby/gems/1.8/gems/ronn-0.7.3/lib/ronn/template.rb:113:in `stylesheet_tags'
from /usr/lib/ruby/gems/1.8/gems/mustache-0.11.2/lib/mustache/context.rb:97:in `__send__'
from /usr/lib/ruby/gems/1.8/gems/mustache-0.11.2/lib/mustache/context.rb:97:in `fetch'
from /usr/lib/ruby/gems/1.8/gems/mustache-0.11.2/lib/mustache/context.rb:85:in `each'
from /usr/lib/ruby/gems/1.8/gems/mustache-0.11.2/lib/mustache/context.rb:85:in `fetch'
from /usr/lib/ruby/gems/1.8/gems/mustache-0.11.2/lib/mustache/context.rb:67:in `[]'
from /usr/lib/ruby/gems/1.8/gems/mustache-0.11.2/lib/mustache/template.rb:40:in `render'
from /usr/lib/ruby/gems/1.8/gems/mustache-0.11.2/lib/mustache/template.rb:44:in `render'
from /usr/lib/ruby/gems/1.8/gems/mustache-0.11.2/lib/mustache.rb:347:in `render'
from /usr/lib/ruby/gems/1.8/gems/ronn-0.7.3/lib/ronn/template.rb:14:in `render'
from /usr/lib/ruby/gems/1.8/gems/ronn-0.7.3/lib/ronn/document.rb:244:in `to_html'
from /usr/lib/ruby/gems/1.8/gems/ronn-0.7.3/lib/ronn/document.rb:221:in `send'
from /usr/lib/ruby/gems/1.8/gems/ronn-0.7.3/lib/ronn/document.rb:221:in `convert'
from /usr/lib/ruby/gems/1.8/gems/ronn-0.7.3/bin/ronn:191
from /usr/lib/ruby/gems/1.8/gems/ronn-0.7.3/bin/ronn:181:in `each'
from /usr/lib/ruby/gems/1.8/gems/ronn-0.7.3/bin/ronn:181
from /usr/lib/ruby/gems/1.8/gems/ronn-0.7.3/bin/ronn:167:in `each'
from /usr/lib/ruby/gems/1.8/gems/ronn-0.7.3/bin/ronn:167
from /usr/local/lib/site_ruby/1.8/roll/library.rb:726:in `load_without_rolls'
from /usr/local/lib/site_ruby/1.8/roll/library.rb:726:in `load'
from /usr/local/lib/site_ruby/1.8/roll/kernel.rb:38:in `load'
from /usr/bin/ronn:19

This is documented but not yet implemented.

I'm using a back-tick block to show a command line, like brew --version, but man is doing a break in the middle of --version. It is possible to suppress hyphenation (but not word breaks) in these blocks?

Ronn 0.5 emits this warning:

warn: unrecognized block tag: "blockquote"