From 615a79d43cab28c6c973b495d5c7745acadfe6f6 Mon Sep 17 00:00:00 2001 From: boxdot Date: Sat, 27 Jan 2018 23:54:25 +0100 Subject: [PATCH 1/2] Add docs for mdBook specific include feature. Also: * Fix bug in take_lines taking `end`-many lines instead of `end-start` many. * Handle special case `include:number` as including a single line. * Start counting lines at 1 and not 0. --- book-example/src/SUMMARY.md | 1 + book-example/src/format/mdbook.md | 22 +++++++++++++++ src/preprocess/links.rs | 46 +++++++++++++++++++++++++++---- src/utils/string.rs | 7 +++-- 4 files changed, 68 insertions(+), 8 deletions(-) create mode 100644 book-example/src/format/mdbook.md diff --git a/book-example/src/SUMMARY.md b/book-example/src/SUMMARY.md index aba9ab5d45..e3a4c42f20 100644 --- a/book-example/src/SUMMARY.md +++ b/book-example/src/SUMMARY.md @@ -15,6 +15,7 @@ - [Syntax highlighting](format/theme/syntax-highlighting.md) - [Editor](format/theme/editor.md) - [MathJax Support](format/mathjax.md) + - [mdBook specific features](format/mdbook.md) - [Rust code specific features](format/rust.md) - [For Developers](for_developers/index.md) - [Preprocessors](for_developers/preprocessors.md) diff --git a/book-example/src/format/mdbook.md b/book-example/src/format/mdbook.md new file mode 100644 index 0000000000..b1ffd9b9e1 --- /dev/null +++ b/book-example/src/format/mdbook.md @@ -0,0 +1,22 @@ +# mdBook specific markdown + +## Including files + +With the following syntax, you can include files into your book: + +```hbs +\{{#include file.rs}} +``` + +The path to the file has to be relative from the current source file. + +Usually, this command is used for including code snippets and examples. In this case, oftens one would include a specific part of the file e.g. which only contains the relevant lines for the example. We support four different modes of partial includes: + +```hbs +\{{#include file.rs:2}} +\{{#include file.rs::10}} +\{{#include file.rs:2:}} +\{{#include file.rs:2:10}} +``` + +The first command only includes the second line from file `file.rs`. The second command includes all lines up to line 10, i.e. the lines from 11 till the end of the file are omitted. The third command includes all lines from line 2, i.e. the first line is omitted. The last command includes the excerpt of `file.rs` consisting of lines 2 to 10. diff --git a/src/preprocess/links.rs b/src/preprocess/links.rs index fda175cb26..e537197582 100644 --- a/src/preprocess/links.rs +++ b/src/preprocess/links.rs @@ -10,7 +10,7 @@ use book::{Book, BookItem}; const ESCAPE_CHAR: char = '\\'; -/// A preprocessor for expanding the `{{# playpen}}` and `{{# include}}` +/// A preprocessor for expanding the `{{# playpen}}` and `{{# include}}` /// helpers in a chapter. pub struct LinkPreprocessor; @@ -87,8 +87,14 @@ enum LinkType<'a> { fn parse_include_path(path: &str) -> LinkType<'static> { let mut parts = path.split(':'); let path = parts.next().unwrap().into(); - let start = parts.next().and_then(|s| s.parse::().ok()); - let end = parts.next().and_then(|s| s.parse::().ok()); + // subtract 1 since line numbers usually begin with 1 + let start = parts + .next() + .and_then(|s| s.parse::().ok()) + .map(|val| val.checked_sub(1).unwrap_or(0)); + let end = parts.next(); + let has_end = end.is_some(); + let end = end.and_then(|s| s.parse::().ok()); match start { Some(start) => match end { Some(end) => LinkType::IncludeRange( @@ -98,7 +104,17 @@ fn parse_include_path(path: &str) -> LinkType<'static> { end: end, }, ), - None => LinkType::IncludeRangeFrom(path, RangeFrom { start: start }), + None => if has_end { + LinkType::IncludeRangeFrom(path, RangeFrom { start: start }) + } else { + LinkType::IncludeRange( + path, + Range { + start: start, + end: start + 1, + }, + ) + }, }, None => match end { Some(end) => LinkType::IncludeRangeTo(path, RangeTo { end: end }), @@ -276,13 +292,31 @@ mod tests { Link { start_index: 22, end_index: 48, - link: LinkType::IncludeRange(PathBuf::from("file.rs"), 10..20), + link: LinkType::IncludeRange(PathBuf::from("file.rs"), 9..20), link_text: "{{#include file.rs:10:20}}", }, ] ); } + #[test] + fn test_find_links_with_line_number() { + let s = "Some random text with {{#include file.rs:10}}..."; + let res = find_links(s).collect::>(); + println!("\nOUTPUT: {:?}\n", res); + assert_eq!( + res, + vec![ + Link { + start_index: 22, + end_index: 45, + link: LinkType::IncludeRange(PathBuf::from("file.rs"), 9..10), + link_text: "{{#include file.rs:10}}", + }, + ] + ); + } + #[test] fn test_find_links_with_from_range() { let s = "Some random text with {{#include file.rs:10:}}..."; @@ -294,7 +328,7 @@ mod tests { Link { start_index: 22, end_index: 46, - link: LinkType::IncludeRangeFrom(PathBuf::from("file.rs"), 10..), + link: LinkType::IncludeRangeFrom(PathBuf::from("file.rs"), 9..), link_text: "{{#include file.rs:10:}}", }, ] diff --git a/src/utils/string.rs b/src/utils/string.rs index 8877d3769a..2245909325 100644 --- a/src/utils/string.rs +++ b/src/utils/string.rs @@ -50,7 +50,7 @@ pub fn take_lines>(s: &str, range: R) -> String { let start = *range.start().unwrap_or(&0); let mut lines = s.lines().skip(start); match range.end() { - Some(&end) => lines.take(end).join("\n"), + Some(&end) => lines.take(end.checked_sub(start).unwrap_or(0)).join("\n"), None => lines.join("\n"), } } @@ -62,9 +62,12 @@ mod tests { #[test] fn take_lines_test() { let s = "Lorem\nipsum\ndolor\nsit\namet"; - assert_eq!(take_lines(s, 0..3), "Lorem\nipsum\ndolor"); + assert_eq!(take_lines(s, 1..3), "ipsum\ndolor"); assert_eq!(take_lines(s, 3..), "sit\namet"); assert_eq!(take_lines(s, ..3), "Lorem\nipsum\ndolor"); assert_eq!(take_lines(s, ..), s); + // corner cases + assert_eq!(take_lines(s, 4..3), ""); + assert_eq!(take_lines(s, ..100), s); } } From 5b0c67669e5468cf17a75388535fac1546acc933 Mon Sep 17 00:00:00 2001 From: boxdot Date: Sun, 28 Jan 2018 17:53:40 +0100 Subject: [PATCH 2/2] Merge mdBook and rust specific features into one chapter. --- book-example/src/SUMMARY.md | 1 - book-example/src/format/mdbook.md | 42 +++++++++++++++++++++++++++++ book-example/src/format/rust.md | 44 ------------------------------- 3 files changed, 42 insertions(+), 45 deletions(-) delete mode 100644 book-example/src/format/rust.md diff --git a/book-example/src/SUMMARY.md b/book-example/src/SUMMARY.md index e3a4c42f20..cedb894918 100644 --- a/book-example/src/SUMMARY.md +++ b/book-example/src/SUMMARY.md @@ -16,7 +16,6 @@ - [Editor](format/theme/editor.md) - [MathJax Support](format/mathjax.md) - [mdBook specific features](format/mdbook.md) - - [Rust code specific features](format/rust.md) - [For Developers](for_developers/index.md) - [Preprocessors](for_developers/preprocessors.md) - [Alternate Backends](for_developers/backends.md) diff --git a/book-example/src/format/mdbook.md b/book-example/src/format/mdbook.md index b1ffd9b9e1..81f6b5b557 100644 --- a/book-example/src/format/mdbook.md +++ b/book-example/src/format/mdbook.md @@ -1,5 +1,29 @@ # mdBook specific markdown +## Hiding code lines + +There is a feature in mdBook that let's you hide code lines by prepending them with a `#`. + +```bash +# fn main() { + let x = 5; + let y = 6; + + println!("{}", x + y); +# } +``` + +Will render as + +```rust +# fn main() { + let x = 5; + let y = 7; + + println!("{}", x + y); +# } +``` + ## Including files With the following syntax, you can include files into your book: @@ -20,3 +44,21 @@ Usually, this command is used for including code snippets and examples. In this ``` The first command only includes the second line from file `file.rs`. The second command includes all lines up to line 10, i.e. the lines from 11 till the end of the file are omitted. The third command includes all lines from line 2, i.e. the first line is omitted. The last command includes the excerpt of `file.rs` consisting of lines 2 to 10. + +## Inserting runnable Rust files + +With the following syntax, you can insert runnable Rust files into your book: + +```hbs +\{{#playpen file.rs}} +``` + +The path to the Rust file has to be relative from the current source file. + +When play is clicked, the code snippet will be send to the [Rust Playpen] to be compiled and run. The result is send back and displayed directly underneath the code. + +Here is what a rendered code snippet looks like: + +{{#playpen example.rs}} + +[Rust Playpen]: https://play.rust-lang.org/ diff --git a/book-example/src/format/rust.md b/book-example/src/format/rust.md deleted file mode 100644 index 3b84534af4..0000000000 --- a/book-example/src/format/rust.md +++ /dev/null @@ -1,44 +0,0 @@ -# Rust code specific features - -## Hiding code lines - -There is a feature in mdBook that let's you hide code lines by prepending them with a `#`. - -```bash -# fn main() { - let x = 5; - let y = 6; - - println!("{}", x + y); -# } -``` - -Will render as - -```rust -# fn main() { - let x = 5; - let y = 7; - - println!("{}", x + y); -# } -``` - - -## Inserting runnable Rust files - -With the following syntax, you can insert runnable Rust files into your book: - -```hbs -\{{#playpen file.rs}} -``` - -The path to the Rust file has to be relative from the current source file. - -When play is clicked, the code snippet will be send to the [Rust Playpen] to be compiled and run. The result is send back and displayed directly underneath the code. - -Here is what a rendered code snippet looks like: - -{{#playpen example.rs}} - -[Rust Playpen]: https://play.rust-lang.org/ \ No newline at end of file