[clug] Man pages.

Andrew Janke a.janke at gmail.com
Fri Jul 24 12:57:28 UTC 2015


Thanks Paul,

I hadn't seen POD used for shell scripts before!  I like the here
document hack to get the POD doc in there.


a


On 24 July 2015 at 16:47, Paul Harvey <csirac2 at gmail.com> wrote:
> 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