please provide man page; use POD documentation

[onlyjob]

Please introduce man page and POD documentation.

Man page can be conveniently generated from POD markup using Pod::Usage core module.

Thanks.

[stevemao]

I like this. PR welcome :)

[scottchiefbaker]

I think this is a great idea. We'd definitely welcome either PRs, or feedback on exactly what should be covered in the manpage. I've never used POD or created a manpage.

[alok]

You could use Pandoc to convert the README into a manpage, or at least write a manpage in markdown rather than groff.

[scottchiefbaker]

I don't have expertise in this area, so I'm willing to accept PRs for this.

[petdance]

I do all the docs for ack in POD and convert them to manpages. I'd be glad to help. https://github.com/beyondgrep/ack3

[scottchiefbaker]

@petdance fantastic. If you're up to writing some POD documentation we'll gladly review it and get it in to the repo.

[petdance]

I don’t know enough about the tool to write docs. I can help with the POD to manual and HTML conversion.

…

On Apr 10, 2019, at 4:19 PM, Scott Baker ***@***.***> wrote: @petdance fantastic. If you're up to writing some POD documentation we'll gladly review it and get it in to the repo. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or mute the thread.

[scottchiefbaker]

@petdance I've never written POD before. Where is a good starting point?

[petdance]

$ perldoc perlpod to see the man page for POD. It has all the details.

POD is like Markdown, just older. You do things like =head1 for level headings, B<foo> to make things bold, and so on. For an example, see https://github.com/beyondgrep/ack3/blob/dev/lib/App/Ack.pm

Paragraph-level directives start with = and are in the leftmost column. Inline markup is always 'x' where x is a capital letter.

[scottchiefbaker]

Is the whole point of POD just to output man pages?

[petdance]

No, it's also for internal documentation, but I think in this case you're just looking for man pages.

Another benefit of using POD, since you're using Perl anyway, is that there is such a rich set of tools in place to process POD. So you can create help on the fly with Pod::Usage, or you can create man pages with pod2man, or you can create HTML with pod2html, like here: https://beyondgrep.com/documentation/ack-v3.3.1-man.html

[matthewpersico]

Pod::Usage