From 5dc424d3027be8fac4831a55f31b5a91bd0e5312 Mon Sep 17 00:00:00 2001 From: Andrew Gallant Date: Tue, 21 Nov 2023 07:58:39 -0500 Subject: [PATCH] doc: scrub mentions of asciidoc/asciidoctor This optional dependency is now finally dropped. So ends a long journey of trying to generate man pages in a lightweight and dependable way. The only thing I could figure out how to make work reliably was to just learn how to write roff myself. Yay. --- .github/workflows/ci.yml | 5 ----- .github/workflows/release.yml | 6 ------ CHANGELOG.md | 9 +++++++++ FAQ.md | 22 ++++++++++++++-------- ci/docker/README.md | 5 ++--- ci/macos-install-packages | 3 --- ci/ubuntu-install-packages | 4 +--- 7 files changed, 26 insertions(+), 28 deletions(-) delete mode 100755 ci/macos-install-packages diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 3254e054..b37753e7 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -101,11 +101,6 @@ jobs: run: | ci/ubuntu-install-packages - - name: Install packages (macOS) - if: matrix.os == 'macos-latest' - run: | - ci/macos-install-packages - - name: Install Rust uses: dtolnay/rust-toolchain@master with: diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index dc732771..357a0d66 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -115,12 +115,6 @@ jobs: run: | ci/ubuntu-install-packages - - name: Install packages (macOS) - if: matrix.os == 'macos-latest' - shell: bash - run: | - ci/macos-install-packages - - name: Install Rust uses: dtolnay/rust-toolchain@master with: diff --git a/CHANGELOG.md b/CHANGELOG.md index d390ae3a..2506cd1c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,15 @@ Unreleased changes. Release notes have not yet been written. `rg -B1 -A2`. That is, `-A` and `-B` no longer completely override `-C`. Instead, they only partially override `-C`. +Build process changes: + +* ripgrep's shell completions and man page are now created by running ripgrep +with a new `--generate` flag. For example, `rg --generate man` will write a +man page in `roff` format on stdout. The release archives have not changed. +* The optional build dependency on `asciidoc` or `asciidoctor` has been +dropped. Previously, it was used to produce ripgrep's man page. ripgrep now +owns this process itself by writing `roff` directly. + Performance improvements: * [PERF #1760](https://github.com/BurntSushi/ripgrep/issues/1760): diff --git a/FAQ.md b/FAQ.md index 8d226262..fafdf693 100644 --- a/FAQ.md +++ b/FAQ.md @@ -61,18 +61,24 @@ patch release out with a fix. However, no promises are made. Does ripgrep have a man page? -Yes! Whenever ripgrep is compiled on a system with `asciidoctor` or `asciidoc` -present, then a man page is generated from ripgrep's argv parser. After -compiling ripgrep, you can find the man page like so from the root of the -repository: +Yes. If you installed ripgrep through a package manager on a Unix system, then +it would have ideally been installed for you in the proper location. In which +case, `man rg` should just work. + +Otherwise, you can ask ripgrep to generate the man page: ``` -$ find ./target -name rg.1 -print0 | xargs -0 ls -t | head -n1 -./target/debug/build/ripgrep-79899d0edd4129ca/out/rg.1 +$ mkdir -p man/man1 +$ rg --generate man > man/man1/rg.1 +$ MANPATH="$PWD/man" man rg ``` -Running `man -l ./target/debug/build/ripgrep-79899d0edd4129ca/out/rg.1` will -show the man page in your normal pager. +Or, if your version of `man` supports the `-l/--local-file` flag, then this +will suffice: + +``` +$ rg --generate man | man -l - +``` Note that the man page's documentation for options is equivalent to the output shown in `rg --help`. To see more condensed documentation (one line per flag), diff --git a/ci/docker/README.md b/ci/docker/README.md index 89baa249..19913e02 100644 --- a/ci/docker/README.md +++ b/ci/docker/README.md @@ -2,9 +2,8 @@ These are Docker images used for cross compilation in CI builds (or locally) via the [Cross](https://github.com/rust-embedded/cross) tool. The Cross tool actually provides its own Docker images, and all Docker images -in this directory are derived from one of them. We provide our own in order -to customize the environment. For example, we need to install some things like -`asciidoctor` in order to generate man pages. We also install compression tools +in this directory are derived from one of them. We provide our own in order to +customize the environment. For example, we need to install compression tools like `xz` so that tests for the `-z/--search-zip` flag are run. If you make a change to a Docker image, then you can re-build it. `cd` into the diff --git a/ci/macos-install-packages b/ci/macos-install-packages deleted file mode 100755 index dc0955c5..00000000 --- a/ci/macos-install-packages +++ /dev/null @@ -1,3 +0,0 @@ -#!/bin/sh - -brew install asciidoctor diff --git a/ci/ubuntu-install-packages b/ci/ubuntu-install-packages index c66fd380..5e7202c8 100755 --- a/ci/ubuntu-install-packages +++ b/ci/ubuntu-install-packages @@ -11,6 +11,4 @@ if ! command -V sudo; then fi sudo apt-get update sudo apt-get install -y --no-install-recommends \ - asciidoctor \ - zsh xz-utils liblz4-tool musl-tools \ - brotli zstd + zsh xz-utils liblz4-tool musl-tools brotli zstd