Merge pull request #149 from blairconrad/build-man-page

Build man page as part of workflows

Author: tummychow

.github/workflows/build.yml

@@ -31,3 +31,21 @@ jobs:
       - uses: actions/checkout@v4
       - name: Check format
         run: cargo fmt --check
+
+  build-man-page:
+    name: build-man-page
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup environment
+        run: |
+          sudo apt-get update
+          sudo apt-get --assume-yes --no-install-recommends install asciidoc
+      - name: Build from asciidoc
+        working-directory: ./Documentation
+        run: make
+      - name: Upload man page as artifact
+        uses: actions/upload-artifact@v4
+        with:
+          path: Documentation/git-absorb.1
+          name: git-absorb.1

.github/workflows/release.yml

@@ -52,9 +52,39 @@ jobs:
           tag_name: ${{ env.GA_VERSION }}
           release_name: ${{ env.GA_VERSION }}
 
+  build-man-page:
+    name: build-man-page
+    needs: ['create-release']
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup environment
+        run: |
+          sudo apt-get update
+          sudo apt-get --assume-yes --no-install-recommends install asciidoc
+      - name: Build from asciidoc
+        env:
+          GA_VERSION: ${{ needs.create-release.outputs.GA_VERSION }}
+        working-directory: ./Documentation
+        run: make
+      - name: Upload man page as artifact
+        uses: actions/upload-artifact@v4
+        with:
+          path: Documentation/git-absorb.1
+          name: git-absorb.1
+      - name: Attach man page to release
+        uses: actions/upload-release-asset@v1.0.1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          upload_url: ${{ needs.create-release.outputs.upload_url }}
+          asset_path: Documentation/git-absorb.1
+          asset_name: git-absorb.1
+          asset_content_type: application/octet-stream
+
   build-release:
     name: build-release
-    needs: ['create-release']
+    needs: ['create-release', 'build-man-page']
     runs-on: ${{ matrix.os }}
     env:
       # Emit backtraces on panics.
@@ -122,6 +152,12 @@ jobs:
             arm-linux-gnueabihf-strip \
             /target/arm-unknown-linux-gnueabihf/release/git-absorb
 
+      - name: Download man page
+        uses: actions/download-artifact@v4
+        with:
+          name: git-absorb.1
+          path: Documentation
+
       - name: Build archive
         shell: bash
         run: |

.gitignore

@@ -1,2 +1,3 @@
+/Documentation/git-absorb.1
 /target/
 .idea

Documentation/Makefile

@@ -3,7 +3,7 @@ build-manpage: git-absorb.1
 git-absorb.1: git-absorb.txt
 	$(if $(shell which a2x),,$(error "No a2x in PATH; install asciidoc."))
 	$(info Building manpage. This may take a few moments...)
-	a2x -L -d manpage -f manpage git-absorb.txt
+	a2x -L -d manpage -f manpage git-absorb.txt --attribute man-version=${GA_VERSION}
 
 clean:
 	rm -f git-absorb.1 git-absorb.xml

Documentation/README.md

@@ -1,7 +1,7 @@
 git-absorb manual
 =================
 
-This project's man page `git-absorb.1.gz` can be generated from `git-absorb.txt`
+This project's man page `git-absorb.1` can be generated from `git-absorb.txt`
 by running `make`.
 
 Build dependencies

Documentation/git-absorb.1

@@ -1,5 +1,5 @@
 :man source:   git-absorb
-:man version:  0.5.0
+:man version:  {man-version}
 :man manual:   git absorb
 
 git-absorb(1)

Documentation/git-absorb.txt

@@ -63,12 +63,20 @@ Then `cargo install git-absorb`. Make sure that `$CARGO_HOME/bin` is on your `$P
 
 Note that `git absorb` does _not_ use the system libgit2. This means you do not need to have libgit2 installed to build or run it. However, this does mean you have to be able to build libgit2. (Due to [recent changes](https://github.com/alexcrichton/git2-rs/commit/76f4b74aef2bc2a54906ddcbf7fbe0018936a69d) in the git2 crate, CMake is no longer needed to build it.)
 
-Note: `cargo install` does not currently know how to install manpages ([cargo#2729](https://github.com/rust-lang/cargo/issues/2729)), so if you use `cargo` for installation then `git absorb --help` will not work. Here is a manual workaround, assuming your system has a `~/.local/share/man/man1` directory that `man --path` knows about:
+Note: `cargo install` does not currently know how to install manpages ([cargo#2729](https://github.com/rust-lang/cargo/issues/2729)), so if you use `cargo` for installation then `git absorb --help` will not work. There are two manual workarounds, assuming your system has a `~/.local/share/man/man1` directory that `man --path` knows about:
+
+1. build the man page from source and copy
+   This requires that the [a2x](https://asciidoc-py.github.io/a2x.1.html) tool be installed on your system.
+   ```bash
+   cd ./Documentation
+   make
+   mv git-absorb.1 ~/.local/share/man/man1
+   ```
+2. download a recently-built man page
+   1. find a recent build as in [Installing](#installing) above
+   2. download the `git-absorb.1` file and unzip
+   3. move it to `~/.local/share/man/man1`
 
-```
-wget https://raw.githubusercontent.com/tummychow/git-absorb/master/Documentation/git-absorb.1
-mv git-absorb.1 ~/.local/share/man/man1
-```
 
 ## Usage