search

so-fancy / diff-so-fancy

Good-lookin' diffs. Actually… nah… The best-lookin' diffs. :tada:
MIT License
17.28k stars 330 forks source link

please provide man page; use POD documentation #195

Open onlyjob opened 8 years ago

onlyjob commented 8 years ago

Please introduce man page and POD documentation.

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

Thanks.

stevemao commented 8 years ago

I like this. PR welcome :)

scottchiefbaker commented 7 years ago

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 commented 6 years ago

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

scottchiefbaker commented 5 years ago

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

petdance commented 5 years ago

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 commented 5 years ago

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

petdance commented 5 years ago

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 notifications@github.com 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 commented 4 years ago

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

petdance commented 4 years ago

$ 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 commented 4 years ago

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

petdance commented 4 years ago

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 commented 4 years ago

Pod::Usage