pry/pry — pull request #785 by rondale-sc (2012-12-21 20:28:17+00:00)
Title: Incorporate GeneratePryMan into pry.

I've included the class and associated files into a directory nested inside the man directory (see: https://github.com/rondale-sc/pry/commit/28a43fe77cd4f716dd98cbcc6c8b49dc9d16b658)

There is now a new rake task that calls this class called generate_man_page in the top level rake namespace. (see: https://github.com/rondale-sc/pry/commit/d47f3e8a98ba1e0ec886e765cf50c5afe2d39a28)

I ran the task to update the man-pages (see: https://github.com/rondale-sc/pry/commit/d47f3e8a98ba1e0ec886e765cf50c5afe2d39a28)

The idea here is to make sure the man-page is filled with useful information. If you want to alter the man page it's really simple now:

#### Adding a section
1. Open up `man/generate_pry_man/templates/pry.1.erb`
2. Add a header for the section you'd like to add
- Be sure to prefix with ##(pound pound)
- Then a newline, and a set of erb tags `<%= @man_sections[:section_name] %>
- Be sure to replace `:section_name` with the name of your section.
3. Create a file in `man/generate_pry_man/templates/man_sections/.md
- It is important to note that the name must be exactly the same as the symbol you passed to @man_sections.
4. Write markdown in your newly created file.
5. Run `rake generate_man_page`

#### Editing a section
1. Open up `man/templates/man_section/.md`
2. Edit the Markdown to tast.
3. Run `rake generate_man_page

## Caveats

1. I added a dependency to the development environment in the Gemfile, though it is not required until it's needed
- Dependency is on a gem called [ronn](https://github.com/rtomayko/ronn), a nice gem for converting markdown into `.roff` files.
2. The tests are slightly brittle because I'm relying on the output to match canned fixtures. So to get the tests to be valid again you'll have to copy in the output from your newly created `.roff` and `.html` files and then manually inspect them for correctness. Once that's done you're tests will pass again.
3. Some work will be needed in the future if we need/want to create other man sections
- ie. Currently we create PRY (1), to create PRY (2) or Pry (5) work will need to be done.
- I think having just a section 1 makes sense (see my comment here for more info: https://github.com/pry/pry/issues/769)

Alright I think that's enough. Let me know if you'd like me to change anything, or if I need to restructure somehow.

Also, many thanks to irc#pry people for helping!