Install doc files

.github/workflows/basic-install.yml

@@ -0,0 +1,66 @@
+name: "Basic Install"
+
+on:
+  push:
+    branches-ignore: [ ]
+  pull_request:
+    branches-ignore: [ ]
+
+jobs:
+
+  installtest-ix:
+    runs-on: ${{ matrix.os }}
+
+    name: 'installtest ${{ matrix.os }}'
+
+    strategy:
+      fail-fast: true
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: 'Update software database (Linux)'
+        if: runner.os == 'Linux'
+        run: sudo apt-get update
+
+      - name: 'Update software database (macOS)'
+        if: runner.os == 'macOS'
+        run: brew update
+
+      - name: 'Install build requirements (Linux)'
+        if: runner.os == 'Linux'
+        run: sudo apt-get install -y asciidoctor
+
+      - name: 'Install build requirements (macOS)'
+        if: runner.os == 'macOS'
+        run: brew install asciidoctor
+
+      - name: "Install"
+        run: |
+          make install DESTDIR=$PWD/_d
+
+          echo "Files installed to DESTDIR:"
+          find $PWD/_d -print0 | sort -z | xargs -0 ls -ld | sed "\| $PWD/_d\$|d; s| $PWD/_d/| /|"
+
+      - name: "Uninstall"
+        run: |
+          make uninstall DESTDIR=$PWD/_d
+
+          echo "Files remaining in DESTDIR after uninstalling:"
+          find $PWD/_d -print0 | sort -z | xargs -0 ls -ld | sed "\| $PWD/_d\$|d; s| $PWD/_d/| /|"
+
+          find $PWD/_d -not -type d > nondir-files.txt
+          if test -s nondir-files.txt; then
+            echo "Error: Leftover item(s) in filesystem after uninstall"
+            cat nondir-files.txt | tr '\n' '\0' | sort -z | xargs -0 ls -ld | sed "\| $PWD/_d\$|d; s| $PWD/_d/| /|"
+            exit 1
+          fi
+
+      - name: "Update man pages"
+        run: |
+          test -s man-src/man1/cowsay.1.adoc
+          touch   man-src/man1/cowsay.1.adoc
+          make man
+          git diff

Makefile

@@ -38,6 +38,11 @@ PRINTF = printf
 SORT = sort
 WC = wc
 
+doc_DATA =
+doc_DATA += CHANGELOG.md
+doc_DATA += LICENSE.txt
+doc_DATA += README.md
+
 # If you implement support for *.pm cows, add share/cows/*.pm here.
 #
 # Note that this is a list of shell globs to be evaluated by the shell, not a list of
@@ -62,33 +67,60 @@ clean:
 # install time to avoid introducing a dependency on Asciidoctor for users.
 
 .PHONY: man
-man: man-src/man1/cowsay.1.adoc man/man1/cowsay.1
+man: man/man1/cowsay.1
 
 # asciidoctor generates both cowsay.1 and cowthink.1, but the cowthink.1 uses an '.so'
-# include macro that doesn't work on some systems, but symlinks do.
-# cowthink.1 is generated as a side effect of cowsay.1, but I'm not sure how
-# to declare that without a redundant target definition.
-# Must delete any existing cowthink.1 symlink *first*, or it may clobber the cowsay.1 file
-# with the wrong contents.
-man/man1/cowsay.1: man-src/man1/cowsay.1.adoc
-	mkdir -p man/man1
-	rm -f man/man1/cowthink.1
-	$(ASCIIDOCTOR) -b manpage -D man/man1 man-src/man1/cowsay.1.adoc
-	rm -f man/man1/cowthink.1
-	$(LN_S) cowsay.1 man/man1/cowthink.1
+# include macro that doesn't work on some systems, while symlinks do.
+#
+# We therefore have asciidoctor write all its output to a temporary
+# directory and only move the cowsay.1 file over, not touching
+# cowthink.1 at all.
+#
+# We also only move the cowsay.1 file over if the differences are more
+# than just irrelevant metadata.
+man/man1/cowsay.1: man-src/man1/cowsay.1.adoc man-src/normalize-manpage.sed
+	@set -e; \
+	tmpdir="tmp$$$$"; \
+	if $(ASCIIDOCTOR) -b manpage -D "$$tmpdir/man/man1" man-src/man1/cowsay.1.adoc; then \
+	  sed -f man-src/normalize-manpage.sed man/man1/cowsay.1 > "$$tmpdir/man/man1/normalized-old-cowsay.1"; \
+	  sed -f man-src/normalize-manpage.sed "$$tmpdir/man/man1/cowsay.1" > "$$tmpdir/man/man1/normalized-new-cowsay.1"; \
+	  if ! test -e "man/man1/cowsay.1" || ! cmp "$$tmpdir/man/man1/normalized-old-cowsay.1" "$$tmpdir/man/man1/normalized-new-cowsay.1" > /dev/null; then \
+	    echo "Updating man/man1/cowsay.1"; \
+	    mv -f "$$tmpdir/man/man1/cowsay.1" man/man1/cowsay.1; \
+	    rm -f "$$tmpdir/man/man1/normalized-old-cowsay.1"; \
+	    rm -f "$$tmpdir/man/man1/normalized-new-cowsay.1"; \
+	    rm -f "$$tmpdir/man/man1/cowthink.1"; \
+	    rmdir "$$tmpdir/man/man1"; \
+	    rmdir "$$tmpdir/man"; \
+	    rmdir "$$tmpdir"; \
+	  else \
+	    echo "man/man1/cowsay.1 is up to date"; \
+	    rm -rf "$$tmpdir"; \
+	  fi; \
+	else \
+	  echo "Error updating man/man1/cowsay.1"; \
+	  exit 1; \
+	fi
 
 .PHONY: install
 install:
