On Wed, Mar 17, 2004, Shachar Shemesh wrote about "Tool for writing man pages":
> Hi,
>
> I was wondering what tools (if any) people were using for writing man
> pages for their FOSS projects.
>
> Shachar
Vi and groff...
Seriously, the amount of troff you need to learn in order to write a
man page is very minimal. You can start with an existing manual page
(like /usr/share/man/man1/...) and modify it for your own program.
Just a few notes that will help you get started:
1. Manual pages are written in the nroff language. To convert a manual
page file "ls.1" to ascii for viewing, use
groff -man -Tascii ls.1
You can also do things like
groff -man -Tps ls.1 >ls.ps
groff -man -TX100 ls.1
groff -man
for the self-explanatory results
Note that the "-man" option simply tells groff to use the "an" (-m)acro
set, which is the age-old Unix tradition.
2. There are documents and books about *roff and the "an" macros. However,
there are just a few things you need to remember:
* In *roff, a line beginning with a dot followed by two letters is
a command. For example ".SH SYNOPSIS" starts a section called "SYNOPSIS"
(SH = Section Header). ".B hello" prints "hello" in bold, and
".BR hello world" prints "helloworld", with the "hello part in bold.
* *roff commands can also appear in the middle of the line, but these
are different commands that start with a backward slash. For example,
\f... is used for switching font: "hello \fIworld\fR" prints
"hello world" with the world in Italic.
3. There are a bunch of sections that a manual page should traditionally
appear in a manual page. Look at existing manual pages to see what your
users will expect to. If you don't know what "CAVEATS" mean, look for
"caveat" in your favorite Latin dictionary (or m-w.com).
Again, start with an existing manual page to make it much easier for you.
--
Nadav Har'El | Wednesday, Mar 17 2004, 24 Adar 5764
[EMAIL PROTECTED] |-----------------------------------------
Phone: +972-53-790466, ICQ 13349191 |I had a lovely evening. Unfortunately,
http://nadav.harel.org.il |this wasn't it. - Groucho Marx
=================================================================
To unsubscribe, send mail to [EMAIL PROTECTED] with
the word "unsubscribe" in the message body, e.g., run the command
echo unsubscribe | mail [EMAIL PROTECTED]
