From fb54a01764f50cf4be9366e399aeacfb2838f08d Mon Sep 17 00:00:00 2001 From: Martin Geisler Date: Wed, 2 Dec 2020 14:12:48 +0100 Subject: [PATCH] Document splitting pipeline --- src/core.rs | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/src/core.rs b/src/core.rs index 6da5de68..244168c8 100644 --- a/src/core.rs +++ b/src/core.rs @@ -3,6 +3,32 @@ //! The functions and structs in this module can be used to implement //! advanced wrapping functionality when the [`wrap`](super::wrap) and //! [`fill`](super::fill) function don't do what you want. +//! +//! In general, you want to follow these steps when wrapping +//! something: +//! +//! 1. Split your input into [`Fragment`]s. These are abstract blocks +//! of text or content which can be wrapped into lines. You can use +//! [`find_words`] to do this for text. +//! +//! 2. Potentially split your fragments into smaller pieces. This +//! allows you to implement things like hyphenation. If wrapping +//! text, [`split_words`] can help you do this. +//! +//! 3. Potentially break apart fragments that are still too large to +//! fit on a single line. This is implemented in [`break_words`]. +//! +//! 4. Finally take your fragments and put them into lines. There are +//! two algorithms for this: [`wrap_optimal_fit`] and +//! [`wrap_first_fit`]. The former produces better line breaks, the +//! latter is faster. +//! +//! 5. Iterate through the slices returned by the wrapping functions +//! and construct your lines of output. +//! +//! Please [open an issue](https://github.com/mgeisler/textwrap/) if +//! the functionality here is not sufficient or if you have ideas for +//! improving it. We would love to hear from you! use crate::{Options, WordSplitter}; use std::cell::RefCell;