diff --git a/crates/service/service-webpage/assets/htwah/definitions.pdf b/crates/service/service-webpage/assets/htwah/definitions.pdf new file mode 100644 index 0000000..c1a9d67 Binary files /dev/null and b/crates/service/service-webpage/assets/htwah/definitions.pdf differ diff --git a/crates/service/service-webpage/assets/htwah/numbering.pdf b/crates/service/service-webpage/assets/htwah/numbering.pdf new file mode 100644 index 0000000..3348067 Binary files /dev/null and b/crates/service/service-webpage/assets/htwah/numbering.pdf differ diff --git a/crates/service/service-webpage/assets/htwah/sols-a.pdf b/crates/service/service-webpage/assets/htwah/sols-a.pdf new file mode 100644 index 0000000..2b47e59 Binary files /dev/null and b/crates/service/service-webpage/assets/htwah/sols-a.pdf differ diff --git a/crates/service/service-webpage/assets/htwah/sols-b.pdf b/crates/service/service-webpage/assets/htwah/sols-b.pdf new file mode 100644 index 0000000..f39a840 Binary files /dev/null and b/crates/service/service-webpage/assets/htwah/sols-b.pdf differ diff --git a/crates/service/service-webpage/assets/htwah/spacing-a.pdf b/crates/service/service-webpage/assets/htwah/spacing-a.pdf new file mode 100644 index 0000000..9c1990b Binary files /dev/null and b/crates/service/service-webpage/assets/htwah/spacing-a.pdf differ diff --git a/crates/service/service-webpage/assets/htwah/spacing-b.pdf b/crates/service/service-webpage/assets/htwah/spacing-b.pdf new file mode 100644 index 0000000..8450871 Binary files /dev/null and b/crates/service/service-webpage/assets/htwah/spacing-b.pdf differ diff --git a/crates/service/service-webpage/src/routes/htwah/typesetting.md b/crates/service/service-webpage/src/pages/htwah-typesetting.md similarity index 77% rename from crates/service/service-webpage/src/routes/htwah/typesetting.md rename to crates/service/service-webpage/src/pages/htwah-typesetting.md index fd5c31f..4cd94ee 100644 --- a/crates/service/service-webpage/src/routes/htwah/typesetting.md +++ b/crates/service/service-webpage/src/pages/htwah-typesetting.md @@ -1,23 +1,21 @@ +++ title = "HtWaH: Typesetting" -template = "page.html" +author = "Mark" -[extra] -show_title = false -back_links = [ - {target = "/htwah", text = "htwah"} -] +# TODO: many slugs, htwah/typesetting +slug = "handouts" +++ ## Table of Contents This page is part of my [how to write a handout](/htwah) series. -- [Part 1: Typesetting](.) {{ color(c="green", t="**<-- you are here**") }} +- [Part 1: Typesetting](.) **{{color(--green, "<-- you are here")}}** - Part 2: Notation - Part 3: Designing lessons - Part 4: Designing puzzles - Part 5: Leading a class +- Part 6: Resources
@@ -34,7 +32,7 @@ Lessons presented on a screen do not take advantage of this; lessons presented o Double-sided handouts break this spacial intuition. The act of turning a page upside-down severs its connection to physical space. Do not entangle your students in the pages of a double-sided worksheet---print only on one side. -{{color(c="grey", t="This is not true of books, which are presented in a fundamentally different way.")}} +{{color(--grey, "This is not true of books, which are presented in a fundamentally different way.")}} Double-sided handouts also clutter the page with the opposite side's nodes. Even when using a pencil, work on the front of a page makes its way to the back. @@ -62,26 +60,29 @@ If you force your students to cram their work into the margin, their understanding will have a similar quality. \ Give them space to work and space to think. -{{color(c="grey", t="This rule only applies to handouts. Lecture notes and textbooks do not need to worry about this, since students should work through them on a separate sheet of paper.")}} +{{color(--grey, "This rule only applies to handouts. Lecture notes and textbooks do not need to worry about this, since students should work through them on a separate sheet of paper")}} Every problem should be followed by a `\vfill`. \ There are exceptions, but they are rare. If your handouts include solutions -{{color(c="grey", t="(they should),")}} +{{color(--grey, "(they should)")}} observe the following rule: each problem's typeset solution should fit in the empty space after the problem. This isn't perfectly accurate estimate of space (your students will likely need more), but it is a very good minimum. -{{color(c="grey", t="If your students will be drawing pictures, make each gap twice as bit as it needs to be.")}} +{{color(--grey, "If your students will be drawing pictures, make each gap twice as bit as it needs to be.")}} In a handout that is typeset well, the layout of each page should not change when solutions are shown. This helps you give students enough room to solve each problem, and keeps page numbers consistent between instructors' and students' handouts: -{{ twopdf(left="/htwah/sols-a.pdf", right="/htwah/sols-b.pdf") }} +
+ + +

