uudoc: write manpages and completions to a directory

.github/workflows/CICD.yml

@@ -705,19 +705,10 @@ jobs:
           *) tar czf '${{ steps.vars.outputs.PKG_NAME }}' '${{ steps.vars.outputs.PKG_BASENAME }}'/* ;;
         esac
         popd >/dev/null
-    - name: Package manpages and completions
-      if: matrix.job.target == 'x86_64-unknown-linux-gnu' && matrix.job.features == 'feat_os_unix,uudoc'
+    - name: Package manpages, Markdown, and completions
+      if: matrix.job.target == 'x86_64-unknown-linux-gnu' && contains(matrix.job.features, 'uudoc')
       run: |
-        mkdir -p share/{man/man1,bash-completion/completions,fish/vendor_completions.d,zsh/site-functions,elvish/lib}
-        _uudoc=target/${{ matrix.job.target }}/release/uudoc
-        for bin in $('target/${{ matrix.job.target }}/release/coreutils' --list) coreutils;do
-          ${_uudoc} manpage ${bin} > share/man/man1/${bin}.1
-          ${_uudoc} completion ${bin} bash > share/bash-completion/completions/${bin}.bash
-          ${_uudoc} completion ${bin} fish > share/fish/vendor_completions.d/${bin}.fish
-          ${_uudoc} completion ${bin} zsh > share/zsh/site-functions/_${bin}
-          ${_uudoc} completion ${bin} elvish > share/elvish/lib/${bin}.elv
-        done
-        rm share/zsh/site-functions/_[ # not supported
+        target/${{ matrix.job.target }}/release/uudoc manpages md completions --usr .
         tar --zstd -cf docs.tar.zst share
     - name: Publish
       uses: softprops/action-gh-release@v3

.github/workflows/make.yml

@@ -1,6 +1,6 @@
 name: make
 # spell-checker:ignore (abbrev/names) CACHEDIR taiki
-# spell-checker:ignore (env/flags) CHERE RUSTDOCFLAGS RUSTFLAGS CARGOFLAGS CLEVEL relocs EAGAIN
+# spell-checker:ignore (env/flags) CHERE RUSTDOCFLAGS RUSTFLAGS CARGOFLAGS CLEVEL DATAROOTDIR relocs EAGAIN
 # spell-checker:ignore (jargon) deps softprops toolchain
 # spell-checker:ignore (people) dawidd
 # spell-checker:ignore (shell/tools) bsdtar nextest pacman sccache zstd
@@ -71,7 +71,12 @@ jobs:
           mv -T target target.cache
         fi
         # Check that we don't cross-build uudoc
-        env CARGO_BUILD_TARGET=invalid-unknown-linux-gnu make install-manpages PREFIX=/tmp/usr UTILS=true
+        env CARGO_BUILD_TARGET=invalid-unknown-linux-gnu make install-docs PREFIX=/tmp/usr DATAROOTDIR=/tmp/uudoc-share UTILS=true
+        test -f /tmp/uudoc-share/man/man1/coreutils.1
+        test -f /tmp/uudoc-share/bash-completion/completions/true.bash
+        make uninstall PREFIX=/tmp/usr DATAROOTDIR=/tmp/uudoc-share UTILS=true
+        ! test -e /tmp/uudoc-share/man/man1/coreutils.1
+        ! test -e /tmp/uudoc-share/bash-completion/completions/true.bash
         # We don't build coreutils without MULTICALL=y
         ! test -e target/debug/coreutils
         # build (host)
@@ -317,12 +322,12 @@ jobs:
           mingw-w64-ucrt-x86_64-openssl mingw-w64-ucrt-x86_64-rust
       env:
         CHERE_INVOKING: 1
-    - name: "`(x86_64-pc-cygwin) make install PROG_PREFIX=uu- PROFILE=release-small COMPLETIONS=n MANPAGES=n LOCALES=n`"
+    - name: "`(x86_64-pc-cygwin) make install PROG_PREFIX=uu- PROFILE=release-small UUDOC=n LOCALES=n`"
       shell: 'C:\msys64\usr\bin\bash.exe --login -eo pipefail {0}'
       run: |
         set -x
         export CARGOFLAGS="--features openssl"
-        DESTDIR=/tmp/c make install PROG_PREFIX=uu- PROFILE=release-small COMPLETIONS=n MANPAGES=n LOCALES=n
+        DESTDIR=/tmp/c make install PROG_PREFIX=uu- PROFILE=release-small UUDOC=n LOCALES=n
         # Check that cksum is linked with openssl (e.g. msys-crypto-*.dll)
         # Also check that utils are built with given profile
         ldd target/release-small/cksum | grep crypto
@@ -366,7 +371,7 @@ jobs:
         export CARGOFLAGS="--features openssl"
         # Check that we exclude unix programs to avoid build failure
         # Windows's stdbuf depends on Cygwin's libstdbuf. So make should not try to install libstdbuf
-        make install DESTDIR=/tmp/w PREFIX=/tmp/usr MULTICALL=y COMPLETIONS=n MANPAGES=n LOCALES=n \
+        make install DESTDIR=/tmp/w PREFIX=/tmp/usr MULTICALL=y UUDOC=n LOCALES=n \
          SKIP_UTILS="arch b2sum base32 base64 basename basenc cat comm cp csplit cut date dd df dir dircolors dirname du echo env expand expr factor false fmt fold head hostname hostid join link ln ls md5sum mkdir mktemp more mv nl nproc numfmt od paste pathchk pr printenv printf ptx pwd readlink realpath rm rmdir seq sha1sum sha224sum sha256sum sha384sum sha512sum shred shuf sleep sort split sum sync tac tail tee test touch tr true truncate tsort tty uname unexpand uniq unlink vdir wc whoami yes"
         target/release/coreutils.exe stdbuf --version
 

.github/workflows/manpage-lint.yml

@@ -56,7 +56,7 @@ jobs:
           export LANG=${{ matrix.locale }}
 
           # Build and install manpages to temporary directory
-          make install-manpages DESTDIR="${MANPAGE_DIR}"
+          make install-docs DESTDIR="${MANPAGE_DIR}"
 
       - name: Validate manpages with mandoc (${{ matrix.locale }})
         run: |

GNUmakefile

@@ -6,8 +6,7 @@ ifneq (,$(filter install, $(MAKECMDGOALS)))
 endif
 PROFILE         ?= debug
 MULTICALL       ?= n
-COMPLETIONS     ?= y
-MANPAGES        ?= y
+UUDOC           ?= y
 LOCALES         ?= y
 # allow bootstrapping by our install. mkdir, chmod and cp should be avoided
 INSTALL         ?= install
@@ -127,6 +126,10 @@ ifeq (${MULTICALL}, y)
 INSTALLEES  := ${INSTALLEES} coreutils
 endif
 
+# uudoc also documents the multicall command and the test alias.
+DOC_UTILS := $(sort $(EXES) coreutils $(if $(filter test,$(EXES)),[))
+BUILDDIR_DOCS := $(BUILDDIR_UUDOC)/docs
+
 all: build
 
 build-pkgs:
@@ -199,33 +202,22 @@ clean:
 distclean: clean
 	$(CARGO) clean $(CARGOFLAGS) && $(CARGO) update $(CARGOFLAGS)
 
-ifeq ($(MANPAGES),y)
 # Do not cross-build uudoc
 build-uudoc:
 	@unset CARGO_BUILD_TARGET && ${CARGO} build ${CARGOFLAGS} --bin uudoc --features "uudoc ${EXES}" ${PROFILE_CMD} --no-default-features
 
-install-manpages: build-uudoc
-	$(INSTALL) -d $(DESTDIR)$(DATAROOTDIR)/man/man1
-	$(foreach prog, $(INSTALLEES), \
-		$(BUILDDIR_UUDOC)/uudoc manpage $(prog) > $(DESTDIR)$(DATAROOTDIR)/man/man1/$(PROG_PREFIX)$(prog).1 $(newline) \
-	)
-else
-install-manpages:
-endif
-
-ifeq ($(COMPLETIONS),y)
-
-install-completions: build-uudoc
-	$(INSTALL) -d $(DESTDIR)$(DATAROOTDIR)/zsh/site-functions
-	$(INSTALL) -d $(DESTDIR)$(DATAROOTDIR)/bash-completion/completions
-	$(INSTALL) -d $(DESTDIR)$(DATAROOTDIR)/fish/vendor_completions.d
-	$(foreach prog, $(INSTALLEES), \
-		$(BUILDDIR_UUDOC)/uudoc completion $(prog) zsh > $(DESTDIR)$(DATAROOTDIR)/zsh/site-functions/_$(PROG_PREFIX)$(prog) $(newline) \
-		$(BUILDDIR_UUDOC)/uudoc completion $(prog) bash > $(DESTDIR)$(DATAROOTDIR)/bash-completion/completions/$(PROG_PREFIX)$(prog).bash $(newline) \
-		$(BUILDDIR_UUDOC)/uudoc completion $(prog) fish > $(DESTDIR)$(DATAROOTDIR)/fish/vendor_completions.d/$(PROG_PREFIX)$(prog).fish $(newline) \
-	)
+ifeq ($(UUDOC),y)
+install-docs: build-uudoc
+	PROG_PREFIX="$(PROG_PREFIX)" $(BUILDDIR_UUDOC)/uudoc manpages completions --usr "$(BUILDDIR_DOCS)"
+	$(INSTALL) -d $(addprefix $(DESTDIR)$(DATAROOTDIR)/,man/man1 bash-completion/completions elvish/lib fish/vendor_completions.d powershell zsh/site-functions)
+	$(INSTALL) -m 644 $(addprefix $(BUILDDIR_DOCS)/share/man/man1/$(PROG_PREFIX),$(addsuffix .1,$(DOC_UTILS))) $(DESTDIR)$(DATAROOTDIR)/man/man1
+	$(INSTALL) -m 644 $(addprefix $(BUILDDIR_DOCS)/share/bash-completion/completions/$(PROG_PREFIX),$(addsuffix .bash,$(DOC_UTILS))) $(DESTDIR)$(DATAROOTDIR)/bash-completion/completions
+	$(INSTALL) -m 644 $(addprefix $(BUILDDIR_DOCS)/share/elvish/lib/$(PROG_PREFIX),$(addsuffix .elv,$(DOC_UTILS))) $(DESTDIR)$(DATAROOTDIR)/elvish/lib
+	$(INSTALL) -m 644 $(addprefix $(BUILDDIR_DOCS)/share/fish/vendor_completions.d/$(PROG_PREFIX),$(addsuffix .fish,$(DOC_UTILS))) $(DESTDIR)$(DATAROOTDIR)/fish/vendor_completions.d
+	$(INSTALL) -m 644 $(addprefix $(BUILDDIR_DOCS)/share/powershell/_$(PROG_PREFIX),$(addsuffix .ps1,$(DOC_UTILS))) $(DESTDIR)$(DATAROOTDIR)/powershell
+	$(INSTALL) -m 644 $(addprefix $(BUILDDIR_DOCS)/share/zsh/site-functions/_$(PROG_PREFIX),$(filter-out [,$(DOC_UTILS))) $(DESTDIR)$(DATAROOTDIR)/zsh/site-functions
 else
-install-completions:
+install-docs:
 endif
 
 ifeq ($(LOCALES),y)
@@ -294,7 +286,7 @@ locales:
 install-locales:
 endif
 
-install: build install-manpages install-completions install-locales
+install: build install-docs install-locales
 	$(INSTALL) -d $(INSTALLDIR_BIN)
 ifneq (,$(and $(findstring stdbuf,$(UTILS)),$(findstring feat_external_libstdbuf,$(CARGOFLAGS))))
 ifneq (,$(findstring cygwin,$(OS)))
@@ -330,9 +322,11 @@ ifeq (${MULTICALL}, y)
 endif
 	rm -f $(addprefix $(INSTALLDIR_BIN)/$(PROG_PREFIX),$(PROGS))
 	rm -f $(INSTALLDIR_BIN)/$(PROG_PREFIX)[
-	rm -f $(addprefix $(DESTDIR)$(DATAROOTDIR)/zsh/site-functions/_$(PROG_PREFIX),$(PROGS))
-	rm -f $(addprefix $(DESTDIR)$(DATAROOTDIR)/bash-completion/completions/$(PROG_PREFIX),$(PROGS).bash)
-	rm -f $(addprefix $(DESTDIR)$(DATAROOTDIR)/fish/vendor_completions.d/$(PROG_PREFIX),$(addsuffix .fish,$(PROGS)))
-	rm -f $(addprefix $(DESTDIR)$(DATAROOTDIR)/man/man1/$(PROG_PREFIX),$(addsuffix .1,$(PROGS)))
-
-.PHONY: all build build-coreutils build-pkgs build-uudoc test distclean clean busytest install uninstall
+	rm -f $(addprefix $(DESTDIR)$(DATAROOTDIR)/zsh/site-functions/_$(PROG_PREFIX),$(filter-out [,$(DOC_UTILS)))
+	rm -f $(addprefix $(DESTDIR)$(DATAROOTDIR)/bash-completion/completions/$(PROG_PREFIX),$(addsuffix .bash,$(DOC_UTILS)))
+	rm -f $(addprefix $(DESTDIR)$(DATAROOTDIR)/fish/vendor_completions.d/$(PROG_PREFIX),$(addsuffix .fish,$(DOC_UTILS)))
+	rm -f $(addprefix $(DESTDIR)$(DATAROOTDIR)/elvish/lib/$(PROG_PREFIX),$(addsuffix .elv,$(DOC_UTILS)))
+	rm -f $(addprefix $(DESTDIR)$(DATAROOTDIR)/powershell/_$(PROG_PREFIX),$(addsuffix .ps1,$(DOC_UTILS)))
+	rm -f $(addprefix $(DESTDIR)$(DATAROOTDIR)/man/man1/$(PROG_PREFIX),$(addsuffix .1,$(DOC_UTILS)))
+
+.PHONY: all build build-coreutils build-pkgs build-uudoc test distclean clean busytest install install-docs uninstall

README.md

@@ -262,55 +262,47 @@ make PREFIX=/my/path install
 ```
 
 Installing with `make` installs shell completions for all installed utilities
-for `bash`, `fish` and `zsh`. Completions for `elvish` and `powershell` can also
-be generated; See `Manually install shell completions`.
+for `bash`, `elvish`, `fish`, `powershell` and `zsh`.
 
 To skip installation of completions and manpages:
 
 ```shell
-make COMPLETIONS=n MANPAGES=n install
+make UUDOC=n install
 ```
 
-### Manually install shell completions
+### Generate documentation
 
-The `uudoc` binary generates completions for the `bash`, `elvish`,
-`fish`, `powershell` and `zsh` shells to stdout.
+Install the documentation generator with
+`cargo install --bin uudoc --features uudoc --path .`, then run:
 
-Install `uudoc` by
 ```shell
-cargo install --bin uudoc --features uudoc --path .
+uudoc manpages md completions --usr /usr/local
 ```
 
-Then use the installed binary:
-```shell
-uudoc completion <utility> <shell>
-```
+List any combination of `manpages`, `md`, and `completions` to generate those
+formats for every compiled utility, including `coreutils`. `--usr` selects the
+installation prefix; output goes beneath its `share` directory. Directories
+are created if needed, and existing files are overwritten.
 
-So, to install completions for `ls` on `bash` to
-`/usr/local/share/bash-completion/completions/ls`, run:
+Manpages go in `man/man1` and Markdown files in `docs/coreutils` beneath the
+shared-data directory. Completions for `bash`,
+`elvish`, `fish`, `powershell` and `zsh` go in `bash-completion/completions`,
+`elvish/lib`, `fish/vendor_completions.d`, `powershell`, and `zsh/site-functions`,
+respectively. PowerShell scripts must be loaded from the generated files.
+The unsupported zsh completion for `[` is omitted.
 
-```shell
-uudoc completion ls bash > /usr/local/share/bash-completion/completions/ls.bash
-```
+`PROG_PREFIX` applies to all generated filenames. For example:
 
-Completion for prefixed `cp` with `uu-` on `zsh` is generated by
 ```shell
-env PROG_PREFIX=uu- uudoc completion cp zsh
+env PROG_PREFIX=uu- uudoc manpages completions --usr /usr/local
 ```
 
-### Manually install manpages
-
-To generate manpages, the syntax is:
+This writes prefixed documentation for every compiled utility beneath
+`/usr/local/share`, such as `man/man1/uu-ls.1` and
+`bash-completion/completions/uu-ls.bash`.
 
-```bash
-uudoc manpage <utility>
-```
-
-So, to install the manpage for `ls` to `/usr/local/share/man/man1/ls.1` run:
-
-```bash
-uudoc manpage ls > /usr/local/share/man/man1/ls.1
-```
+Running `uudoc` without arguments still generates the repository's mdbook
+documentation in `docs/src`.
 
 ## Un-installation