Move man source files to separate man-src dir, to avoid "ignoring bogus filename" warning

On Fedora (but not Ubuntu or macOS, it seems), if you put the in-repo man/ dir on the manpath and do `man cowsay`, if the corresponding .adoc source file is there, it'll give you a warning. This breaks the man dir in to separate source and built dirs, and should get rid of that warning.

Example on Fedora 39:

```
janke@fed39-test-as:~/repos/cowsay$ PATH=$PWD/bin:$PATH
janke@fed39-test-as:~/repos/cowsay$ which cowsay
~/repos/cowsay/bin/cowsay
janke@fed39-test-as:~/repos/cowsay$ man -a -w cowsay
man: warning: /home/janke/repos/cowsay/man/man1/cowsay.1.adoc: ignoring bogus filename
/home/janke/repos/cowsay/man/man1/cowsay.1
janke@fed39-test-as:~/repos/cowsay$ man -a -w cowthink
/home/janke/repos/cowsay/man/man1/cowsay.1
janke@fed39-test-as:~/repos/cowsay$
```

Author: apjanke

Makefile

@@ -62,14 +62,18 @@ clean:
 # install time to avoid introducing a dependency on Asciidoctor for users.
 
 .PHONY: man
-man: man/man1/cowsay.1.adoc man/man1/cowsay.1
+man: man-src/man1/cowsay.1.adoc 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.
-man/man1/cowsay.1: man/man1/cowsay.1.adoc
-	$(ASCIIDOCTOR) -b manpage man/man1/cowsay.1.adoc
+# 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
 

doc-project/Developer Notes.md

@@ -25,6 +25,10 @@ As of 2024, cowsay uses Asciidoctor, not AsciiDoc, to build its man page and stu
 
 The man pages are built at code authoring time and checked in to the repo, instead of at `make install` time, so users do not need to have Asciidoctor installed in order to install cowsay.
 
+## Dev setup and testing cowsay
+
+The repo layout is organized to mimic the directory structure of the installed cowsay, so you can set up your `$PATH` to run cowsay from it, instead of the system installation location, with unqualified `cowsay` and `man cowsay` commands, instead of having to say e.g. `./bin/cowsay`. To do so, cd to the repo and run `PATH="$PWD/bin:$PATH`. (The man pages get picked up on the manpath automatically as a result of that; probably no need to set `$MANPATH` separately.) That's how I do testing as of 2024-08, and I'm thinking that future test or automation scripts will be written to work that way, instead of adding code paths to call the local `cowsay` using a full path to it. I think this approach is a good way to mimic how cowsay will work once installed.
+
 ## Releasing cowsay
 
 See `doc-project/Release Checklist.md` for the steps needed to do a cowsay release.

doc-project/Release Checklist.md

@@ -1,32 +1,42 @@
 # Cowsay Release Checklist
 
+## Getting ready for a release
+
+Once `main` seems ready for a release, test it out.
+
+1. Test the code manually by playing around with `cowsay`.
+2. Exercise all cows.
+  a. `for cow in $(cowsay -l); do echo "${cow}:"; cowsay -f "$cow" moo; echo ''; done`
+3. Install on macOS with `brew install --HEAD cowsay/cowsay-org`.
+  a. Test `cowsay` as above.
+  b. Test `man cowsay` and `man cowthink`.
+
 ## Creating a release
 
 Steps to be done for a release:
 
 1. Change version number in:
-  a. `cowsay`
-  a. `cowsay.1.adoc`
+  a. `bin/cowsay`
+  a. `man-src/man1/cowsay.1.adoc`
 2. Rebuild the man pages with `make man`.
 3. Update `CHANGELOG.md` with the release date, and make sure it's up to date with changes.
-4. Commit those changes, with a commit message like "v. X.Y.Z".
-5. Tag the release in git, in format "vX.Y.Z".
-6. Create an X.Y-fixes branch, if this is a major or minor release. (But not for patch releases.)
-7. Push the tag and new fixes branch to GitHub.
+4. Commit those changes, with a commit message like "v X.Y.Z".
+5. Tag the release in git, in format "vX.Y.Z", like `git tag vX.Y.Z`.
+6. Create a `patches/vX.Y` branch, if this is a major or minor release. (But not for patch releases.)
+7. Push the commits, tag, and new patches branch to GitHub.
 8. Create the release in [GitHub Releases](https://github.com/cowsay-org/cowsay/releases).
   a. Use the CHANGELOG contents as the release comments.
 9. Update the cowsay-org formula over in the [homebrew-cowsay Tap repo](https://github.com/cowsay-org/homebrew-cowsay) to use the new release.
 10. Post a comment on the ["Moos & Announcements"](https://github.com/cowsay-org/cowsay/issues/48) issue.
-12. Open development on next release.
+12. Open development on next release, if this is a major or minor release.
   a. Bump the version in files listed above (`cowsay`, `cowsay.1.adoc`), and give it a "-SNAPSHOT" suffix.
   b. Update the CHANGELOG with a section for the new release.
   c. Rebuild the man pages with `make man`.
-  d. Commit with a message like "Open development for X.Y.Z", and push.
+  d. Commit with a message like "Open development for X.Y", and push.
+13. Don't bother doing the "open development on next" steps if this is a patch release; just remember to do that if and when you start a patch release for that minor series.
 
 ## Build environment
 
-You may need to do some setup to get your environment working for a build, especially the `make man` part.
-
-The cowsay build depends on Asciidoctor. (Not the old AsciiDoc. If you see `a2x` usage, that's old AsciiDoc stuff, and should be removed and replaced with `asciidoctor` calls.)
+You may need to do some setup to get your environment working for a build, especially the `make man` part. The cowsay build depends on Asciidoctor. (Specifically Asciidoctory, not the old AsciiDoc and its `a2x` command.)
 
 See the "Developer Notes.md" doc for more details. (Well, as soon as I get to writing more details.)