Added a Rake Task for Md2Man.

[postmodern]

Added a simple rake task named man:pages, which creates file-tasks for each man-page and markdown file within man/. The file-tasks will only (re)generate a man-page, if the related markdown file has a newer timestamp than the man-page file (or if the man-page does not yet exist).

I wasn't sure about code-style, documentation or if you wanted to support additional options besides RedCarpet rendering options. So I am submitting this rake task for review. :)

[postmodern]

@sunaku Ping. I am now successfully using the Rake task in ronin to auto-generate man-pages when building a gem.

[sunaku]

Sorry, I've been busy these days. I'll take a look at your contributions this weekend. Cheers.

[postmodern]

w00t thanks

[sunaku]

I've examined this patch and I don't think it belongs in md2man. I already have similar logic (rake tasks to auto-produce man pages using md2man) at a higher level (external to md2man) in my binman project.

TLDR: Unsure.

[postmodern]

This rake task generates man-pages from arbitrary markdown source files. The binman tasks appears to only generate the man-page via the output of --help?

[sunaku]

Correct, the binman tasks parse man pages embedded in the bin scripts themselves, and thus only generate section 1 man pages. This is less flexible than your contributed solution, but I'm not sure where to draw the line on build automation.

I want md2man to focus on being a converter and nothing more. Build automation can be handled outside of it, via rake or shell scripts or whatever. :cop:

[sunaku]

In the end, I decided that it is acceptable to provide these rake tasks (for the same reason that binman also provides rake tasks). I will try to integrate your contributions this week. Cheers.

[postmodern]

Awesome, thank you! Feel free to simplify the rake tasks, maybe remove the man:page[] task.

[postmodern]

Removed the man:page[foo.1] task, and made it possible to simply run rake man/foo.1 to selectively (re)generate man-pages.

[sunaku]

Hey @postmodern sorry for the long delay. :sweat_smile:

How does one use your Rake task? Simply requiring it into rake(1) doesn't seem to be enough:

$ rake -r md2man/task -T
rake aborted!
uninitialized constant Rake::TaskLib

(See full trace by running task with --trace)
exit 1

Gems included by the bundle:

• binman (3.1.0)
• bundler (1.2.1)
• md2man (1.3.1 7f07209)
• minitest (4.0.0)
• rake (0.9.2.2)
• redcarpet (2.1.1)

Thanks.

[postmodern]

@sunaku Fixed!

[sunaku]

Hey @postmodern, thanks for the update. Although Rake::TaskLib is probably the right way to do things, I felt that it was a bit too much for such a simple task. I just ported the rakefile library from binman into this project instead. Thanks for your contribution anyway. :sweat_smile:

(We'll just leave this pull request open in case I change my mind in the future.) :seedling:

[postmodern]

Inheriting from Rake::TaskLib is indeed the right way to define additional rake tasks to matter how small. I guess I'll just to vendor my rake task into ronin (requires generation of custom man pages, not from the output of --help) and delete my fork.

[sunaku]

Actually, the md2man tasks operate on Markdown files inside man/. They don't depend on --help at all.

In contrast, binman (which builds upon md2man) is the tool that is concerned with --help.

In ronin, do you need to pass certain options down to the redcarpet renderer? If not, I think the md2man tasks (as they are currently implemented) should be sufficient for your use.

[postmodern]

Ah my mistake! Yeah, I'm just passing all man/*.md through Md2Man.

[postmodern]

@sunaku I reviewed the Rakefile, and am a little worried how md2man hooks into the install and release tasks. md2man should only be invoked before building the gem, so the output can be included in the .gem. The rakefile also globs man/man*/*.md which is the proper directory structure for man-pages, but breaks compatibility with gem-man; not sure which is better. Also, the rakefile probably should be converted into a Rake::TaskLib class, so it can accept configuration. Would you be OK with me converting the file into Task class?

[sunaku]

Sure, you can convert it using Rake::TaskLib. However, I think we should patch gem-man (to support the traditional man(1) directory structure) instead of accommodating its limitations.

[postmodern]

@sunaku Awesome. I think if we support a :files option (defaulting to man/man*/*.md), we can support those who prefer using gem-man; until we fix gem-man.

It appears that @defunkt has abandoned all of his projects. You might consider emailing him and offer to take over gem-man.

[sunaku]

I just pushed 31596da44a73500add3d8e82a0c4156abd0bccf9 to eliminate the need for a :files option. md2man should just process all markdown files under man/ for the user. Later on, it's up to the user to decide which of those to package up in their gems.

[sunaku]

Funny, I actually reported this gem-man issue in the past.

:triumph: Fixed it now and sent a pull request (attached to that same issue).

[postmodern]

Closing in favour of https://github.com/sunaku/md2man/pull/7