Add {{#shiftinclude}} command #2333
Conversation
Syntax is the same as {{#include}} except with a shift value and colon
before the remaining arguments, e.g.
{{#include -2:somefile.rs:myanchor}}
A positive value for the shift prepends spaces to each line.
A negative value for the shift removes chars from the beginning of each
line (including non-whitespace chars, although this will emit an error
log).
As well as allowing explicitly-specified shift amounts, also support an "auto" option that strips common leftmost whitespace from an inclusion.
daviddrysdale
force-pushed
the
left-shift
branch
from
4b1b97b to
a886ff5
Compare
Taken from suggested pull request for upstream: rust-lang/mdBook#2333
Taken from suggested pull request for upstream: rust-lang/mdBook#2333
Taken from suggested pull request for upstream: rust-lang/mdBook#2333
|
Given that this looks unlikely to be included in the main mdBook code, I've pulled the functionality out into a separate |
src/preprocess/links.rs
Outdated
| Shift::Auto | ||
| } else { | ||
| let shift: isize = param0.parse().unwrap_or_else(|e| { | ||
| log::error!("failed to parse shift amount: {e:?}"); |
There was a problem hiding this comment.
This function should probably return an Option, so that the shiftinclude directive isn't parsed at all when there's an invalid shift amount.
The problem with this setup is that it isn't carrying the filename:linenumber in the error message, so finding the failed shiftinclude is really hard. If it refuses to parse it entirely, instead of substituting zero, it'll be easier to find where it failed by looking for the literal text {{#shiftinclude in your book.
There was a problem hiding this comment.
Ah, makes sense, thanks.
Done.
src/utils/string.rs
Outdated
| if l.chars().take(skip).any(|c| !c.is_whitespace()) { | ||
| log::error!("left-shifting away non-whitespace"); | ||
| } | ||
| let rest = l.chars().skip(skip).collect::<String>(); |
There was a problem hiding this comment.
As long as there's no easy way to report the line number where the error is actually occurring, it would probably be good to avoid left shifting away non-whitespace characters. That way, even if the indentation comes out weird, it won't come out broken.
| let rest = l.chars().skip(skip).collect::<String>(); | |
| let rest = l.chars() | |
| .take_while(|c| c.is_whitespace()) | |
| .skip(skip) | |
| .collect::<String>(); |
There was a problem hiding this comment.
Yeah, I was in two minds as to whether left-shift should remove non-whitespace or not. Done
Rather than defaulting to a shift of 0, instead just skip over a shiftinclude command with an invalid shift specifier.
Allows included code to be shifted left or right by a specified amount, or to be automatically left-shifted so that common leading whitespace is stripped.
Uses a new command name
#shiftincludeto avoid changing the behaviour of any existing books.There are few open issues1 that this might help with :
{{#shiftinclude auto:file.rs}}here.{{#include ...}}with indented #1564{{#shiftinclude +4:myfn.rs}}here.{{#shiftinclude auto:file.rs}}here.{{#shiftinclude +4:../exercises/chapter6/test/no-peeking/Solutions.purs:eqNonEmpty}}(but would need to be left-aligned).There are also a few open PRs that this might overtake/replace/combine-with:
{{#include}}is indented #1565autovariant here (and is also careful not to affect existing behaviour).Footnotes
I confess that I implemented this without looking at the current open issues/pull requests. ↩