+	$(INSTALL_DIR) $(DESTDIR)$(docdir)
+	$(INSTALL_DATA) $(doc_DATA) $(DESTDIR)$(docdir)
 	$(INSTALL_DIR) $(DESTDIR)$(cowpathdir)
+	$(INSTALL_DATA) etc/cowsay/cowpath.d/README.md $(DESTDIR)$(cowpathdir)
 	$(INSTALL_DIR) $(DESTDIR)$(bindir)
 	$(INSTALL_PROGRAM) bin/cowsay $(DESTDIR)$(bindir)/cowsay
+	rm -f $(DESTDIR)$(bindir)/cowthink
 	$(LN_S) cowsay $(DESTDIR)$(bindir)/cowthink
 	$(INSTALL_DIR) $(DESTDIR)$(mandir)/man1
 	$(INSTALL_DATA) man/man1/cowsay.1 $(DESTDIR)$(mandir)/man1/cowsay.1
+	rm -f $(DESTDIR)$(mandir)/man1/cowthink.1
 	$(LN_S) cowsay.1 $(DESTDIR)$(mandir)/man1/cowthink.1
 	$(INSTALL_DIR) $(DESTDIR)$(cowsdir)
+	$(INSTALL_DATA) share/cowsay/cows/README.md $(DESTDIR)$(cowsdir)
 	$(INSTALL_DATA) $(COW_FILES) $(DESTDIR)$(cowsdir)
 	$(INSTALL_DIR) $(DESTDIR)$(sitecowsdir)
+	$(INSTALL_DATA) share/cowsay/site-cows/README.md $(DESTDIR)$(sitecowsdir)
 
 .PHONY: uninstall
 uninstall:
@@ -98,13 +130,24 @@ uninstall:
 	  $(DESTDIR)$(bindir)/cowthink \
 	  $(DESTDIR)$(mandir)/man1/cowsay.1 \
 	  $(DESTDIR)$(mandir)/man1/cowthink.1 \
+	  $(DESTDIR)$(cowpathdir)/README.md \
+	  $(DESTDIR)$(cowsdir)/README.md \
+	  $(DESTDIR)$(sitecowsdir)/README.md \
         ; do \
 	  if test -f "$$f" || test -L "$$f"; then \
 	    echo "rm -f $$f"; \
 	    rm -f "$$f"; \
 	  fi; \
 	done
 	@set -e; \
+	for f in $(doc_DATA); do \
+	  df="$(DESTDIR)$(docdir)/$$(basename "$$f")"; \
+	  if test -f "$$df"; then \
+	    echo "rm -f $$df"; \
+	    rm -f "$$df"; \
+	  fi; \
+	done
+	@set -e; \
 	for cow in $(COW_FILES); do \
 	  dcow="$(DESTDIR)$(cowsdir)/$$(basename "$$cow")"; \
 	  if test -f "$$dcow"; then \
@@ -113,7 +156,7 @@ uninstall:
 	  fi; \
 	done
 	@set -e; \
-	for dir in $(cowsdir) $(sitecowsdir) $(pkgdatadir) $(cowpathdir) $(pkgsysconfdir); do \
+	for dir in $(docdir) $(cowsdir) $(sitecowsdir) $(pkgdatadir) $(cowpathdir) $(pkgsysconfdir); do \
 	  $(PRINTF) "%s\n" "$$dir"; \
 	done \
 	| $(AWK) '{ print length, $$0 }' | $(SORT) -n -r | $(CUT) -d" " -f2- \

etc/cowsay/cowpath.d/README.md

@@ -0,0 +1,21 @@
+The cowsay `cowpath.d/` directory
+=================================
+
+You can drop files into this directory to extend the cowpath cowsay
+uses to find cows.
+
+Each such file MUST
+
+  * be called `*.path`
+
+  * contain only lines containing a directory (no comments, no empty
+    lines, no extra space before or after)
+
+An example file could be `/etc/cowsay/cowpath.d/foo-cows.path` containing
+
+```
+/usr/share/foo-cows/cows
+```
+
+which goes together with you `foo-cows` cow file package's cow file(s)
+in `/usr/share/foo-cows/cows`.

man-src/normalize-manpage.sed

@@ -0,0 +1,3 @@
+s|^\.\\" Generator: Asciidoctor .*|.\\" Generator: GENERATOR|
+s|^\.\\"      Date: 20[0-9][0-9]-[0-1][0-9]-[0-3][0-9]|.\\"      Date: DATE|
+s|^\.TH "COWSAY" "1" "20[0-9][0-9]-[0-1][0-9]-[0-3][0-9]" "Cowsay" "Cowsay Manual"|.TH "COWSAY" "1" "DATE" "Cowsay" "Cowsay Manual"|

share/cowsay/cows/README.md

@@ -0,0 +1,12 @@
+The cowsay `cows/` directory
+============================
+
+This directory is where `cowsay` keeps its own cows.
+
+While you can technically drop your own cow files here, it is
+recommended that you use the `site-cows/` directory to keep your own
+local cow files, and use the `cowpath.d` mechanism to extend the
+cowpath if you distribute your own cows.
+
+Any file type and file name supported by the `cowsay(1)` command will
+work.

share/cowsay/site-cows/README.md

@@ -0,0 +1,10 @@
+The cowsay `site-cows/` directory
+=================================
+
+You can drop your local site specific cow files into this directory.
+
+To distribute your own cows, we recommend you use the `cowpath.d`
+mechanism to extend the cowpath.
+
+Any file type and file name supported by the `cowsay(1)` command will
+work.