mirror of
https://github.com/BurntSushi/ripgrep.git
synced 2025-03-17 20:28:03 +02:00
doc: use asciidoctor instead of a2x
AsciiDoc development is continued under asciidoctor. See https://github.com/asciidoc/asciidoc. We do however fallback to a2x if asciidoctor is not present. This is to ease migration, but at some point, it's likely that support for a2x will be dropped. Originally reported downstream: https://github.com/Homebrew/linuxbrew-core/issues/19885 Closes #1544
This commit is contained in:
parent
793c1179cc
commit
16a1221fc7
2
.github/workflows/ci.yml
vendored
2
.github/workflows/ci.yml
vendored
@ -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:
|
||||
|
2
.github/workflows/release.yml
vendored
2
.github/workflows/release.yml
vendored
@ -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]
|
||||
|
@ -15,6 +15,8 @@ Bug fixes:
|
||||
Note how to escape a `$` when using `--replace`.
|
||||
* [BUG #1537](https://github.com/BurntSushi/ripgrep/issues/1537):
|
||||
Fix match bug caused by inner literal optimization.
|
||||
* [BUG #1544](https://github.com/BurntSushi/ripgrep/issues/1544):
|
||||
ripgrep now uses `asciidoctor` instead of `a2x` to generate its man page.
|
||||
* [BUG #1571](https://github.com/BurntSushi/ripgrep/issues/1571):
|
||||
Add note about configuration files in `--type-{add,clear}` docs.
|
||||
* [BUG #1573](https://github.com/BurntSushi/ripgrep/issues/1573):
|
||||
|
7
FAQ.md
7
FAQ.md
@ -60,9 +60,10 @@ patch release out with a fix. However, no promises are made.
|
||||
Does ripgrep have a man page?
|
||||
</h3>
|
||||
|
||||
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
|
||||
|
45
build.rs
45
build.rs
@ -65,6 +65,51 @@ fn git_revision_hash() -> Option<String> {
|
||||
}
|
||||
|
||||
fn generate_man_page<P: AsRef<Path>>(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::<P>(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<P: AsRef<Path>>(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.");
|
||||
|
@ -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
|
||||
|
@ -1,3 +1,3 @@
|
||||
#!/bin/sh
|
||||
|
||||
brew install asciidoc docbook-xsl
|
||||
brew install asciidoctor
|
||||
|
@ -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
|
||||
|
Loading…
x
Reference in New Issue
Block a user