Tags:
create new tag
, view all tags
See BLT.

Contents

Resources

  • Creating Your Own MAN Page: Version 1.0; contributed (to LinuxOrbit) by Harold Rodriguez; (viewed in June, 2002) -- concentrates on writing a man page for your own application, but useful for its explanation of the groff formatting markup.

Introduction

I sent an email to to Andries Brouwer with a suggestion of adding syntax examples to man pages -- Beginners Man Pages is a "scratchpad" for that effort. This page is for discussion.

My First Letter

Subject:  Adding a Syntax Example to Man Pages
   Date:  Mon, 28 Jan 2002 18:48:48 -0500
  From:  Randy Kramer <rhkramer@fast.net>
    To:  Andries Brouwer <aeb@cwi.nl>

Andries,

I found your name on the linuxdoc.org website as the person to write to about man pages. If you are not the appropriate person to deal with a suggestion like this, feel free to pass it on to the appropriate person or send it back to me with any suggestions you may have on who an appropriate person (or organization) is.

I would like to propose that one or a few simple simple examples be added to the man pages, before the synopsis section.

As a newbie to Linux, the man pages are very difficult to deal with. Quite often, I want to go to the man page to quickly (refind) the proper syntax and common command line options to run a command.

Two examples:

For tar, I'd suggest some variation of the following four examples:

  • tar -xvf Extract files from a tar file
  • tar -zxvf Gunzip and extract files from a gzipped tar file.
  • tar -??? Tar the list of files into the tar file
  • tar -???? Tar and gzip the list of files into a gzipped tar file

If there is an easily understandable way to combine the four examples into two (perhaps by combining the first and second examples and putting z into parenthesis or square brackets to show it is optional, and with it a note something like [if z is specifed, a gzipped tar file can be opened].

Another command that I always have trouble with is find, and I can easily come up with a few simple examples for find.

I have thought about starting a new set of reference pages to add this kind of information, but I think it would be much better if it were incorporated in the man pages. (If there is strong objection to this proposal, maybe we could create "nman" (for newbie man pages)?)

If this proposal would be received favorably, I would plan to submit revised man pages (or patches when I learn how) to deal with adding a section like this to man pages as I recognized the need. Others could do the same. (What I'm trying to suggest is that we don't have to set a plan and schedule (deadline) for this effort -- it can be done as people recognize the need and submit patches. When a distro or Internet mirror grabs the latest set of man pages, some would have this new section, others would not (until sometime in the future when all are complete).

regards, Randy Kramer

Andries' Response

Subject: Re: Adding a Syntax Example to Man Pages
   Date: Tue, 29 Jan 2002 12:01:00 GMT
  From: Andries.Brouwer@cwi.nl
    To: Andries.Brouwer@cwi.nl, rhkramer@fast.net

> the person to write to about man pages

Yes. However: I distribute the package man-pages-VERSION.tar.gz (latest man-pages-1.47.tar.gz), and it contains most man pages from sections 2, 3, 4, 5, 7. Man pages from sections 1, 6, 8 are supposed to describe user programs, games, system programs, and these usually follow with the program they describe. In particular, I do not (yet) distribute a page tar.1.

On the other hand, Richard Stallman does not like man pages, and it looks like he forbade GNU people to include man pages for GNU programs, so I also distribute a handful of section 1 pages for GNU programs. See man-pages-1.47.tar.gz for the style. So, if you want to contribute a good tar page, it is very welcome.

You can see that it may be complicated to add a few simple examples to a lot of pages, because each page is from a different package, and all these packages have different maintainers.

A different possibility would be a "beginners.1" page, that mentions all very basic Unix commands with very few very simple examples (ls, cat, cp, mv, rm, cd, mkdir, rmdir, grep, find, chmod, df, gzip, bzip2, tar, ps, kill, less, man). After that one could have a "beginners.8" page with simple sysadm commands (mount, umount, sync, shutdown, chown).

Maybe you could come with a first version of beginners.1? (And perhaps invent a better name for such a page?)

Best regards, Andries

Andries Second Response, with Man Page Example

Subject: Re: Adding a Syntax Example to Man Pages
   Date: Wed, 30 Jan 2002 00:11:08 GMT
  From: Andries.Brouwer@cwi.nl
    To: Andries.Brouwer@cwi.nl, rhkramer@fast.net

> I guess I'll have to read the man HOWTO
> to learn how to format / create a man page.

Yes, possibly. However, things are exceedingly simple. You look at the source for some man pages (maybe in /usr/man/man*, or /usr/share/man, or some such place; maybe they are compressed - the names end in .gz - and zcat page.1.gx will show page.1), and follow the example.

Make a skeleton page to work from. Say,

.\" Copyright 2002 John E. Nobody, 30 Jan 2002.
.\"
.\" Nobody may read this page without my permission,
.\" and distribution is strictly forbidden.
.TH EXAMPLE 1 2002-01-30 "Linux 2.6" "Linux Programmer's Manual"
.SH NAME
example \- give an example
.SH SYNOPSIS
.BI example " foo"
.SH DESCRIPTION
The command
.B example
prints an example of the use of the command
.IR foo .
For example, the invocation
.RS
.nf
example example
.fi
.RE
might print
.RS
.nf
example example
.fi
.RE
.SH "CONFORMING TO"
This is a nonstandard command, not in POSIX or any other
standard standard.
.SH "SEE ALSO"
.BR man (1)

Call this file example.1, and say "man ./example.1" (if you have the right man command; other man versions need some option to take a page from the current directory).

Andries

Contributors

  • RandyKramer - 29 Jan 2002
  • <If you edit this page, add your name here, move this to the next line>
Edit | Attach | Watch | Print version | History: r4 < r3 < r2 < r1 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r4 - 2002-06-25 - RandyKramer
 
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by PerlCopyright 1999-2017 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding WikiLearn? WebBottomBar">Send feedback
See TWiki's New Look