Introduction

Okay… it’s high time we wrote some docs. I come from a perl background, so we’re going to write the docs using perldoc. I know there are better ways to do this for C# projects and I’m happy to take contributions to this series. Just ask for contributor status and you can post the next article :)

Return to the workspace

$ cd ~/src/greeting

Create the POD

$ mkdir doc
$ cat > doc/greeting.pod.in


=head1 NAME

Greeting - Example to illustrate writing and distributing Free Software

=head1 VERSION

Version @PACKAGE_VERSION@

=head1 SYNOPSIS

 Greeting will greet the planet specified numerically
 (1 = Mercury .. 9 = Pluto) or the world, given
 no argument or arg value 0.

 $ greeting
 Greetings World!
 $ greeting -n 1
 Greetings Mercury!
 $ greeting --number 3
 Greetings Earth!

=head1 COPYRIGHT

Copyright 2008 J. Random Hacker .

  Permission is granted to copy, distribute and/or modify
  this document under the terms of the GNU Free
  Documentation License, Version 1.2 or any later version
  published by the Free Software Foundation; with no
  Invariant Sections, with no Front-Cover Texts, and with
  no Back-Cover Texts.

=cut

Update configure.ac

$ patch configure.ac
@@ -11,11 +11,18 @@
AC_MSG_ERROR([Can't find "gmcs" in your PATH])
fi
 
+AC_PATH_PROG(PERLDOC, perldoc, no)
+if test "x$PERLDOC" = "x" ; then
+ AC_MSG_ERROR([Can't find "perldoc" in your PATH])
+fi
+
AC_CONFIG_FILES([
Makefile
ndesk/Makefile
src/Makefile
greeting
+doc/Makefile
+doc/greeting.pod
])
AC_OUTPUT
 
@@ -24,6 +31,7 @@
echo "Thank you for configuring '$PACKAGE_NAME' version '$PACKAGE_VERSION'"
echo "Runtime: $RUNTIME"
echo "C# compiler: $CSC"
+echo "Perldoc interpreter: $PERLDOC"
echo "installation prefix: $prefix"
echo ""
echo "================="


Create doc/Makefile.am file for man page

$ cat > doc/Makefile.am

all: man1/greeting.1

man1/greeting.1: man1 greeting.pod
        $(PERLDOC) -d man1/greeting.1 greeting.pod

man1:
        mkdir man1

clean:
        rm -rf man1

noinst_docdir = $(prefix)/share/man/man1
noinst_doc_DATA = man1/greeting.1

DISTCLEAN_FILES = greeting.pod

Update Makefile.am

$ patch Makefile.am
@@ -1,3 +1,3 @@
-SUBDIRS = src ndesk
+SUBDIRS = src ndesk doc
 
bin_SCRIPTS = greeting


Re-build Makefile files and configure script

$ autoreconf

Test

$ make
...
$ man -M doc greeting
...
$ sudo make install
...
$ man greeting


Conclusion

There’s a lot more to documentation than this, but like the other pieces of this series, this is an introduction that should get you to a point where you can distributed “just enough.” Some other good tools to look at:

• monodoc
• docbook
• GNU Texinfo

I’m serious about having others beef up this series with a 11.1, 11.2, etc. Leave a comment or catch me on IRC and I’ll hook you up with contributor status.