No longer build manpage in build scripts

Instead, build manpage only as part of the release process to include it
in the release artifacts, and document how to build it during packaing.

This finally removes the OUT_DIR dependency for the release pipeline,
which simplifies and fixes the release pipeline.

Closes GH-284

.github/workflows/release.yml

@@ -25,24 +25,21 @@ jobs:
         with:
           targets: ${{ matrix.target }}
       - run: sudo gem install asciidoctor
-        if: "!contains(matrix.target, 'windows')"
+        if: '!contains(matrix.target, "windows")'
       - run: sudo apt-get install musl-tools
-        if: contains(matrix.target, 'linux-musl')
-      - shell: bash
-        id: build
-        run: |
-            OUTDIR="$(cargo build --locked --target '${{ matrix.target }}' ${{ matrix.cargo_opts }} --release --message-format=json-render-diagnostics |
-                jq -r 'select(.out_dir) | select(.package_id | startswith("mdcat ")) | .out_dir')"
-            echo "outdir=$OUTDIR" >>"$GITHUB_OUTPUT"
+        if: 'contains(matrix.target, "linux-musl")'
+      - run: cargo build --locked --target '${{ matrix.target }}' ${{ matrix.cargo_opts }} --release
+      - run: asciidoctor -b manpage -a reproducible mdcat.1.adoc
+        if: '!contains(matrix.target, "windows")'
       - run: strip 'target/${{ matrix.target }}/release/mdcat'
-        if: "!contains(matrix.target, 'windows')"
+        if: '!contains(matrix.target, "windows")'
       - id: version
         shell: bash
         run: |
           echo "version=$(cargo pkgid | cut -d'#' -f2 | cut -d: -f2)" >>"${GITHUB_OUTPUT}"
       - id: package
         shell: bash
-        run: ./scripts/package '${{ steps.version.outputs.version }}' '${{ matrix.target }}' '${{ steps.build.outputs.outdir }}'
+        run: ./scripts/package '${{ steps.version.outputs.version }}' '${{ matrix.target }}'
       - uses: actions/upload-artifact@v4
         with:
           name: ${{ steps.package.outputs.name }}

CHANGELOG.md

@@ -11,10 +11,15 @@ Use `cargo release` to create a new release.
 ### Added
 - mdcat now includes a `--completions` argument to generate shell completions for all major shells (see [GH-286]).
 
+### Fixed
+- Restore binary release artifacts (see [GH-284])
+
 ### Removed
-- mdcat now longer builds shell completions during compilation (see [GH-286]).
+- mdcat now longer builds shell completions and man pages during compilation (see [GH-286]).
+  - Packagers now need to build the manpage explicitly during packaging.
 - Release artifacts no longer contain completions; use `mdcat --completions` to generate them instead (see [GH-286]).
 
+[GH-284]: https://github.com/swsnr/mdcat/issues/284
 [GH-286]: https://github.com/swsnr/mdcat/pull/286
 
 ## [2.2.0] – 2024-07-11

README.md

@@ -73,21 +73,10 @@ Try `mdcat --help` or read the [mdcat(1)](./mdcat.1.adoc) manpage.
 
 Run `cargo build --release`.
 The resulting `mdcat` executable links against the system's SSL library, i.e. openssl on Linux.
+
 To build a self-contained executable use `cargo build --features=static`; the resulting executable uses a pure Rust SSL implementation.
 It still uses the system's CA roots however.
 
-The build process also generates the following additional files in `$OUT_DIR`:
-
-- A `mdcat.1` manpage, build from `mdcat.1.adoc` with the `asciidoctor` command from [AsciiDoctor].
-  If `asciidoctor` is not found the build script prints a warning.
-
-These additional artifacts are included in the release builds.
-If you package mdcat you may want to include these files too.
-
-You may also want to include an `mdless` link to `mdcat` (see above).
-
-[AsciiDoctor]: https://asciidoctor.org/
-
 ## Packaging
 
 When packaging `mdcat` you may wish to include the following additional artifacts:
@@ -105,6 +94,17 @@ When packaging `mdcat` you may wish to include the following additional artifact
   $ mdless --completions zsh > /usr/share/zsh/site-functions/_mdless
   ```
 
+- A build of the man page `mdcat.1.adoc`, using [AsciiDoctor]:
+
+  ```console
+  $ asciidoctor -b manpage -a reproducible -o /usr/share/man/man1/mdcat.1 mdcat.1.adoc
+  $ gzip /usr/share/man/man1/mdcat.1
+  # If you include a mdless as above, you may also want to support man mdless
+  $ ln -s mdcat.1.gz /usr/share/man/man1/mdless.1.gz
+  ```
+
+[AsciiDoctor]: https://asciidoctor.org/
+
 ## Troubleshooting
 
 `mdcat` can output extensive tracing information when asked to.

scripts/package

@@ -9,7 +9,6 @@ set -exuo pipefail
 
 VERSION="$1"
 TARGET="$2"
-OUTDIR="$3"
 
 ARCHIVE_NAME="mdcat-${VERSION}-${TARGET}"
 
@@ -37,7 +36,7 @@ package_unix() {
     cp -r \
         README.md CHANGELOG.md LICENSE \
         "target/${TARGET}/release/mdcat" \
-        "${OUTDIR}/mdcat.1" \
+        "mdcat.1" \
         "${pkg_dir}/${ARCHIVE_NAME}"
     tar -czf "${PWD}/${archive_file}" -C "${pkg_dir}" "${ARCHIVE_NAME}"
     echo "file=${archive_file}" >>"${GITHUB_OUTPUT}"