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

Groups > comp.unix.programmer > #698 > unrolled thread

How to write a UNIX man page

Back to article view | Back to comp.unix.programmer

Contents

  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

#698 — How to write a UNIX man page

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.

[toc] | [next] | [standalone]

#699

On Thu, 02 Jun 2011 00:51:58 -0700, 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.

Great - I'm all for encouraging people to write man pages!
I find 'info' completely confusing - and I'm a regular emacs user.

If I find one of those useless gnu man pages that say refer to info page, 
then my next step is google.

Regards
JohnT

[toc] | [prev] | [next] | [standalone]

#737

In article <is7gjp$8iu$1@dont-email.me>, JohnT <john@example.com> 
wrote:

> On Thu, 02 Jun 2011 00:51:58 -0700, 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.
> 
> Great - I'm all for encouraging people to write man pages!
> I find 'info' completely confusing - and I'm a regular emacs user.
> 
> If I find one of those useless gnu man pages that say refer to info page, 
> then my next step is google.

Brother!

-- 
Michael Press

[toc] | [prev] | [next] | [standalone]

#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

[toc] | [prev] | [next] | [standalone]

#736

On 06/02/2011 01:47 PM, Tim Watts wrote:
> Mark R. Bannister wrote:
>
> hyperlinking[1]
>
> [1] DEC's VMS HELP command was a decent implementation of how to do this
> properly and nothing text based has surpassed it IMO.

What was it that it did right that other programs don't? I'm asking as a 
person who has only used VMS maybe once or twice.


Bjarni
-- 

                        INFORMATION WANTS TO BE FREE

[toc] | [prev] | [next] | [standalone]

#740

On Sat, 4 Jun 2011, Bjarni Juliusson wrote:

> On 06/02/2011 01:47 PM, Tim Watts wrote:
>> Mark R. Bannister wrote:
>> 
>> hyperlinking[1]
>> 
>> [1] DEC's VMS HELP command was a decent implementation of how to do this
>> properly and nothing text based has surpassed it IMO.
>
> What was it that it did right that other programs don't? I'm asking as a 
> person who has only used VMS maybe once or twice.

$ help help

HELP

    The   HELP   command   invokes   the  HELP  Facility  to  display
    information about a command or topic.  In response to the "Topic?"
    prompt, you can:

       o Type  the  name of the command  or topic for which you need help.

       o Type  INSTRUCTIONS  for more detailed  instructions on how to use
         HELP.

       o Type  HINTS  if you are not  sure of the  name  of the command or
         topic for which you need help.

       o Type HELP/MESSAGE for help with the HELP/MESSAGE command.

       o Type a question mark (?) to redisplay the most recently requested
         text.

       o Press the Return key one or more times to exit from HELP.

    You  can  abbreviate any  topic name, although ambiguous abbreviations
    result in all matches being displayed.


   Additional information available:

   Parameters /INSTRUCTIONS         /LIBLIST   /LIBRARY   /MESSAGE   /OUTPUT
   /PAGE      /PROMPT    /USERLIBRARY          Examples

HELP Subtopic?

[toc] | [prev] | [next] | [standalone]

#708

"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

[toc] | [prev] | [next] | [standalone]

#709

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

When I needed to write a man page I used the help2man [1] utility,
however knowing how to write man pages manually can be useful and surely
it's interesting, so thanks for sharing your article.

Regards,
Marco.

  1. http://www.gnu.org/software/help2man/

-- 
Marco Parrone

[toc] | [prev] | [next] | [standalone]

#713

On Thu, 02 Jun 2011 00:51:58 -0700, Mark R. Bannister wrote:

> http://technicalprose.blogspot.com/2011/06/how-to-write-unix-man-page.html

I just posted a followup there (using Debian Iceape), and it did not appear,
so I guess there may be a fault with the site or with its compatibility
with that browser.

Mark.

-- 
Mark Hobley
Linux User: #370818  http://markhobley.yi.org/

[toc] | [prev] | [next] | [standalone]

#726

On 6/2/2011 3:51 AM, 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.

See also:

http://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap01.html#tag_17_04

and

http://www.fnal.gov/docs/products/ups/ReferenceManual/html/manpages.html

-- 
Wayne

[toc] | [prev] | [next] | [standalone]

#732

Wayne <nospam@all.invalid> writes:
>On 6/2/2011 3:51 AM, 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.
>
>See also:
>
>http://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap01.html#tag_17_04
>
>and
>
>http://www.fnal.gov/docs/products/ups/ReferenceManual/html/manpages.html

See also the man(5) man page in

  _Unix System V Documenter's Workbench Software Technical Discussion and Reference Manual_

or

  text/macros.d/an.src  in the AT&T DWB distribution.

scott

[toc] | [prev] | [standalone]

Back to top | Article view | comp.unix.programmer

csiph-web