sequoia-sq/README.md

# sq, the Sequoia-PGP command line tool

[Sequoia-PGP][] is an implementation of OpenPGP in Rust. It includes a
suite of library crates, which are meant to be used from applications.
This crate provides the `sq` command line application. `sq` is aimed
at command line users as a way to use OpenPGP conveniently from the
command line.

See the [sq user guide][] for instructions. The program also has built-in
help, using the `--help` option and `help` subcommand:

~~~sh
$ sq help
...
~~~

These are collected as the [sq help][] page, for your convenience.

[Sequoia-PGP]: https://sequoia-pgp.org/
[sq user guide]: https://sequoia-pgp.gitlab.io/sq-user-guide/
[sq help]: https://docs.sequoia-pgp.org/sq/index.html

## Building

This crate can be built using the standard `cargo` toolchain:

```sh
cargo build
```

The above creates the `sq` executable, the manual pages, and its shell
completions.  By default, the manual pages and shell completions are
put into the `cargo` target directory, but the exact location is
unpredictable.  To write the assets to a predictable location, set the
environment variable `ASSET_OUT_DIR` to a suitable location.
Reincarnation commit. - This implementation has been moved from the Sequoia repository to its own repository. To inspect the history, either look at the Sequoia repository, or graft it onto this repository like this: $ git remote add sequoia https://gitlab.com/sequoia-pgp/sequoia $ git fetch sequoia 82eb0d7b240d137141fc0aaaa3dff1685bb11864 $ git replace --graft <THIS-COMMIT> 82eb0d7b240d137141fc0aaaa3dff1685bb11864 2023-02-21 14:43:43 +03:00			`# sq, the Sequoia-PGP command line tool`

			`[Sequoia-PGP][] is an implementation of OpenPGP in Rust. It includes a`
			`suite of library crates, which are meant to be used from applications.`
			This crate provides the `sq` command line application. `sq` is aimed
			`at command line users as a way to use OpenPGP conveniently from the`
			`command line.`

			`See the [sq user guide][] for instructions. The program also has built-in`
			help, using the `--help` option and `help` subcommand:

			`~~~sh`
			`$ sq help`
			`...`
			`~~~`

			`These are collected as the [sq help][] page, for your convenience.`

			`[Sequoia-PGP]: https://sequoia-pgp.org/`
			`[sq user guide]: https://sequoia-pgp.gitlab.io/sq-user-guide/`
			`[sq help]: https://docs.sequoia-pgp.org/sq/index.html`
Add instructions on man page creation to README - Add instructions on how to build the `sq` executable and its shell completions. - Add information on how to generate the man pages using the `SQ_MAN` environment variable. - Disable printing of info about `clap_mangen` generated man pages, since they still lack features and are partially incorrect. 2023-06-06 16:44:32 +03:00
			`## Building`

			This crate can be built using the standard `cargo` toolchain:

			```sh
			`cargo build`
			```

Use our custom manual page generator during build time. - Previously, there were two ways of generating manual pages. We used to use the upstream clap_mangen crate, but decided to develop our own custom formatter. However, we didn't quite switch to it, keeping the old mechanism in place and adding our new solution to sq, activated by a hidden environment variable. - This patch drops the upstream formatter, and uses the custom formatter during build time. First, our custom code can be tweaked easily to suit our needs, and switching back to the upstream solution is easy enough should it better suit our needs. Second, generating manual pages at build time should help cross-building environments. 2024-01-05 15:37:36 +03:00			The above creates the `sq` executable, the manual pages, and its shell
Write assets like manual pages to a predictable location. - Fixes #45. 2024-01-05 17:57:05 +03:00			`completions. By default, the manual pages and shell completions are`
			put into the `cargo` target directory, but the exact location is
			`unpredictable. To write the assets to a predictable location, set the`
			environment variable `ASSET_OUT_DIR` to a suitable location.