From ede8423e921afb4396b429059ae617d522583226 Mon Sep 17 00:00:00 2001 From: cubetastic Date: Tue, 30 Jul 2019 22:18:05 +0530 Subject: [PATCH] Update docs, fix minor typos, rephrase some parts of the tutorials (#364) Also mention that strikethrough doesn't work with ncurses and blt. --- doc/tutorial_1.md | 18 +++++++++--------- doc/tutorial_2.md | 8 ++++---- doc/tutorial_3.md | 8 ++++---- src/cursive.rs | 4 ++-- src/lib.rs | 4 ++-- src/theme/effect.rs | 2 +- 6 files changed, 22 insertions(+), 22 deletions(-) diff --git a/doc/tutorial_1.md b/doc/tutorial_1.md index 94b5699..3dfefab 100644 --- a/doc/tutorial_1.md +++ b/doc/tutorial_1.md @@ -20,7 +20,7 @@ fn main() { } ``` -Run this application, and you should have something like that: +Run the application, and you should have something like this: ![Tutorial 1 goal](./tutorial_1.png) @@ -61,9 +61,9 @@ The cursive library is configured through a main [`Cursive`] root. A typical cursive application will consist of three phases, all centered around this object: -1. Create a `Cursive` object. -2. Configure the `Cursive` object. -3. Run the `Cursive` object. +1. Create a `Cursive` object +2. Configure the `Cursive` object +3. Run the `Cursive` object Of these, the configuration phase is often the largest one, so let's skip it for now. @@ -93,14 +93,14 @@ Let's first add a way to stop the application. We want to quit when the user presses the letter `q`. Cursive sends an event for every user input; most of these are just ignored -and have no effect. The `Cursive` root has a [`add_global_callback`] method to +and have no effect. The `Cursive` root has an [`add_global_callback`] method to call a function anytime a certain event is fired. This method takes 2 arguments: a trigger, and a callback. * The trigger needs to implement `Into`. In addition to [`event::Event`] itself, this includes [`event::Key`], or simply `char`. These will trigger when the corresponding key (or letter) is pressed. -* The callback should be a function taking a `&mut Cursive` as argument. Here, +* The callback should be a function taking an `&mut Cursive` as an argument. Here, we want to quit, so we'll use [`Cursive::quit`] in a closure: `|s| s.quit()`. In the end, we have: @@ -117,8 +117,8 @@ fn main() { } ``` -As expected, running it show no visible change, but hitting the `q` key at -least closes the application. +As expected, running it shows no visible change, but hitting the `q` key does +close the application. [`add_global_callback`]: https://docs.rs/cursive/0/cursive/struct.Cursive.html#method.add_global_callback [`event::Event`]: https://docs.rs/cursive/0/cursive/event/enum.Event.html @@ -139,7 +139,7 @@ The `TextView` constructor just takes the text to use: `TextView::new("...")`. The `Cursive` root itself uses a [`StackView`] on the entire screen. This `StackView` unsurprisingly stacks views in layers. It starts empty, so we'll -just need to add our `TextView` as a layer. The [`Cursive::add_layer`] does +just need to add our `TextView` as a layer. [`Cursive::add_layer`] lets us do exactly that. Once we've added this line, our first application is complete: diff --git a/doc/tutorial_2.md b/doc/tutorial_2.md index ae26893..0b4baca 100644 --- a/doc/tutorial_2.md +++ b/doc/tutorial_2.md @@ -86,14 +86,14 @@ siv.add_layer(Dialog::text("...")); ``` Next, let's add a title. To do that, `Dialog` has a chainable [`Dialog::title`] -method. It takes the dialog by value, and return it back, making function +method. It takes the dialog by value, and returns it back, making function chains easy: ```rust,ignore siv.add_layer(Dialog::text("...").title("...")); ``` -This way of chaining method to set-up the view is very common in cursive. Most +This way of chaining methods to set-up the view is very common in cursive. Most views provide chainable variants of their methods, to allow creating the view and configuring it in one spot. @@ -120,7 +120,7 @@ siv.add_layer(Dialog::text("...") Only this time, we don't want to exit the application right away. Instead of packing everything into the closure, let's use a separate function for the -callback. Here is the current state: +callback. Here's the current state: ```rust,no_run use cursive::Cursive; @@ -209,7 +209,7 @@ a new `Dialog` instead. Your code should now look like the one at the top of this guide. As you've seen, the `Dialog` view is a nice way to present a `TextView`, but it -works with any other content. Actually, most layers you'll add will start with +also works with any other content. Actually, most layers you'll add will start with a `Dialog` wrapping some other view. Next: [Starting with Cursive (3/3)](./tutorial_3.md) diff --git a/doc/tutorial_3.md b/doc/tutorial_3.md index 0126787..e3138d8 100644 --- a/doc/tutorial_3.md +++ b/doc/tutorial_3.md @@ -146,12 +146,12 @@ replace the layer with a simple dialog. ## Linear layouts -Our main screen is more complex than our previous examples: it is made of +Our main screen is more complex than in our previous examples: it is made of several views. There is a `SelectView` on the left, and three [`Button`]s to -the right. But our [`Dialog::around`] method only takes one view! How will we do? +the right. But our [`Dialog::around`] method only takes one view! How will we do this? The solution is to use a layout view to display multiple children side-by-side. -[`LinearLayout`] for instance can display views in a line. +[`LinearLayout`], for instance, can display views in a line. We'll use two of them: * One, set vertically, will hold the buttons on the right. @@ -171,7 +171,7 @@ fn delete_name(s: &mut Cursive) {} ``` Buttons here take a regular callback. We're also adding a [`DummyView`] here: -this view doesn't do anything, it just occupies a single row - we're using it +this view doesn't do anything, it just occupies some space - we're using it as a cheap spacer. We can now create the second linear layout inside a Dialog: diff --git a/src/cursive.rs b/src/cursive.rs index 970bd41..e82ed63 100644 --- a/src/cursive.rs +++ b/src/cursive.rs @@ -23,8 +23,8 @@ const INPUT_POLL_DELAY_MS: u64 = 30; /// Central part of the cursive library. /// /// It initializes ncurses on creation and cleans up on drop. -/// To use it, you should populate it with views, layouts and callbacks, -/// then start the event loop with run(). +/// To use it, you should populate it with views, layouts, and callbacks, +/// then start the event loop with `run()`. /// /// It uses a list of screen, with one screen active at a time. pub struct Cursive { diff --git a/src/lib.rs b/src/lib.rs index 4326cad..700ab1e 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -27,7 +27,7 @@ //! Cursive is callback-driven: it reacts to events generated by user input. //! //! During the declarative phase, callbacks are set to trigger on specific -//! events. These functions usually take a `&mut Cursive` argument, allowing +//! events. These functions usually take an `&mut Cursive` argument, allowing //! them to modify the view tree at will. //! //! ## Examples @@ -49,7 +49,7 @@ //! //! ## Debugging //! -//! The `Cursive` root initializes the terminal on creation, and do cleanups +//! The `Cursive` root initializes the terminal on creation, and does cleanups //! on drop. While it is alive, printing to the terminal will not work //! as expected, making debugging a bit harder. //! diff --git a/src/theme/effect.rs b/src/theme/effect.rs index 87aef61..1f72593 100644 --- a/src/theme/effect.rs +++ b/src/theme/effect.rs @@ -11,7 +11,7 @@ pub enum Effect { Bold, /// Prints foreground in italic Italic, - /// Prints foreground with strikethrough + /// Prints foreground with strikethrough (has no effect for ncurses and blt backends) Strikethrough, /// Prints foreground with underline Underline,