HTWAH draft

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
 
 <hr style="margin-top: 5rem; margin-bottom: 5rem"/>
 
@@ -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") }}
+<div style="display: flex; flex-direction: row; gap: 1rem; height: 50rem">
+	<embed type="application/pdf" src="/assets/htwah/sols-a.pdf" width="100%" height="100%" />
+	<embed type="application/pdf" src="/assets/htwah/sols-b.pdf" width="100%" height="100%" />
+</div>
 
 <br>
 
@@ -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") }}
+
+<div style="display: flex; flex-direction: row; gap: 1rem; height: 50rem">
+	<embed type="application/pdf" src="/assets/htwah/definitions.pdf" width="100%" height="100%" />
+</div>
 
 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") }}
+<div style="display: flex; flex-direction: row; gap: 1rem; height: 50rem">
+	<embed type="application/pdf" src="/assets/htwah/spacing-a.pdf" width="100%" height="100%" />
+	<embed type="application/pdf" src="/assets/htwah/spacing-b.pdf" width="100%" height="100%" />
+</div>
+
 
 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") }}
+<div style="display: flex; flex-direction: row; gap: 1rem; height: 50rem">
+	<embed type="application/pdf" src="/assets/htwah/numbering.pdf" width="100%" height="100%" />
+</div>
 
 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") }}
+
+<div style="display: flex; flex-direction: row; gap: 1rem; height: 50rem">
+	<embed type="application/pdf" src="/assets/htwah/sols-a.pdf" width="100%" height="100%" />
+	<embed type="application/pdf" src="/assets/htwah/sols-b.pdf" width="100%" height="100%" />
+</div>
+
 
 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.
 

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()),
+	)
+}

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())
+		]
+	}
 }

crates/service/service-webpage/src/routes/mod.rs

@@ -25,7 +25,8 @@ fn build_server() -> Arc<PageServer> {
 		.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
 }