Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > comp.unix.programmer > #708

Re: How to write a UNIX man page

Show all headers | View raw

"Mark R. Bannister" <chapter34@yahoo.com> writes:

> 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.

That argument is distressingly common; but it's not based on “we have
GNU ‘info’ documents” (I find that's even less often produced than man
pages), it's usually based on “we have interactive help / command-line
help / online HTML documentation” as though those were a replacement for
the conventional structure of a man page.

> 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.

+1

> 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

Awesome, thank you for writing and publishing this!

Another good reference is a 2005 presentation directed at Debian
developers by Branden Robinson, titled “Write The Fine Manual”
<URL:http://web.archive.org/web/20060102171907/people.debian.org/~branden/talks/wtfm/>.


Since that time, Docutils <URL:http://docutils.sourceforge.net/> (which
renders reStructuredText markup to various output formats) has grown a
manpage rendering module.

    <URL:http://jimmyg.org/blog/2009/generating-man-pages-from-restructuredtext.html>

These days I usually point developers to ‘rst2man’ from Docutils for
quickly getting started writing a man page without wrapping one's head
around roff markup. But the renderer could probably do with some loving
critical appraisal from someone who knows man pages well.

-- 
 \       “My mind is incapable of conceiving such a thing as a soul. I |
  `\     may be in error, and man may have a soul; but I simply do not |
_o__)                                      believe it.” —Thomas Edison |
Ben Finney

Back to comp.unix.programmer | Previous | Next — Previous in thread | Next in thread | Find similar | Unroll thread

Thread

How to write a UNIX man page "Mark R. Bannister" <chapter34@yahoo.com> - 2011-06-02 00:51 -0700
  Re: How to write a UNIX man page JohnT <john@example.com> - 2011-06-02 08:11 +0000
    Re: How to write a UNIX man page Michael Press <rubrum@pacbell.net> - 2011-06-04 12:53 -0700
  Re: How to write a UNIX man page Tim Watts <tw@dionic.net> - 2011-06-02 12:47 +0100
    Re: How to write a UNIX man page Bjarni Juliusson <bjarni@update.uu.se> - 2011-06-04 20:42 +0200
      Re: How to write a UNIX man page "Ersek, Laszlo" <lacos@caesar.elte.hu> - 2011-06-05 08:45 +0200
  Re: How to write a UNIX man page Ben Finney <ben+unix@benfinney.id.au> - 2011-06-02 22:41 +1000
  Re: How to write a UNIX man page Marco Parrone <marco@marcoparrone.com> - 2011-06-02 15:34 +0200
  Re: How to write a UNIX man page Mark Hobley <markhobley@yahoo.donottypethisbit.co> - 2011-06-02 18:02 +0000
  Re: How to write a UNIX man page Wayne <nospam@all.invalid> - 2011-06-02 23:32 -0400
    Re: How to write a UNIX man page scott@slp53.sl.home (Scott Lurndal) - 2011-06-03 15:56 +0000

csiph-web