[clug] Man pages.
csirac2 at gmail.com
Fri Jul 24 06:47:49 UTC 2015
I'm not a fan of writing man pages at the best of times, let alone in *roff.
I think it's pretty hard to go wrong with any of these choices. The
only reason I didn't write the doc for snazzer  in markdown for use
with pandoc and friends is purely because I had an unhealthy obsession
of avoiding extra dependencies at the time, but I also wanted to keep
my scripts entirely self-contained, documentation living at the end of
the script file.
I can appreciate that many dislike this approach (for good reasons)
but when I started out with snazzer, it was a small toy of only 50
lines or so... perhaps I'll split it up when I get around to packaging
it properly one day.
But back to the point, snazzer is a handful of shell scripts that can
call pod2usage on themselves. So I write my doc inside the shell
script in POD syntax , but I can generate an nroff version of it
or, a markdown version of it suitable for browsing on github (example at ):
or, the usage information directs the user to run
... which will allow them to navigate the man page with their default pager.
I'm not advocating this as a solution that you should adopt (I'd
rather write markdown than pod), but I thought it was a cute idea at
the time (I've seen it elsewhere before) and as long as you're not
using a distro that has completely purged itself of perl, the
pod2usage script is a command-line version of Pod::Usage  that's
almost always there in most default installs already.
If I ever move to pandoc, all I'll have to do is feed it the markdown
output from Pod::Usage (snazzer --man-markdown) - so in theory it
should be pretty easy to switch tools.
On 24 July 2015 at 16:24, Andrew Janke <a.janke at gmail.com> wrote:
> I've written and maintained man pages for some time now for software
> toolkits. These toolkits are now all developed on github and it begs
> the question if I should use something else to write the documentation
> (markdown?) and then create the man page from it via some tool.
> (pandoc, ronn, ascii things, xml things).
> There are a number of choices, I like ronn on the surface due to the
> markdown support meaning it could instantly serve as online
> documentation via one of the github documentatio engines.
> So, anyone have any advice and has played in this area? For an example see here:
> linux mailing list
> linux at lists.samba.org
More information about the linux