[clug] Man pages.

Paul Harvey 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 [1] 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 [2], but I can generate an nroff version of it
doing:

snazzer --man-roff

or, a markdown version of it suitable for browsing on github (example at [3]):

snazzer --man-markdown

or, the usage information directs the user to run

snazzer --man

... 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 [4] 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.

[1] https://github.com/csirac2/snazzer
[2] https://github.com/csirac2/snazzer/blob/c2bc5df5e8910e96622606ddff1b64de85cc98aa/snazzer#L627
[3] https://github.com/csirac2/snazzer/blob/c2bc5df5e8910e96622606ddff1b64de85cc98aa/doc/snazzer.md
[4] http://search.cpan.org/~marekr/Pod-Usage-1.67/lib/Pod/Usage.pm

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:
>
>    https://github.com/BIC-MNI/minc-tools/blob/master/progs/mincstats/mincstats.man1
>
> ta
>
>
> a
>
> --
> linux mailing list
> linux at lists.samba.org
> https://lists.samba.org/mailman/listinfo/linux



More information about the linux mailing list