Adding man pages
No program is complete without a manual, so we'll now add one to our hello program.
In the top level
hello directory, create a directory called
man and add the directory name to the
SUBDIRS variable in the top level
Makefile.am:
SUBDIRS = src man
EXTRA_DIST = BUGS
Make sure the
configure.ac will make autoconf write a Makefile in the new directory:
AC_INIT([hello], [0.0.2])
AM_INIT_AUTOMAKE
AC_PROG_CC
AC_OUTPUT(
Makefile
src/Makefile
man/Makefile
)
Now, in the
man directory, create two files. Firstly,
hello.1 with these contents:
.TH HELLO 1
.SH NAME
hello \- says Hello
.SH SYNOPSIS
.B hello
.SH DESCRIPTION
.I hello
says hello to the world
.SH "SEE ALSO"
goodbye(8), goodnight(1)
That's a simple man-page, and if you're not familiar with the format, there's plenty of documentation available on the web that explains it. The key point to note here is that the filename ends in a number - in this case, a '1', signifying that it's a general user command - and automake uses that number to determine where the file should be installed.
Add this
Makefile.am in the new
man directory:
dist_man_MANS = hello.1
Now recompile the program, and install it, somewhere under the /tmp directory so that it doesn't make a mess of our filesystem:
automake
autoconf
./configure --prefix=/tmp/hello
make
make install
You'll now see that the man page has been installed under
/tmp/hello/share/man/man1/hello.1.
The MANS primary is used to list man pages, and the target name should be
dist_man if all of your man files are named in a standard
name.number format. If your man files have non-standard names, then you can give a section name to the target and automake will rename the files and place them in the appropriate section when installing. For example, if we had this:
dist_man1_MANS = hello.man
dist_man8_MANS = goodbye.man
The above section would rename
hello.man to
hello.1 and
goodbye.man to
goodbye.8, when installed.
Next time
In the next article, we'll start getting down to the nitty-gritty of autoconf, so that you can use it to write code that can be easily ported to different operating systems.
This story has been submitted to fsdaily.com! If you think this story should be read by the free software community, come vote it up and discuss it here: http://www.fsdaily.com/HighEnd/GNU_autotools_primer_part_two
Tracked: Jun 16, 09:53
This story has been submitted to fsdaily.com! If you think this story should be read by the free software community, come vote it up and discuss it here: http://www.fsdaily.com/HighEnd/GNU_autotools_primer_part_two-1
Tracked: Jun 16, 18:49