Generating 'doc/rg.1'

[gvanem]

On Windows I use the man-page program from Eli Zaretskii. I works fine.

My question is how to generate a doc/rg.1 easiest. I failed to understand how the recipe in build.rs should do it.
What cargo command should do it? (I'm a n00b when it comes to Rust etc.)

So I ended up using pandoc in my custom GNU Makefile. This works:

doc/rg.1::
	@echo .TH rg 1 "$(shell date +%d-%B-%Y)" > $@
	pandoc --from markdown --to man doc/rg.1.txt.tpl >> $@

A man rg shows up nice IMHO:

and the build-date at the bottom.

No asciidoc or a2x mess. Just my € 0.02.

[BurntSushi]

So I ended up using pandoc in my custom GNU Makefile. This works

It does not. You're only generating the man page from the template.

No asciidoc or a2x mess.

It's not a mess. I started generating the man page with pandoc, but ran into problems where I couldn't reliably build pandoc. Moreover, pandoc was not producing ideal output. ASCII Doctor provides a much better man page.

What cargo command should do it?

cargo build

My question is how to generate a doc/rg.1 easiest.

Does this FAQ item answer your question?

Note also that the output of rg --help is nearly identical to what's in the man page.

I failed to understand how the recipe in build.rs should do it.

This comment pretty much sums it up:

ripgrep/build.rs

Lines 76 to 79 in ba535fb

	// 1. Read asciidoctor template.
	// 2. Interpolate template with auto-generated docs.
	// 3. Save interpolation to disk.
	// 4. Use asciidoctor to convert to man page.

Basically, the help text for the CLI flags is auto-generated from the flag definitions in the source code. That permits the documentation for every flag to have a single point of truth. There is no easy way to build the man page other than with the build script, which is automatically executed during cargo build.

[gvanem]

Does this FAQ item answer your question?

No. I get no rg.1 generated. And I do have asciidoc.exe and a2x.exe on PATH. So why not?

[BurntSushi]

I don't know? You'll need to look at the build script logs. They will be in the same directory that the rg.1 file would be IIRC. Look around in the target directory.

[gvanem]

The log simply says failed to generate man page: 'asciidoctor' failed with exit code Some(1). How nice.
So I ended up using pandoc on the generated out/rg.1txt file instead:

RG_1_TXT = $(shell find ./target -name rg.1.txt)

doc/rg.1::
	@echo .TH rg 1 "$(shell date +%d-%B-%Y)"     > $@
	pandoc --from markdown --to man $(RG_1_TXT) >> $@

But instead of such struggles it would be nice to have a doc/rg.1 as part of a Release ZIP.

[BurntSushi]

But instead of such struggles it would be nice to have a doc/rg.1 as part of a Release ZIP.

You can grab it from one of the Linux tarballs.