blob42/rusty-man
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
07996d9dd6
rusty-man/README.md

129 lines
4.4 KiB
Markdown
Raw Normal View History

Initial project scaffolding This patch contains the initial project scaffolding, based on the files generated by cargo new.
2020-01-12 10:50:40 +00:00
<!---
SPDX-FileCopyrightText: 2020 Robin Krahl <robin.krahl@ireas.org>
SPDX-License-Identifier: MIT
-->
# rusty-man
Update readme This patch updates the readme with better usage examples and with the documentation for rusty-man itself. Signed-off-by: Robin Krahl <robin.krahl@ireas.org>
2020-07-24 10:36:49 +00:00
```
Rewrap example in readme to 80 columns This makes it easier to read the example e. g. on crates.io.
2020-07-28 12:57:52 +00:00
$ rusty-man rusty-man | head -5
rusty-man Module rusty-man rusty-man
Update readme This patch updates the readme with better usage examples and with the documentation for rusty-man itself. Signed-off-by: Robin Krahl <robin.krahl@ireas.org>
2020-07-24 10:36:49 +00:00
DESCRIPTION
Rewrap example in readme to 80 columns This makes it easier to read the example e. g. on crates.io.
2020-07-28 12:57:52 +00:00
rusty-man is a command-line viewer for documentation generated by
`rustdoc`.
Update readme This patch updates the readme with better usage examples and with the documentation for rusty-man itself. Signed-off-by: Robin Krahl <robin.krahl@ireas.org>
2020-07-24 10:36:49 +00:00
```
Initial project scaffolding This patch contains the initial project scaffolding, based on the files generated by cargo new.
2020-01-12 10:50:40 +00:00
Add installation and contributing information This patch extends the README.md file and adds the INSTALL.md and CONTRIBUTING.md files with more detailed information.
2020-07-19 23:34:56 +00:00
## Example Usage
Update readme This patch updates the readme with better usage examples and with the documentation for rusty-man itself. Signed-off-by: Robin Krahl <robin.krahl@ireas.org>
2020-07-24 10:36:49 +00:00
Before running rusty-man, make sure that you generated the documentation with
`cargo doc`:
Add installation and contributing information This patch extends the README.md file and adds the INSTALL.md and CONTRIBUTING.md files with more detailed information.
2020-07-19 23:34:56 +00:00
```
$ cd rusty-man && cargo doc
Update readme This patch updates the readme with better usage examples and with the documentation for rusty-man itself. Signed-off-by: Robin Krahl <robin.krahl@ireas.org>
2020-07-24 10:36:49 +00:00
```
Add installation and contributing information This patch extends the README.md file and adds the INSTALL.md and CONTRIBUTING.md files with more detailed information.
2020-07-19 23:34:56 +00:00
Update readme This patch updates the readme with better usage examples and with the documentation for rusty-man itself. Signed-off-by: Robin Krahl <robin.krahl@ireas.org>
2020-07-24 10:36:49 +00:00
Then you can open the documentation for an item:
```
$ rusty-man kuchiki::NodeRef
```
Add installation and contributing information This patch extends the README.md file and adds the INSTALL.md and CONTRIBUTING.md files with more detailed information.
2020-07-19 23:34:56 +00:00
Update readme This patch updates the readme with better usage examples and with the documentation for rusty-man itself. Signed-off-by: Robin Krahl <robin.krahl@ireas.org>
2020-07-24 10:36:49 +00:00
You don’t have to specificy the full item name:
```
$ rusty-man NodeRef
```
Add installation and contributing information This patch extends the README.md file and adds the INSTALL.md and CONTRIBUTING.md files with more detailed information.
2020-07-19 23:34:56 +00:00
Use rustc --print sysroot for default sources Previously, we were used /usr/share/doc/rust{,-doc}/html as a default source, assuming that it would contain the standard library documentation. This is true if the user installed the Rust documentation manually or using a package manager. If they use rustup instead, the documentation is placed in a subdirectory of ~/.rustup. With this patch, we call `rustc --print sysroot` to determine the installation directory of the currently activated Rust toolchain – either the system Rust installation or a Rust installation managed by rustup. We then use `$(sysroot)/share/doc/…` as a default path for the standard library documentation (with /usr as a fallback if the call to rustc does not return a valid path).
2020-07-25 17:06:27 +00:00
If the documentation is not placed in `./target/doc` or the Rust installation
directory, you have to manually set the source path using the `-s`/`--source`
option:
Update readme This patch updates the readme with better usage examples and with the documentation for rusty-man itself. Signed-off-by: Robin Krahl <robin.krahl@ireas.org>
2020-07-24 10:36:49 +00:00
```
Use rustc --print sysroot for default sources Previously, we were used /usr/share/doc/rust{,-doc}/html as a default source, assuming that it would contain the standard library documentation. This is true if the user installed the Rust documentation manually or using a package manager. If they use rustup instead, the documentation is placed in a subdirectory of ~/.rustup. With this patch, we call `rustc --print sysroot` to determine the installation directory of the currently activated Rust toolchain – either the system Rust installation or a Rust installation managed by rustup. We then use `$(sysroot)/share/doc/…` as a default path for the standard library documentation (with /usr as a fallback if the call to rustc does not return a valid path).
2020-07-25 17:06:27 +00:00
$ rusty-man --source my/other/crate/target/doc io::Error
Update readme This patch updates the readme with better usage examples and with the documentation for rusty-man itself. Signed-off-by: Robin Krahl <robin.krahl@ireas.org>
2020-07-24 10:36:49 +00:00
```
Add installation and contributing information This patch extends the README.md file and adds the INSTALL.md and CONTRIBUTING.md files with more detailed information.
2020-07-19 23:34:56 +00:00
Update readme This patch updates the readme with better usage examples and with the documentation for rusty-man itself. Signed-off-by: Robin Krahl <robin.krahl@ireas.org>
2020-07-24 10:36:49 +00:00
If there are multiple matches for the keyword, rusty-man will show you a list
of all matching items:
```
Use rustc --print sysroot for default sources Previously, we were used /usr/share/doc/rust{,-doc}/html as a default source, assuming that it would contain the standard library documentation. This is true if the user installed the Rust documentation manually or using a package manager. If they use rustup instead, the documentation is placed in a subdirectory of ~/.rustup. With this patch, we call `rustc --print sysroot` to determine the installation directory of the currently activated Rust toolchain – either the system Rust installation or a Rust installation managed by rustup. We then use `$(sysroot)/share/doc/…` as a default path for the standard library documentation (with /usr as a fallback if the call to rustc does not return a valid path).
2020-07-25 17:06:27 +00:00
$ rusty-man --source my/other/crate/target/doc u8
Add installation and contributing information This patch extends the README.md file and adds the INSTALL.md and CONTRIBUTING.md files with more detailed information.
2020-07-19 23:34:56 +00:00
Found mulitple matches for u8 – select one of:
[ 0 ] core::u8: The 8-bit unsigned integer type.
[ 1 ] std::u8: The 8-bit unsigned integer type.
> 1
```
Update readme This patch updates the readme with better usage examples and with the documentation for rusty-man itself. Signed-off-by: Robin Krahl <robin.krahl@ireas.org>
2020-07-24 10:36:49 +00:00
For more usage information, run `rusty-man --help`.
Add TUI viewer using cursive This patch adds a new viewer, tui, that provides an interactive interface using cursive. This viewer makes it possible to follow links to other documentation items and to open external links in a web browser.
2020-09-15 15:32:06 +00:00
## Viewers
rusty-man has three viewers (select one with the `--viewer` option) that
determine the output format:
- `plain` prints the documentation to the standard output without formatting.
This is the default for non-interactive use.
- `rich` prints the documentation to the standard output with formatting and
optional syntax highlighting. This is the default for interactive use.
- `tui` is an interactive terminal interface. You can read the documentation
and follow links.
Add installation and contributing information This patch extends the README.md file and adds the INSTALL.md and CONTRIBUTING.md files with more detailed information.
2020-07-19 23:34:56 +00:00
## Installation
Update installation instructions This patch updates the installation instructions with information on the AUR packgage and on the tarball downloads.
2020-08-11 07:59:43 +00:00
To install rusty-man from source, clone this repository and use cargo to build
the project, or use `cargo install`. See the [`INSTALL.md`][] file for more
information. rusty-man is also available as a package for these distributions:
- Arch Linux: [`rusty-man`][pkg-aur] in the Arch User Repository
Add installation and contributing information This patch extends the README.md file and adds the INSTALL.md and CONTRIBUTING.md files with more detailed information.
2020-07-19 23:34:56 +00:00
Add TUI viewer using cursive This patch adds a new viewer, tui, that provides an interactive interface using cursive. This viewer makes it possible to follow links to other documentation items and to open external links in a web browser.
2020-09-15 15:32:06 +00:00
rusty-man is developed for Unix-like systems. It should run on other platforms
Use termion backend for cursive With this patch, we replace cursive’s default ncurses backend with the termion backend. This has multiple reasons: - The ncurses backend has safety issues, see [0]. - ncurses requires a pre-installed library and a C compiler, introducing additional build dependencies. Termion is implemented in Rust only. - ncurses does not work on Windows, while termion works in all terminals that support ANSI escape codes. Per default, the termion backend does not buffer the output which may cause flickering [1]. Therefore, we also use the cursive_buffered_backend that buffers the output and fixes the flickering problem. [0] https://github.com/gyscos/cursive/issues/488 [1] https://github.com/gyscos/cursive/issues/142
2020-10-08 08:19:21 +00:00
too, but with some limitations: The `rich` and `tui` viewers uses ANSI escape
codes, which are not supported on older Windows versions. If you have trouble
running rusty-man on your platform or if you want to help porting rusty-man to
other platforms, please let me know.
Add installation and contributing information This patch extends the README.md file and adds the INSTALL.md and CONTRIBUTING.md files with more detailed information.
2020-07-19 23:34:56 +00:00
Add vim integration to readme This patch adds information about calling rusty-man from vim to the readme.
2020-07-24 20:47:13 +00:00
## Integrations
### vim
You can set rusty-man as the keyword program with `set keywordprg=rusty-man`
and then use `K` to open the documentation for the item under the cursor. If
you want to apply this setting for all Rust files, add it to the
`ftplugin/rust.vim` file in your vim runtime directory (e. g. `~/.vim`).
Add installation and contributing information This patch extends the README.md file and adds the INSTALL.md and CONTRIBUTING.md files with more detailed information.
2020-07-19 23:34:56 +00:00
## Contributing
Contributions to this project are very welcome! You can contribute by writing
Extend contributing guide This patch extends the CONTRIBUTING.md file with more information on possible tasks, the test suite and the code checks.
2020-07-20 08:23:28 +00:00
code or documentation or by testing. See the [`CONTRIBUTING.md`][] file for
more information.
Add installation and contributing information This patch extends the README.md file and adds the INSTALL.md and CONTRIBUTING.md files with more detailed information.
2020-07-19 23:34:56 +00:00
If you are looking for a good starting point, have a look at the [issues with
the label “good first issue”][issues] in rusty-man’s issue tracker.
Initial project scaffolding This patch contains the initial project scaffolding, based on the files generated by cargo new.
2020-01-12 10:50:40 +00:00
## Minimum Supported Rust Version
Add --viewer option and plain text viewer This patch adds a new --viewer command line option that lets the user select a viewer that displays the documentation. It also adds a default viewer implementation that uses html2text to generate plain text from the HTML documentation. html2text requires the ptr_cast feature and we use the Option::as_deref method in the viewer implementation, so we have to update the minimum supported Rust version to 1.40.
2020-07-16 19:01:29 +00:00
This crate supports Rust 1.40 or later.
Initial project scaffolding This patch contains the initial project scaffolding, based on the files generated by cargo new.
2020-01-12 10:50:40 +00:00
## Contact
For bug reports, patches, feature requests or other messages, please send a
Add installation and contributing information This patch extends the README.md file and adds the INSTALL.md and CONTRIBUTING.md files with more detailed information.
2020-07-19 23:34:56 +00:00
mail to the mailing list [~ireas/rusty-man-dev@lists.sr.ht][] ([public
Extend contributing guide This patch extends the CONTRIBUTING.md file with more information on possible tasks, the test suite and the code checks.
2020-07-20 08:23:28 +00:00
archive][]) or [contact me directly][]. You can also use the rusty-man [issue
tracker][] for bug reports or features requests.
Initial project scaffolding This patch contains the initial project scaffolding, based on the files generated by cargo new.
2020-01-12 10:50:40 +00:00
## License
Refactor test suite to check multiple versions This patch refactors the test suite: - Instead of always generating the documentation with the available rustdoc version, we now store generated documentation for all supported rustdoc versions in the test/html directory. - Instead of using one snapshot per test case, we now use one snapshot per test case and rustdoc version.
2020-09-11 16:14:19 +00:00
This project is licensed under the [MIT License][]. For license information
for the data used by the test suite, see the [`.reuse/dep5`][] file.
Initial project scaffolding This patch contains the initial project scaffolding, based on the files generated by cargo new.
2020-01-12 10:50:40 +00:00
`rusty-man` complies with [version 3.0 of the REUSE specification][reuse].
Use crossterm instead of termion With this patch, we replace the termion dependency with crossterm. This should make it possible to compile and run rusty-man on other platforms than Unix.
2020-07-24 11:18:35 +00:00
[`crossterm`]: https://lib.rs/crossterm
Use absolute links in readme This fixes missing links on crates.io.
2020-07-24 12:21:37 +00:00
[`INSTALL.md`]: https://git.sr.ht/~ireas/rusty-man/tree/refs/heads/master/INSTALL.md
[`CONTRIBUTING.md`]: https://git.sr.ht/~ireas/rusty-man/tree/refs/heads/master/CONTRIBUTING.md
Add installation and contributing information This patch extends the README.md file and adds the INSTALL.md and CONTRIBUTING.md files with more detailed information.
2020-07-19 23:34:56 +00:00
[issues]: https://todo.sr.ht/~ireas/rusty-man?search=label:%22good%20first%20issue%22%20status%3Aopen
[~ireas/rusty-man-dev@lists.sr.ht]: mailto:~ireas/rusty-man-dev@lists.sr.ht
Extend contributing guide This patch extends the CONTRIBUTING.md file with more information on possible tasks, the test suite and the code checks.
2020-07-20 08:23:28 +00:00
[contact me directly]: mailto:robin.krahl@ireas.org
Add installation and contributing information This patch extends the README.md file and adds the INSTALL.md and CONTRIBUTING.md files with more detailed information.
2020-07-19 23:34:56 +00:00
[public archive]: https://lists.sr.ht/~ireas/rusty-man-dev
[issue tracker]: https://todo.sr.ht/~ireas/rusty-man
Initial project scaffolding This patch contains the initial project scaffolding, based on the files generated by cargo new.
2020-01-12 10:50:40 +00:00
[MIT license]: https://opensource.org/licenses/MIT
Refactor test suite to check multiple versions This patch refactors the test suite: - Instead of always generating the documentation with the available rustdoc version, we now store generated documentation for all supported rustdoc versions in the test/html directory. - Instead of using one snapshot per test case, we now use one snapshot per test case and rustdoc version.
2020-09-11 16:14:19 +00:00
[`.reuse/dep5`]: https://git.sr.ht/~ireas/rusty-man/tree/refs/heads/master/.reuse/dep5
Initial project scaffolding This patch contains the initial project scaffolding, based on the files generated by cargo new.
2020-01-12 10:50:40 +00:00
[reuse]: https://reuse.software/practices/3.0/
Update installation instructions This patch updates the installation instructions with information on the AUR packgage and on the tarball downloads.
2020-08-11 07:59:43 +00:00
[pkg-aur]: https://aur.archlinux.org/packages/rusty-man/
Reference in New Issue Copy Permalink