Shell scripting programmer toolbox : 03 documentation (manpage)

INDEX
https://forums.truenas.com/t/shell-scripting-programmer-toolbox-00-a-programming-directory-structure/21938
https://forums.truenas.com/t/shell-scripting-programmer-toolbox-01-makefile/21954
https://forums.truenas.com/t/shell-scripting-programmer-toolbox-02-function-definitions/22057

The next objective is to create documentation for our project and the traditional documentation method/format is done in the troff typesetting languange–and specifically the mdoc macro set (the newest and fastest macro set). This is called a manpage. If you do not know what a man page is, type man man on the command line and you should see a document displayed on your screen (type q to quit viewing).

If you absolutely need to click a link, here is a web interface for the above command:
https://man.freebsd.org/cgi/man.cgi?query=man&apropos=0&sektion=0&manpath=FreeBSD+14.1-RELEASE+and+Ports&arch=default&format=html

The goal is for when a user types man dircopy they get a docuemnt that looks like the following:

dircopy(7)      Miscellaneous Information Manual        dircopy(7)

NAME
     dircopy -- a program to copy from one directory to another.

SYNOPSIS
     dircopy <source> <destination>

     -source
             A location from where to copy from.

     -desination
             A location to where to copy to.

DESCRIPTION
     A program to copy from one directory to another.

HISTORY
     Created for personal use.

AUTHOR
     John

To get a file to display like this, the man program needs a file with the text (and typesetting macros) in a location where it can find it.

I don’t want to get into the mdoc macros (I wrote myself a helper program to make the following) so, I will just list the file contents.

dircopy.7

.Dd Oct 30 2024
.Dt dircopy 7
.Os
.Au John
.Pp
.Sh  NAME
dircopy -- a program to copy from one directory to another.
.Pp
.Sh  SYNOPSIS
dircopy <source> <destination>
.Bl -tag -width Ds
.It Fl source
A location from where to copy from.
.Pp
.It Fl desination
A location to where to copy to.
.El
.Pp
.Sh  DESCRIPTION
A program to copy from one directory to another.
.Pp
.Sh  HISTORY
Created for personal use.
.Pp
.Sh  AUTHOR
John

Now that we have the file, we need to add this to our makefile so it gets installed to the right location. As you can see from the following, I’ve added a few variables called DOCDIR, and MANPATH so I the extra lines in the install and uninstall sections could be added (to copy and remove the dircopy.7 file).

makefile (modified)

#===---------------------------------------------*- makefile -*---===
#: dircopy
# A tool for changing the world.
#===--------------------------------------------------------------===

#--------------------------------------------------------------------
# Set the target name and source file list.
#--------------------------------------------------------------------
TARGET		= dircopy

SRCDIR      = src
DOCDIR 		= doc

PREFIX		:= /usr/local/bin
MANPATH 	= /usr/local/share/man/man7

CC			:= chmod
CFLAGS		:= +x
REMOVE		:= rm -f

# ==============================================================
# files
# ==============================================================
#
SOURCES =	\
		$(SRCDIR)/dircopy.sh

#--------------------------------------------------------------------
# Define the target compile instructions.
#--------------------------------------------------------------------
dircopy:
	dircopy_TARGET='dircopy'
		@$(CC) $(CFLAGS) $(SOURCES)

.PHONY: install
install:
	@echo "Installing dircopy to: $(PREFIX)"
	@cp $(SRCDIR)/dircopy.sh $(PREFIX)/
	@cp $(DOCDIR)/dircopy.7 $(MANPATH)/dircopy.7

.PHONY: uninstall
uninstall:
	@echo "Uninstalling dircopy from: $(INSTALLDIR)"
	@if [ -f $(PREFIX)/dircopy.sh ]; then rm $(PREFIX)/dircopy.sh; fi
	@if [ -f $(MANPATH)/dircopy.7 ]; then rm $(MANPATH)/dircopy.7; fi

.PHONY: dircopy
all: dircopy

# vim: set noet

We now have a complete program that can be installed–and unistalled–with documentation, safely. We offer the user a helper program but if they choose to uninstall, we clean up after ourselves.