Extract code into runnable Rust files

[simonsan]

With the Translation feature (#345) coming in I want to discuss something, that would make translations easier and maybe even give us the possibility to easily check, format and test code in this book.

What I imagine is:

• extract all code examples into a patterns crate (2021 edition)
• make examples runnable on their own
• embed code into the pages

See here: https://rust-lang.github.io/mdBook/format/mdbook.html#inserting-runnable-rust-files

This would make it a bit more clear which parts need to be translated and we could even easily go for auto-translation of some parts.

What I'm unsure about, is the disadvantages it would bring, especially for contributions and maintenance.
Any thoughts?

[mgeisler]

I've thought a bit about this for https://github.com/google/comprehensive-rust :-) In general, moving code snippets from the Markdown file to .rs files makes it harder to understand the book itself. However, having .rs files comes with advantages in terms of editor support (syntax highlighting) and formatting, etc.

format and

For this, I plan to use dprint.dev which will format code snippets inside Markdown files.

test code in this book.

I haven't checked what kind of code you typically have in your examples, but mdbook test works pretty well for us. I'm also planning to take a closer look at mdbook-keeper: https://github.com/tfpk/mdbook-keeper/.

[simonsan]

Oh, dprint is a nice tool, thanks for the recommendation. So do I understand you right, that you would advise us against extracting the code examples, because the only benefits would be editor support? And as you wrote in the other issue, that it would make translations "fuzzy" if more than paragraphs changed?

[mgeisler]

So do I understand you right, that you would advise us against extracting the code examples, because the only benefits would be editor support?

I've been working in a special constrained environment because I'm trying to fit everything on a page without scrolling — I'm (mis)using mdbook to make a presentation, essentially. Because of this my code snippets are short, 5-10 lines typically. The overhead of managing an extra file was typically higher than the advantage for me.

And as you wrote in the other issue, that it would make translations "fuzzy" if more than paragraphs changed?

The fuzzyness is on a per-message basis. It's not affected by where you put the code: mdbook-i18n-helpers gives you a preprocessor and if you run it after the built-in links preprocessor, then it sees the code after resolving any {{#include directives. If you run it before, it will see the directive.

[simonsan]

Formatted the code blocks with dprint and I'm happy with that. Going to close this here. :) Thanks again for that awesome recommendation. Made my life a lot easier in different repositories. 👍🏽