@@ -93,7 +94,7 @@ A page should _never_ break between the first mention of a concept and the probl New sections should _always_ start on a new page. -{{color(c="grey", t="Unlike the previous comments on spacing, the above rules apply to all formats. Whether you are writing a textbook, a handout, or lecture notes, do not allow your page breaks to break as student's train of thought.")}} +{{color(--grey, "Unlike the previous comments on spacing, the above rules apply to all formats. Whether you are writing a textbook, a handout, or lecture notes, do not allow your page breaks to break as student's train of thought.")}} These rules are easy to follow if you leave space for work: \ Place your `\pagebreak`s well and let `\vfill` handle the rest. @@ -111,11 +112,14 @@ clear that these are the definitions we will be using in the future. It is also a good idea to mark the first use of a term. \ In the example below, this is done with italicized text. -{{ onepdf(src="/htwah/definitions.pdf") }} + +
+ +
Of course, not all texts need such aggressive grouping. I tend to avoid clear "boxing" in [my lessons](/handouts), opting for subtle grouping by whitespace instead. This is a matter of taste. -{{color(c="grey", t="Regardless of implementation, visual boundaries should match conceptual boundaries. It should be easy to see where each logical element ends.")}} +{{color(grey, "Regardless of implementation, visual boundaries should match conceptual boundaries. It should be easy to see where each logical element ends.")}} Finally, remember that too much separation is just as distracting as too little. Balance is key. @@ -125,7 +129,11 @@ Balance is key. Different elements should be far apart, and related elements should be close together[^4]. This rule is often violated by equations and diagrams. Consider the two pages below: -{{ twopdf(left="/htwah/spacing-a.pdf", right="/htwah/spacing-b.pdf") }} +
+ + +
+ The circuit diagram on the left is clearly a part of the setup at the top of the page. It is not connected to Problem 14. @@ -151,7 +159,7 @@ Numbering should be simple: use a single counter that is set to 1 on the first p Different numbering systems (`i, ii, iii...` for a preface; `A31, A32, A33...` for appendices) have little value and only make navigation more difficult. -{{color(c="grey", t="Roman numbering of frontmatter in large textbooks is acceptable, but anything more complicated is unnecessary.")}} +{{color(--grey, "Roman numbering of frontmatter in large textbooks is acceptable, but anything more complicated is unnecessary")}} ### Versions @@ -159,11 +167,11 @@ The document itself should also be numbered. In most cases, a `\today` on the fr This helps synchronize the handout you _think_ the class has with the handout that the class _really_ has. -Future instructors {{color(c="grey", t="(and future you)")}} will be thankful. +Future instructors {{color(--grey, "(and future you")}} will be thankful. ### Items -Propositions, definitions, and examples should all be numbered with the same counter. Problems should also use this counter, unless they are only listed at the end of each section {{color(c="grey", t="(as they often are in textbooks).")}} +Propositions, definitions, and examples should all be numbered with the same counter. Problems should also use this counter, unless they are only listed at the end of each section {{color(--grey, "(as they often are in textbooks).")}} Do not use different counters for different objects. Theorem 1 should not follow Definition 2. This is the default behavior of LaTeX, and it is a serious mistake. @@ -175,7 +183,9 @@ With a single counter, this is not an issue. Readers are aware of their absolute [Open Logic](https://openlogicproject.org/) again provides an example of quality typesetting. Notice how the numbering of Propositions, Definitions, and Examples on the page below is consecutive: -{{ onepdf(src="/htwah/numbering.pdf") }} +
+ +
In long textbooks, prefixing numbers with the chapter index (e.g, the `2` in `2.32` above) is wise. In any other case, a single counter should be enough. @@ -197,7 +207,12 @@ who made it, when, and why. If you're writing a document that is available in multiple variants (for example, a handout with solutions or an exam with multiple versions), the variant should be easily visible in the title. Note the box under the title in the handout on the left. -{{ twopdf(left="/htwah/sols-a.pdf", right="/htwah/sols-b.pdf") }} + +
+ + +
+ This lets us detect errors quickly: we only need to look at the first page of a lesson to know if we printed the wrong variant, handed the students solutions, or graded an exam using the wrong answer key. diff --git a/crates/service/service-webpage/src/pages/mod.rs b/crates/service/service-webpage/src/pages/mod.rs index d17d5a4..e4b8f56 100644 --- a/crates/service/service-webpage/src/pages/mod.rs +++ b/crates/service/service-webpage/src/pages/mod.rs @@ -26,3 +26,10 @@ pub fn betalupi() -> Page { Some(Image_Icon::URL.to_owned()), ) } + +pub fn htwah_typesetting() -> Page { + page_from_markdown( + include_str!("htwah-typesetting.md"), + Some(Image_Icon::URL.to_owned()), + ) +} diff --git a/crates/service/service-webpage/src/routes/assets.rs b/crates/service/service-webpage/src/routes/assets.rs index d54a6e3..2ea9480 100644 --- a/crates/service/service-webpage/src/routes/assets.rs +++ b/crates/service/service-webpage/src/routes/assets.rs @@ -2,6 +2,7 @@ use assetserver::Asset; use axum::http::header; use macro_assets::assets; use macro_sass::sass; +use toolbox::mime::MimeType; assets! { prefix: "/assets" @@ -150,4 +151,56 @@ assets! { (header::CONTENT_TYPE, "application/font-ttf") ] } + + // + // MARK: htwah + // + + Htwah_Definitions { + source: include_bytes!("../../assets/htwah/definitions.pdf"), + target: "/htwah/definitions.pdf", + headers: [ + (header::CONTENT_TYPE, MimeType::Pdf.to_string()) + ] + } + + Htwah_Numbering { + source: include_bytes!("../../assets/htwah/numbering.pdf"), + target: "/htwah/numbering.pdf", + headers: [ + (header::CONTENT_TYPE, MimeType::Pdf.to_string()) + ] + } + + Htwah_SolsA { + source: include_bytes!("../../assets/htwah/sols-a.pdf"), + target: "/htwah/sols-a.pdf", + headers: [ + (header::CONTENT_TYPE, MimeType::Pdf.to_string()) + ] + } + + Htwah_SolsB { + source: include_bytes!("../../assets/htwah/sols-b.pdf"), + target: "/htwah/sols-b.pdf", + headers: [ + (header::CONTENT_TYPE, MimeType::Pdf.to_string()) + ] + } + + Htwah_SpacingA { + source: include_bytes!("../../assets/htwah/spacing-a.pdf"), + target: "/htwah/spacing-a.pdf", + headers: [ + (header::CONTENT_TYPE, MimeType::Pdf.to_string()) + ] + } + + Htwah_SpacingB { + source: include_bytes!("../../assets/htwah/spacing-b.pdf"), + target: "/htwah/spacing-b.pdf", + headers: [ + (header::CONTENT_TYPE, MimeType::Pdf.to_string()) + ] + } } diff --git a/crates/service/service-webpage/src/routes/mod.rs b/crates/service/service-webpage/src/routes/mod.rs index feeb0ed..12c235c 100644 --- a/crates/service/service-webpage/src/routes/mod.rs +++ b/crates/service/service-webpage/src/routes/mod.rs @@ -25,7 +25,8 @@ fn build_server() -> Arc { .add_page("/", pages::index()) .add_page("/links", pages::links()) .add_page("/whats-a-betalupi", pages::betalupi()) - .add_page("/handouts", pages::handouts()); + .add_page("/handouts", pages::handouts()) + .add_page("/htwah", pages::htwah_typesetting()); server }