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.