Path: csiph.com!x330-a1.tempe.blueboxinc.net!usenet.pasdenom.info!news.albasani.net!eternal-september.org!feeder.eternal-september.org!.POSTED!not-for-mail
From: Tim Watts <tw@dionic.net>
Newsgroups: comp.unix.programmer
Subject: Re: How to write a UNIX man page
Followup-To: comp.unix.programmer
Date: Thu, 02 Jun 2011 12:47:49 +0100
Organization: A noiseless patient Spider
Lines: 29
Message-ID: <5s9kb8-pee.ln1@squidward.dionic.net>
References: <97dc4380-6f30-4f16-b3c6-10a7492c1093@e21g2000vbz.googlegroups.com>
Mime-Version: 1.0
Content-Type: text/plain; charset="ISO-8859-1"
Content-Transfer-Encoding: 7Bit
Injection-Info: mx04.eternal-september.org; posting-host="6oIlEBqCjOm0MjsSUEk5CA"; logging-data="748"; mail-complaints-to="abuse@eternal-september.org";	posting-account="U2FsdGVkX1+Phji9iCc+2olsJ6qLXUsa/ModzdhDYUs="
User-Agent: KNode/4.4.10
Cancel-Lock: sha1:U5ffno9Jd+vj+4cmENjKgwfd7ss=
Xref: x330-a1.tempe.blueboxinc.net comp.unix.programmer:703

Mark R. Bannister wrote:

> I realise that with GNU 'info' a lot of developers become, dare I say
> it, quite lazy when it comes to providing a well written man page -
> and some argue they're not needed at all. But I find, in the products
> that I develop, that man pages are used more often for quick
> reference, and therefore the quality and usability of a product can be
> improved by providing well written man pages.
> 
> To that end, and because I've been writing man pages myself for over
> 10 years, I've decided to provide some notes for beginners on how to
> write your own man page. I hope this article is of help to the wider
> developer community:
> 
> http://technicalprose.blogspot.com/2011/06/how-to-write-unix-man-page.html
> 
> Best regards,
> Mark.

Well done. I thought "info" was dead - I don't know of anyone who doesn't 
use "man" for local documentation.

Personally, desite man's lack of hyperlinking[1] I find "info" confusing and 
unintuitive so I couldn't be bothered.

[1] DEC's VMS HELP command was a decent implementation of how to do this 
properly and nothing text based has surpassed it IMO.

-- 
Tim Watts