Add The Little Book of Rust Macros (WIP)

[killercup]

From DanielKeep/tlborm@28d616ab934321811fe699d9729814f039365a39

[killercup]

So, I had a go with the current source code as-is: tlborm-2015-10-14.a4.pdf

As expected, there are some formatting issues with the ASCII diagrams and code blocks. Additionally, there are some raw HTML segments for math and tables. Fixing this will take time, but should be straightforward (using actual images, e.g. using graphviz; annotating more block with rust; using LaTeX math; using Markdown tables).

cc @danielkeep, @jaxx (#24)

[jaxx]

Great, thanks!

[DanielKeep]

Good luck with the hygiene code blocks! :P

[DanielKeep]

Also:

• Those aren't ASCII diagrams: they're Unicode diagrams. And they took more time and effort than you might believe. This looks more like LaTeX can't handle how awesome they are (or it has entirely deviant ideas about what ─ should look like).
• The parsing table is evil because I had to adjust a bunch of styling to get it to work. The major differences are that I shrink the code down (so it'll all fit), and then futz with the positioning of the marker line so it fits more snugly with the code.
• As I said, good luck with the hygiene code blocks.
• The math does use LaTeX... originally before I fed it to the KaTeX website and hacked the raw output into the source. Again, I blame Markdown for being rubbish.
• Lots of code blocks aren't annotated with rust because they're not valid, testable Rust code. Granted, rustbook doesn't currently run tests, but I doubt that's going to be the case long-term. Then again, I see a few which (I assume) aren't annotated with rust because I just got so used to typing ignore :P

[killercup]

Wow, thanks for the long answer, @DanielKeep!

Those aren't ASCII diagrams: they're Unicode diagrams. And they took more time and effort than you might believe. This looks more like LaTeX can't handle how awesome they are (or it has entirely deviant ideas about what ─ should look like).

I can only imagine how much time that took! I'm using DejaVu Sans Mono for code blocks, which apparently doesn't work well with these symbols. Also, I'm not sure if they can cut off at the 'line' end. One solution might be to take the code, put it in a PDF and embed that as a figure (this would of course not work for the epub version, it'll need to be converted to a PNG or something). This would also keep the style (except the dark background :stuck_out_tongue_winking_eye: ). Also, it's pretty easy as you can just use your browser's print dialog (and something link OS X's Preview.app to cut the PDF).

The parsing table is evil because I had to adjust a bunch of styling to get it to work. The major differences are that I shrink the code down (so it'll all fit), and then futz with the positioning of the marker line so it fits more snugly with the code.

Oh I can see that… The layout should be possible using pandoc's Markdown tables, but that code marker is more tricky… Another PDF?

As I said, good luck with the hygiene code blocks.

Before saying "PDF" again… Maybe I'll just remove the background color note and have people figuring out the changes themselves. (A teacher of mine once told that people reading paper-based books are more educated than those only reading stuff on the Internet, so I guess the readers are up the challenge! :wink:)

The math does use LaTeX... originally before I fed it to the KaTeX website and hacked the raw output into the source. Again, I blame Markdown for being rubbish.

Putting the original math in a HTML comment (and doing some wrapping) could be enough to get this to work.

<!-- MATH START: $F​_n = 0, 1, …, F_​{n−1} ​+ F_​n - 2​​$ -->
<span class="katex-magic">…</span>
<!-- MATH END -->

Lots of code blocks aren't annotated with rust because they're not valid, testable Rust code. Granted, rustbook doesn't currently run tests, but I doubt that's going to be the case long-term. Then again, I see a few which (I assume) aren't annotated with rust because I just got so used to typing ignore :P

I had a good regex for adding rust[,ignore] to TRPL…

[DanielKeep]

I actually looked at turning the diagrams into some kind of image that would be portable across outputs... but couldn't get it to work. Specifically, I was looking at inline SVG (which would allow me to style the images to match the CSS). Sadly, Firefox just will not render the image, and no other solution allows me to have "style independent" diagrams, so... yeah, sticking with text in my sources for now.

Aside from turning the diagrams into glyphs in a custom web font, I'm out of ideas.

Maybe I'll just remove the background color note…

The whole reason for doing that is that syntax contexts are otherwise invisible. I suspect, again, that a diagram of some sort is probably the only sane approach.

Putting the original math in a HTML comment (and doing some wrapping) could be enough to get this to work.

Not a bad idea; that shouldn't interfere with the current output and is vaguely amenable to tooling. :P

[DanielKeep]

Put math markers around the one and only equation: DanielKeep/tlborm@94c7d40b

[killercup]

Specifically, I was looking at inline SVG (which would allow me to style the images to match the CSS). Sadly, Firefox just will not render the image, and no other solution allows me to have "style independent" diagrams

Oh, that's odd. I've made a few websites where inline SVG was used with site-wide CSS to e.g. change the color/outline of an icon to match the context.

I'm assuming you want to have diagrams that match the color scheme? How about cheating with filter: invert(100%); (docs)?

The whole reason for doing that is that syntax contexts are otherwise invisible.

Sorry, my "remove the background color note" should have been obviously followed by an "and replace it with a sentence explaining what was previously highlighted". (Actually, I'd write it in a way to complement the highlighting.)

[killercup]

Diagram as PDF

(Assumes OS X.) Inspect the site in Chrome's dev tools, overwrite CSS to use black text on white for code. Select the diagram text in Chrome, press CMD+P (print), choose "selection only", save as PDF. Open PDF in Preview.app, select "Rectangular selection" (or whatever this is called in English) in "Tools" menu. Select diagram area, press CMD+K (crop), save PDF. This apparently does not remove the invisible parts of the PDF, but it shouldn't matter.

Example: Source Analysis.pdf

[h5rdly]

Any luck with the Little Macro book? Would love to have a PDF!