google / google/comprehensive-rust
Exclude "In this segment" outlines and keyboard shortcuts from PDF
- Dominant language
- Rust
- Stars
- 33.4k
- Forks
- 2.1k
- Avg merge
- 1d 3h
- Merged PRs (30d)
- 10
Description
In #1572, @mgeisler asked:
> Do you know of a way to exclude/include content in the PDF? As an example, [1.2. Keyboard Shortcuts](https://google.github.io/comprehensive-rust/running-the-course/keyboard-shortcuts.html) should not be shown in the PDF. Similarly, the "In this segment" texts (as seen in [12. Pattern Matching](https://google.github.io/comprehensive-rust/pattern-matching.html)) should also go away.
I got another ask for adding this to `mdbook-pandoc` (https://github.com/max-heller/mdbook-pandoc/discussions/206) so I wanted to revisit and clarify the desired outcome.
1. For excluding portions of chapters such as the "In this segment" snippets, the most straightforward approach would likely be to add a class like `mdbook-pandoc::skip` to a div/header/etc. It looks like the snippets are generated from `{{%segment outline}}` placeholders by `mdbook-course`; which of the following options makes the most sense?
1. Disable `mdbook-course` when building with `mdbook-pandoc` and use a Pandoc filter to strip `{{%segment outline}}` placeholders from the source (this seems best to me)
2. Wrap `{{%segment outline}}` placeholders in the book with `
3. Have `mdbook-course` tag snippets with `mdbook-pandoc::skip` (this feels wrong)
2. If *1.2. Keyboard Shortcuts* is excluded from the PDF, should *1.3. Translations* remain numbered as 1.3 (i.e., leave a gap between 1.1 and 1.3) or be shifted up to *1.2. Translations*? My intuition says that having chapter numbers match between the PDF and HTML forms is important, but gaps in numbering would also be confusing and I'm not sure if Pandoc even has a way to leave such a gap.
How would you prefer to specify which chapters should be excluded?
1. List chapters to exclude in `book.toml`
2. Tag the chapter heading with `mdbook-pandoc::skip` (simple but requires source annotation)
Contributor guide
Assessment
This issue has not been assessed yet.