Merge pull request #775 from pkgw/install-instructions

docs: update installation instructions

CARGO_README.md

@@ -0,0 +1,71 @@
+# The Tectonic Typesetting System
+
+The `tectonic` crate delivers a modernized, complete, self-contained
+[TeX](https://en.wikipedia.org/wiki/TeX)/[LaTeX](https://www.latex-project.org/)
+engine, powered by [XeTeX](http://xetex.sourceforge.net/) and
+[TeXLive](https://www.tug.org/texlive/). It provides a CLI and ties together the
+functionality of a large collection of sub-crates.
+
+- [User Website](https://tectonic-typesetting.github.io/)
+- [The Tectonic Book](https://tectonic-typesetting.github.io/book/latest/)
+- [Installation](https://tectonic-typesetting.github.io/book/latest/installation/) of the CLI
+- [Detailed Build Instructions][build-inst]
+- [API Documentation](https://docs.rs/tectonic/)
+- [Issues](https://github.com/tectonic-typesetting/tectonic/issues/)
+- [Changelog](https://github.com/tectonic-typesetting/tectonic/blob/release/CHANGELOG.md)
+
+[build-inst]: https://tectonic-typesetting.github.io/book/latest/howto/build-tectonic/
+
+
+## Building Tectonic
+
+The Tectonic crates collectively depend on a relatively large number of
+third-party libraries. See [the Book’s build instructions][build-inst] for a
+listing and guidance on setting up the build.
+
+The crate build can be customized with the following [Cargo features]:
+
+[Cargo features]: https://doc.rust-lang.org/cargo/reference/features.html
+
+- `external-harfbuzz`: build against an external version of the [Harfbuzz] text
+  shaping library, rather than a vendored version (the default)
+- `geturl-curl`: use the [curl] crate to implement HTTP requests. In order for
+  this to take effect, you must use `--no-default-features` because
+  `geturl-reqwest` is a default feature and it takes precedence
+- `geturl-reqwest`: use the [reqwest] crate to implement HTTP requests (enabled
+  by default)
+- `native-tls-vendored`: if using [reqwest], activate the `vendored` option in
+  the [native-tls] crate, causing OpenSSL to be vendored
+
+[Harfbuzz]: https://harfbuzz.github.io/
+[curl]: https://docs.rs/curl/
+[reqwest]: https://docs.rs/reqwest/
+[native-tls]: https://github.com/sfackler/rust-native-tls
+
+[The Book][build-inst] describes some less-used features and provides a bit more
+detail.
+
+
+## Sub-crates
+
+The main `tectonic` crate ties together the functionality of a number of
+sub-crates:
+
+- [`tectonic_bridge_core`](https://crates.io/crates/tectonic_bridge_core)
+- [`tectonic_bridge_flate`](https://crates.io/crates/tectonic_bridge_flate)
+- [`tectonic_bridge_freetype2`](https://crates.io/crates/tectonic_bridge_freetype2)
+- [`tectonic_bridge_graphite2`](https://crates.io/crates/tectonic_bridge_graphite2)
+- [`tectonic_bridge_harfbuzz`](https://crates.io/crates/tectonic_bridge_harfbuzz)
+- [`tectonic_bridge_icu`](https://crates.io/crates/tectonic_bridge_icu)
+- [`tectonic_cfg_support`](https://crates.io/crates/tectonic_cfg_support)
+- [`tectonic_dep_support`](https://crates.io/crates/tectonic_dep_support)
+- [`tectonic_engine_bibtex`](https://crates.io/crates/tectonic_engine_bibtex)
+- [`tectonic_engine_xdvipdfmx`](https://crates.io/crates/tectonic_engine_xdvipdfmx)
+- [`tectonic_engine_xetex`](https://crates.io/crates/tectonic_engine_xetex)
+- [`tectonic_errors`](https://crates.io/crates/tectonic_errors)
+- [`tectonic_geturl`](https://crates.io/crates/tectonic_geturl)
+- [`tectonic_io_base`](https://crates.io/crates/tectonic_io_base)
+- [`tectonic_pdf_io`](https://crates.io/crates/tectonic_pdf_io)
+- [`tectonic_status_base`](https://crates.io/crates/tectonic_status_base)
+- [`tectonic_xdv`](https://crates.io/crates/tectonic_xdv)
+- [`tectonic_xetex_layout`](https://crates.io/crates/tectonic_xetex_layout)

Cargo.toml

@@ -14,7 +14,7 @@ of support files.
 homepage = "https://tectonic-typesetting.github.io/"
 documentation = "https://docs.rs/tectonic"
 repository = "https://github.com/tectonic-typesetting/tectonic/"
-readme = "README.md"
+readme = "CARGO_README.md"
 keywords = ["tex", "latex", "typesetting", "font"]
 categories = ["command-line-interface", "parser-implementations", "rendering", "science", "text-processing"]
 license = "MIT"

README.md

@@ -11,23 +11,27 @@ engine, powered by [XeTeX](http://xetex.sourceforge.net/) and
 
 ## Read this first
 
-If you just want to compile TeX documents, you should probably **click through to
-[the main Tectonic website](https://tectonic-typesetting.github.io/)**. This
-page is primarily aimed at folks interested in how Tectonic works “under the hood.”
+If you just want to compile TeX documents, you should probably **click through
+to [the main Tectonic website](https://tectonic-typesetting.github.io/)**. This
+page is primarily aimed at folks interested in how Tectonic works “under the
+hood.” If you want to build the [`tectonic`][crate] Rust crate, check out [its
+README](./CARGO_README.md).
+
+[crate]: https://crates.io/crates/tectonic
 
 ## Developer dashboard
 
 <a href="https://repology.org/metapackage/tectonic">
     <img src="https://repology.org/badge/vertical-allrepos/tectonic.svg" alt="Packaging status" align="right">
 </a>
 
-- [User website](https://tectonic-typesetting.github.io/).
-- [Community discussion forum](https://tectonic.newton.cx/).
-- [Installation](https://tectonic-typesetting.github.io/install.html).
-- [Developer documentation, including build instructions](https://tectonic-typesetting.github.io/develop.html).
-- [API documentation](https://docs.rs/tectonic/).
-- [Issues](https://github.com/tectonic-typesetting/tectonic/issues/).
-- [Changelog](./CHANGELOG.md).
+- [User website](https://tectonic-typesetting.github.io/)
+- [Community discussion forum](https://tectonic.newton.cx/)
+- [Installation](https://tectonic-typesetting.github.io/book/latest/installation/)
+- [Build instructions](https://tectonic-typesetting.github.io/book/latest/howto/build-tectonic/)
+- [API documentation](https://docs.rs/tectonic/)
+- [Issues](https://github.com/tectonic-typesetting/tectonic/issues/)
+- [Changelog](https://github.com/tectonic-typesetting/tectonic/blob/release/CHANGELOG.md)
 
 ## Technical ecosystem
 
@@ -67,60 +71,3 @@ any given time.
 Please see
 [the tectonic-staging README](https://github.com/tectonic-typesetting/tectonic-staging#readme)
 for more information. (Or at least, more words on the topic.)
-
-
-## Cargo Features
-
-The Tectonic build can be customized with the following [Cargo features]:
-
-[Cargo features]: https://doc.rust-lang.org/cargo/reference/features.html
-
-##### `external-harfbuzz`
-
-By default, the Tectonic crates will build and link to a “vendored” (static,
-internal) version of the [Harfbuzz] text shaping library. If you would like to
-link to an externally-supplied version instead, enable this feature. The
-external library can be detected with either [pkg-config] or [vcpkg]. See the
-[How To Build Tectonic][howto-build] guide for more details.
-
-[Harfbuzz]: https://harfbuzz.github.io/
-[pkg-config]: https://www.freedesktop.org/wiki/Software/pkg-config/
-[vcpkg]: https://vcpkg.readthedocs.io/
-[howto-build]: https://tectonic-typesetting.github.io/book/latest/#update-link-when-published
-
-##### `geturl-curl`
-
-Use the [curl] crate to implement HTTP requests. In order for this to take
-effect, you must use `--no-default-features` because `geturl-reqwest` is a
-default feature and it takes precedence.
-
-[curl]: https://docs.rs/curl/
-
-##### `geturl-reqwest` (enabled by default)
-
-Use the [reqwest] crate to implement HTTP requests. This is the default
-selection.
-
-[reqwest]: https://docs.rs/reqwest/
-
-##### `native-tls-vendored`
-
-If using [reqwest], activate the `vendored` option in the [native-tls] crate,
-causing OpenSSL to be vendored. This can be useful when cross-compiling or
-building static binaries, but is discouraged because that means that the
-resulting binaries won't benefit from security fixes to system TLS libraries.
-
-[native-tls]: https://github.com/sfackler/rust-native-tls
-
-##### `serialization` (enabled by default)
-
-This feature enables (de)serialization using the [serde](https://serde.rs/)
-crate. At the moment, this is only used to read per-user configuration from a
-[TOML](https://github.com/toml-lang/toml) file. If this feature is disabled, the
-per-user configuration file will be silently ignored. This feature is provided
-because serialization requires the `serde_derive` crate, which in turn uses
-Rust’s `proc_macro` feature. The `proc_macro` functionality is difficult to
-build with statically linked targets, although Tectonic’s CI system
-[demonstrates how to make it work][static-proc-macro].
-
-[static-proc-macro]: https://github.com/tectonic-typesetting/tectonic-ci-support/tree/master/cross-images#readme

docs/src/getting-started/install.md

@@ -26,7 +26,7 @@ you should:
 4. Put that file in the appropriate location so that you can easily run it from
    your computer’s command prompt.
 
-[gh-latest]: https://github.com/tectonic-typesetting/tectonic/releases/latest
+[gh-latest]: https://tectonic-typesetting.github.io/latest.html
 [inst-packaged]: ../installation/index.md#pre-built-binary-packages
 [inst-ref]: ../installation/index.md
 

docs/src/installation/index.md

@@ -30,7 +30,7 @@ release is published with precompiled executables attached. Because Tectonic is
 distributed as a single executable, all you need to do is download the
 appropriate archive for your platform and unpack it.
 
-[gh-latest]: https://github.com/tectonic-typesetting/tectonic/releases/latest
+[gh-latest]: https://tectonic-typesetting.github.io/latest.html
 
 For instance, on most Linux systems, you’ll want to download the file with the
 name looking like `tectonic-<VERSION>-x86_64-unknown-linux-gnu.tar.gz`. This
@@ -68,14 +68,14 @@ complete, the command `conda` will now be available in your terminal.
 
 Once the `conda` command is available, you can install Tectonic and its support
 libraries using [conda-forge](http://conda-forge.github.io/), a community-led
-Conda packaing project. To install Tectonic you must activate conda-forge, which
-can be done temporarily like so:
+Conda packaging project. To install Tectonic you must activate conda-forge,
+which can be done temporarily like so:
 
 ```sh
-conda install -c conda-forge tectonic
+$ conda install -c conda-forge tectonic
 ```
 
-### Pre-built packages for Arch Linux
+### Arch Linux
 
 For users of [Arch Linux], there are two Tectonic packages available. The
 [tectonic-bin][arch-tectonic-bin] package on [AUR] provides actual pre-compiled
@@ -87,14 +87,68 @@ machine, which may take a while.
 [AUR]: https://aur.archlinux.org/
 [arch-tectonic]: https://aur.archlinux.org/packages/tectonic/
 
+### Homebrew
+
+There is a `tectonic` package in [Homebrew](https://brew.sh/). If you already
+have Homebrew installed, installing Tectonic should be as simple as:
+
+```sh
+$ brew install tectonic
+```
+
+We also have instructions about [installing Tectonic’s dependencies using
+Homebrew][homebrew-deps] if you’d like to compile Tectonic yourself on your
+Homebrew-based computer.
+
+[homebrew-deps]: /howto/build-tectonic/external-dep-install.md#homebrew-on-macos
+
+### MacPorts
+
+There is a `tectonic` port in [MacPorts](https://www.macports.org/). If you
+already have MacPorts installed, installing Tectonic should be as simple as:
+
+```sh
+$ sudo port install tectonic
+```
+
+### nix or nixOS
+
+If you're using [nix], you can imperatively install [`tectonic`][nix-tectonic] with:
+
+```sh
+$ nix-env -iA nixos.tectonic
+```
+
+in your shell. You can also create a temporary environment using
+[`nix-shell`](https://nixos.org/nix/manual/#sec-nix-shell):
+
+```sh
+$ nix-shell '<nixpkgs>' -A tectonic
+```
+
+[nix]: https://nixos.org/
+[nix-tectonic]: https://nixos.org/nixos/packages.html#tectonic
+
+### Void Linux
+
+Void Linux has a `tectonic` package in the [void-packages] repository. To
+install it, run:
+
+```sh
+$ sudo xbps-install -S tectonic
+```
+
+[void-packages]: https://github.com/void-linux/void-packages/blob/master/srcpkgs/tectonic/template
+
+
 
 ## Compile Tectonic Yourself
 
 You can always compile Tectonic yourself. If your system has C++ and Rust
 compilers installed, this may be as simple as running:
 
 ```sh
-cargo install tectonic
+$ cargo install tectonic
 ```
 
 However, Tectonic requires various C/C++ support libraries that may not be