From e83e14c8a3808666e7c57728b18833b8c3978820 Mon Sep 17 00:00:00 2001 From: Chayoung You Date: Mon, 6 Apr 2020 22:05:17 +0900 Subject: [PATCH] doc: use asciidoctor instead of a2x AsciiDoc development is continued under asciidoctor. See https://github.com/asciidoc/asciidoc. --- .github/workflows/ci.yml | 2 -- .github/workflows/release.yml | 2 -- FAQ.md | 7 +++--- build.rs | 45 +++++++++++++++++++++++++++++++++++ ci/docker/README.md | 2 +- ci/macos-install-packages | 2 +- ci/ubuntu-install-packages | 2 +- 7 files changed, 52 insertions(+), 10 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 3bdcd6452..eee64bd70 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -19,8 +19,6 @@ jobs: TARGET_DIR: ./target # Emit backtraces on panics. RUST_BACKTRACE: 1 - # Apparently needed to use a2x on macOS. - XML_CATALOG_FILES: /usr/local/etc/xml/catalog runs-on: ${{ matrix.os }} strategy: matrix: diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 86719c039..d687d824d 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -75,8 +75,6 @@ jobs: RUST_BACKTRACE: 1 # Build static releases with PCRE2. PCRE2_SYS_STATIC: 1 - # Apparently needed to use a2x on macOS. - XML_CATALOG_FILES: /usr/local/etc/xml/catalog strategy: matrix: build: [linux, linux-arm, macos, win-msvc, win-gnu, win32-msvc] diff --git a/FAQ.md b/FAQ.md index 633312669..3eed7942e 100644 --- a/FAQ.md +++ b/FAQ.md @@ -60,9 +60,10 @@ 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 `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! 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: ``` $ find ./target -name rg.1 -print0 | xargs -0 ls -t | head -n1 diff --git a/build.rs b/build.rs index e3c08a5d4..6fa7c1acd 100644 --- a/build.rs +++ b/build.rs @@ -65,6 +65,51 @@ fn git_revision_hash() -> Option { } fn generate_man_page>(outdir: P) -> io::Result<()> { + // If asciidoctor isn't installed, fallback to asciidoc. + if let Err(err) = process::Command::new("asciidoctor").output() { + eprintln!( + "Could not run 'asciidoctor' binary, falling back to 'a2x'." + ); + eprintln!("Error from running 'asciidoctor': {}", err); + return legacy_generate_man_page::

(outdir); + } + // 1. Read asciidoctor template. + // 2. Interpolate template with auto-generated docs. + // 3. Save interpolation to disk. + // 4. Use asciidoctor to convert to man page. + let outdir = outdir.as_ref(); + let cwd = env::current_dir()?; + let tpl_path = cwd.join("doc").join("rg.1.txt.tpl"); + let txt_path = outdir.join("rg.1.txt"); + + let mut tpl = String::new(); + File::open(&tpl_path)?.read_to_string(&mut tpl)?; + let options = + formatted_options()?.replace("{", "{").replace("}", "}"); + tpl = tpl.replace("{OPTIONS}", &options); + + let githash = git_revision_hash(); + let githash = githash.as_ref().map(|x| &**x); + tpl = tpl.replace("{VERSION}", &app::long_version(githash, false)); + + File::create(&txt_path)?.write_all(tpl.as_bytes())?; + let result = process::Command::new("asciidoctor") + .arg("--doctype") + .arg("manpage") + .arg("--backend") + .arg("manpage") + .arg(&txt_path) + .spawn()? + .wait()?; + if !result.success() { + let msg = + format!("'asciidoctor' failed with exit code {:?}", result.code()); + return Err(ioerr(msg)); + } + Ok(()) +} + +fn legacy_generate_man_page>(outdir: P) -> io::Result<()> { // If asciidoc isn't installed, then don't do anything. if let Err(err) = process::Command::new("a2x").output() { eprintln!("Could not run 'a2x' binary, skipping man page generation."); diff --git a/ci/docker/README.md b/ci/docker/README.md index 58f367efd..89baa249e 100644 --- a/ci/docker/README.md +++ b/ci/docker/README.md @@ -4,7 +4,7 @@ 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 -`asciidoc` in order to generate man pages. We also install compression tools +`asciidoctor` in order to generate man pages. We also 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 index 309562f7b..dc0955c5d 100755 --- a/ci/macos-install-packages +++ b/ci/macos-install-packages @@ -1,3 +1,3 @@ #!/bin/sh -brew install asciidoc docbook-xsl +brew install asciidoctor diff --git a/ci/ubuntu-install-packages b/ci/ubuntu-install-packages index edaac6f4d..b372e0e47 100755 --- a/ci/ubuntu-install-packages +++ b/ci/ubuntu-install-packages @@ -2,5 +2,5 @@ sudo apt-get update sudo apt-get install -y --no-install-recommends \ - libxslt1-dev asciidoc docbook-xsl xsltproc libxml2-utils \ + asciidoctor \ zsh xz-utils liblz4-tool musl-tools