Merge branch 'main' into 225-ebook-situation

Dockerfile

@@ -1,4 +1,4 @@
-FROM registry.gitlab.com/islandoftex/images/texlive
+FROM debian:trixie
 
 LABEL "maintainer"="Hendrik Kleinwächter <hendrik.kleinwaechter@gmail.com>"
 LABEL "repository"="https://github.com/hendricius/the-sourdough-framework"
@@ -6,7 +6,7 @@ LABEL "homepage"="https://github.com/hendricius/the-sourdough-framework"
 LABEL org.opencontainers.image.source="https://github.com/hendricius/the-sourdough-framework"
 
 # Print release information if needed
-# RUN cat /etc/*release*
+RUN cat /etc/*release*
 
 # Install base depdendencies
 RUN apt-get update && \
@@ -21,7 +21,43 @@ RUN apt-get update && \
     ruby3.1 \
     ruby-dev \
     imagemagick \
-    build-essential
+    rsync \
+    wget \
+    perl \
+    xzdec \
+    # dvisvgm dependencies
+    build-essential \
+    fonts-texgyre \
+    fontconfig \
+    libfontconfig1 \
+    libkpathsea-dev \
+    libptexenc-dev \
+    libsynctex-dev \
+    libx11-dev \
+    libxmu-dev \
+    libxaw7-dev \
+    libxt-dev \
+    libxft-dev \
+    libwoff-dev
+
+# Install TeX
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends \
+    texlive-full \
+    texlive-luatex
+
+# Compile latest dvisvgm
+RUN wget https://github.com/mgieseki/dvisvgm/releases/download/3.1.2/dvisvgm-3.1.2.tar.gz && \
+    mv dvisvgm-3.1.2.tar.gz dvisvgm.tar.gz && \
+    tar -xzf dvisvgm.tar.gz && \
+    cd dvisvgm-* && \
+    ./configure && \
+    make && \
+    make install
+
+# Make sure everything is UTF-8
+RUN echo "export LC_ALL=en_US.UTF-8" >> /root/.bashrc && \
+    echo "export LANG=en_US.UTF-8" >> /root/.bashrc
 
 WORKDIR /root
 

book/baking/baking.tex

@@ -1,34 +1,28 @@
+\chapter{Baking}%
+\label{chapter:baking}
 \begin{quoting}
-Baking refers to the part of the process where you are loading
+Baking refers to the part of the process where you are loading your dough into
-your dough into the oven. This is typically done after your
+the oven\footnote{While some breads like flatbreads could also be baked on the
-dough has gone through the bulk fermentation and proofing stage.
+stove. This chapter focuses on the home oven.}.  Baking is typically done after
+your dough has gone through the bulk fermentation and proofing stage.  This
+chapter will review what happens to your dough during baking, as well as
+several techniques used to improve the final result.
 \end{quoting}
 
-\begin{flowchart}[!htb]
+\section{The process of baking}
-\begin{center}
+Once temperature starts to rise, the dough will go through several stages as
-  \input{figures/fig-baking-process.tex}
+summarized in Table~\ref{tab:baking-stages}.  As the dough heats up, the water
-  \caption[Different steaming methods]{A schematic visualization of the baking
+and acids in your dough start to evaporate. When baking a gluten based dough,
-      process using different sources of steam in a home oven.}%
+the bubbles in your dough start to expand.  The dough starts to vertically
-  \label{fig:baking-process}
+rise, this is called oven spring.  Your bread starts to build a crust of
-\end{center}
+gel-like consistency, the crust is still extensible and can be stretched.
-\end{flowchart}
-
-Some other breads like flatbreads
-could also be baked on the stove. This chapter focuses on the
-home oven.
-
-As the dough heats up, the water and acids
-in your dough start to evaporate. When baking
-a gluten based dough, the bubbles in your dough start to expand.
-Your dough starts to vertically rise. This is called oven spring.
-Your bread starts to build a crust of gel-like consistency. The crust is still
-extensible and can be stretched.
 
 \begin{table}[htp!]
     \begin{center}
         \input{tables/table-baking-process-stages.tex}
         \caption[Stages of dough during baking]{The different stages that
-            your dough undergoes during the baking process.}
+            your dough undergoes during the baking process.}%
+        \label{tab:baking-stages}
     \end{center}
 \end{table}
 
@@ -41,28 +35,32 @@ More research should be done here to validate or invalidate this
 claim.
 
 At  \qty{75}{\degreeCelsius} (\qty{167}{\degF}) the surface of your dough turns into a gel. It
-holds together nicely and is still extensible. This gel is essential
+holds together nicely but is still extensible. This gel is essential
-for oven spring as it retains the gas of your dough very well.
+for oven spring as it retains the gas inside your dough.
 
 At around  \qty{100}{\degreeCelsius} (\qty{212}{\degF}) the water starts to evaporate out of your
 dough. If this weren't the case, your dough would taste soggy and
 doughy. The higher hydration your dough has, the more water your bread
-still contains after the bake. The crumb is going to taste a bit
+still contains after the bake, changing its consistency.  As a result the
-more moist. The consistency will be different.
+crumb is going to taste a bit more moist.
 
-Another often undervalued step is the evaporation of acids. At
+Another often undervalued step is the evaporation of acids.
-\qty{118}{\degreeCelsius} (\qty{244}{\degF}) the acetic acid in your dough starts to evaporate.
+At~\qty{118}{\degreeCelsius} (\qty{244}{\degF}) the acetic acid in your dough
-Shortly after at  \qty{122}{\degreeCelsius} (\qty{252}{\degF}) the lactic acid begins evaporating.
+starts to evaporate.
-This is crucial to understand and opens a door to many interesting
+Shortly after at~\qty{122}{\degreeCelsius} (\qty{252}{\degF}) the lactic acid begins evaporating.
+This is crucial to understand and it opens the door to many interesting
 ways to influence your final bread's taste. As more and more water
 begins to evaporate the acids in your dough become more concentrated.
-There is less water but in relation you have more acids. A shorter
+There is less water but in relation you have more acids, therefore a shorter
-bake will therefore lead to a more tangy dough. The longer you bake the bread,
+bake will lead to a more tangy dough. The longer you bake the bread,
 the more of the water evaporates, but also ultimately the acids will follow.
-They will be more concentrated. In absolute units, though, they
+The longer you bake, the less sour your bread is going to be. By controlling
-will become less and less. The longer you bake, the less sour
+baking time you can influence which sourness level you would like to achieve.
-your bread is going to be. By baking you can
+
-influence which sourness level you would like to achieve.
+It would be a very interesting experiment to bake a bread at different exact
+temperatures. How would a bread taste with only evaporated water but
+full acidity? What if you were to just completely get rid of the acetic
+acid? How would the taste change?
 
 \begin{figure}[!htb]
   \includegraphics[width=\textwidth]{baking-experiment-temperatures.png}
@@ -74,18 +72,14 @@ influence which sourness level you would like to achieve.
       the surface temperature increases.}
 \end{figure}
 
-It would be a very interesting experiment to bake a bread at different exact
+As the temperature increases further the crust thickens. The Maillard reaction
-temperatures. How would a bread taste with only evaporated water but
+kicks in, deforming proteins and starches. The outside of your dough starts to
-full acidity? What if you were to just completely get rid of the acetic
+become browner and crisper, this process begins at
-acid? How would the taste change?
+around~\qty{140}{\degreeCelsius} (\qty{284}{\degF})
 
-As the temperature increases
+Once the temperature increases even more to around~\qty{170}{\degreeCelsius}
-the crust thickens. The Maillard reaction kicks in, further deforming
+(\qty{338}{\degF}),
-proteins and starches. The outside of your dough starts to become
+the caramelization process begins, the remaining sugars and the microbes which
-browner and crisper. This process begins at around  \qty{140}{\degreeCelsius} (\qty{284}{\degF})
-
-Once the temperature increases even more to around  \qty{170}{\degreeCelsius} (\qty{338}{\degF}),
-the caramelization process begins. The remaining sugars the microbes
 did not convert yet start to brown and darken. You can keep baking
 for as long as you like to achieve the crust color that you
 like\footnote{This really depends a lot on your personal preference.
@@ -95,66 +89,53 @@ heat your bread in the oven one more time to continue building a
 darker crust.}.
 
 The best method to know that your dough is done is to take
-the temperature of your dough. You can use a barbecue thermometer
+the temperature of your dough, you can use a barbecue thermometer
-to measure it. Once the core temperature is at around  \qty{92}{\degreeCelsius} (\qty{197}{\degF}),
+to measure it. Once the core temperature is at around~\qty{92}{\degreeCelsius}
+(\qty{197}{\degF}),
 you can stop the baking process. This is typically not done though
 as the crust hasn't been built yet\footnote{The thermometer is
 especially important when using a large loaf pan. It is sometimes
 very hard to judge from the outside if the dough is done. I~failed
 many times and ended up having a semi baked dough.}.
 
-Once your dough has finished baking, it is ready to eat. Your
+Once your dough has finished baking, it is ready to eat: your
 dough has turned into a bread. At this
 point, your bread is sterile as the temperature was too hot for
 for the microorganisms to survive\footnote{I~wonder though
 if a starter culture could be grown again from a slice of bread.
 Under heat stress the microorganisms begin sporulating. Maybe
 some of the spores survive the baking process and could be reactivated
-later? If this worked, you could use any store bought sourdough
+later? If this works, you could use any store bought sourdough
 bread as a source for a new starter.}.
 
 \section{The role of steam}
-
-\begin{figure}[!htb]
-  \includegraphics[width=\textwidth]{oven-example}
-  \caption[Home oven baking example to maximize steam]{My default home oven setup. The tray of rocks
-  and tray on top of the rolls greatly improve the steaming capabilities. This way the bread can
-  rise more during the initial stage of the baking process.}
-\end{figure}
-
 Steam is essential when baking as it helps to counter premature
 crust building. During the first stage of the bake, the dough
-increases in size. The water in your dough evaporates and pushes
+increases in size as the water in your dough evaporates and pushes
 the whole dough upwards.
 
-\begin{figure}[!htb]
-  \includegraphics[width=\textwidth]{baking-process-steam.jpg}
-  \caption[Steam building with inverted tray]{How steam builds in your oven
-      using the later described inverted tray method.}%
-      \label{flc:inverted-tray}
-\end{figure}
-
 Normally, under high heat a crust would form. Just like
 if you were to bake vegetables in your home oven, at some point
 they become darker and crisper. This is the same thing that
-happens with your dough. You want to delay this process
+happens with your dough, and you want to delay this process
 as long as possible until your dough no longer expands.
 Expansion stops when most of the microbes have died and
 the evaporating water no longer stays inside the alveoli.
+
 The stronger the gluten network, the more gas can be retained
 during the baking process. This gluten network at some point
 loses its ability to contain gas as the temperature heats
 up. The dough stops increasing in size. The steam plays
 an important role as it condenses and evaporates on top
 of your dough. The surface temperature is rapidly increasing
-to around  \qty{75}{\degreeCelsius} (\qty{160}{\degF}). At this temperature the gel starts
+to around~\qty{75}{\degreeCelsius} (\qty{160}{\degF}). At this temperature the
-to build. This gel is still extensible and allows expansion.
+gel starts to build, and is still extensible and allows expansion.
 Without the steam, the dough would never enter the gel stage,
 but instead directly go to the Maillard reaction zone. You
 want your dough to stay in this gel stage as long as possible
 to achieve maximum expansion\footnote{You can remove your
 dough from the oven after 5~minutes to see the gel. You will notice
-that it holds the dough's structure. It has a very interesting consistency.}.
+that it holds the dough's structure and it has a very interesting consistency.}.
 
 \begin{figure}[!htb]
   \includegraphics[width=\textwidth]{baking-process-stage-2.jpg}
@@ -165,10 +146,9 @@ that it holds the dough's structure. It has a very interesting consistency.}.
 When not steaming enough, you will notice that the scoring
 incisions do not properly open up during the bake. They stay
 closed as the dough is unable to push through the crust.
-
+Another common sign, as you can see in Figure~\ref{fig:too-little-steam} is
-Another common sign is that you have larger pockets
+that you have larger pockets of air towards the crust of your dough. As the
-of air towards the crust of your dough. As the dough increases
+dough increases vertically, expansion is halted by the crust. The pockets
-vertically, expansion is halted by the crust. The pockets
 of air converge into larger pockets as the pressure increases.
 This can also happen when you are baking at too high a temperature.
 
@@ -185,10 +165,35 @@ way.
   \caption[Bread baked too hot]{A submission by Karomizu showing a bread that
       has been baked at too high a temperature or with too little steam. Note
       the large pockets of air towards the crust. They are a typical
-      indicator.}
+      indicator.}%
+      \label{fig:too-little-steam}
 \end{figure}
 
-\section{Dutch ovens}
+\section{Building up steam}
+\begin{flowchart}[!htb]
+\begin{center}
+  \input{figures/fig-baking-process.tex}
+  \caption[Different steaming methods]{A schematic visualization of the baking
+      process using different sources of steam in a home oven.}%
+  \label{fig:baking-process}
+\end{center}
+\end{flowchart}
+
+\begin{figure}[!htb]
+  \includegraphics[width=\textwidth]{oven-example}
+  \caption[Home oven baking example to maximize steam]{My default home oven setup. The tray of rocks
+  and tray on top of the rolls greatly improve the steaming capabilities. This way the bread can
+  rise more during the initial stage of the baking process.}
+\end{figure}
+
+\begin{figure}[!htb]
+  \includegraphics[width=\textwidth]{baking-process-steam.jpg}
+  \caption[Steam building with inverted tray]{How steam builds in your oven
+      using the later described inverted tray method.}%
+      \label{flc:inverted-tray}
+\end{figure}
+
+\subsection{Dutch ovens}
 
 \begin{figure}[!htb]
   \includegraphics[width=\textwidth]{dutch-oven-example}
@@ -264,7 +269,7 @@ the simple flatbread recipe which is baked in a pan. Please
 refer to Section~\ref{section:flat-bread-recipe} for more details.
 
 
-\section{Inverted tray method}
+\subsection{Inverted tray method}
 
 The inverted tray method simulates a Dutch oven.
 By placing another tray on top of your dough, the steam

book/figures/fig-baking-process.tex

@@ -1,23 +1,22 @@
-\begin{tikzpicture}[node distance = 3cm, auto]
+\begin{tikzpicture}[node distance = 4cm, auto]
   \node [start] (heat_oven) {Heat oven to  \qty{230}{\degreeCelsius} (\qty{446}{\degF}) for 30~minutes};
-  \node [block, right of=heat_oven, node distance=3cm] (score_dough) {Score your dough};
+  \node [block, right of=heat_oven] (score_dough) {Score your dough};
   \node [decision, right of=score_dough, node distance=4cm] (decide_steam) {Choose your steaming method};
-  \node [block, below of=heat_oven, node distance=4cm] (inverted_tray_method) {Inverted tray method};
+  \node [block, below of=decide_steam, node distance=3.5cm] (dutch_oven) {Dutch oven};
-  \node [block, right of=inverted_tray_method, node distance=3cm] (dutch_oven) {Dutch oven};
+  \node [block, left of=dutch_oven] (inverted_tray_method) {Inverted tray method};
-  \node [block, right of=dutch_oven, node distance=3cm] (steam_injection) {Steam injection oven};
+  \node [block, right of=dutch_oven] (steam_injection) {Steam injection oven};
-  \node [block, below of=inverted_tray_method, node distance=3cm] (bake_30) {Bake dough for 30~minutes with steam};
+  \node [block, below of=dutch_oven, node distance=3cm] (bake_30) {Bake dough for 30~minutes with steam};
-  \node [block, right of=bake_30, node distance=3cm] (remove_steam) {Remove source of steam};
+  \node [block, below of=bake_30, node distance=3cm] (remove_steam) {Remove source of steam};
-  \node [block, right of=remove_steam, node distance=3cm] (build_crust) {Build the crust};
+  \node [success, right of=remove_steam] (finish_baking) {Stop baking 10--30~minutes later depending on crust preference};
-  \node [success, right of=build_crust, node distance=3cm] (finish_baking) {Stop baking 10--30~minutes later depending on crust preference};
   \path [line] (heat_oven) -- (score_dough);
   \path [line] (score_dough) -- (decide_steam);
-  \path [line] (decide_steam) -- (inverted_tray_method);
+  \path [line] (decide_steam) -- (inverted_tray_method.north east);
   \path [line] (decide_steam) -- (dutch_oven);
-  \path [line] (decide_steam) -- (steam_injection);
+  \path [line] (decide_steam) -- (steam_injection.north west);
-  \path [line] (steam_injection) -- (bake_30);
+  \path [line] (steam_injection.south west) -- (bake_30.north east);
-  \path [line] (inverted_tray_method) -- (bake_30);
+  \path [line] (inverted_tray_method.south east) -- (bake_30.north west);
   \path [line] (dutch_oven) -- (bake_30);
   \path [line] (bake_30) -- (remove_steam);
-  \path [line] (remove_steam) -- (build_crust);
+  \path [line] (remove_steam) -- (finish_baking);
-  \path [line] (build_crust) -- (finish_baking);
+  \draw[BC, decoration=mirror] (remove_steam.south west) ++(0, -0.3) -- node[below=1em]{Building crust}(finish_baking.south east);
 \end{tikzpicture}

book/figures/flowcharts_tikz.tex

@@ -1,6 +1,6 @@
 \tikzstyle{every picture}+=[font=\footnotesize\sffamily]
 \usetikzlibrary{calc, shapes, arrows, decorations.pathreplacing, calligraphy,
-                calligraphy}
+                positioning}
 \tikzstyle{decision} = [diamond, draw=codeblack, fill=codeblack, text=white,
     text width=4.5em, text badly centered, node distance=3cm, inner sep=0pt,
     line width=2mm]

book/makefile

@@ -1,7 +1,7 @@
 # Macros for commands
 LATEX := latexmk -cd -pdflua -lualatex="lualatex -interaction=nonstopmode" -synctex=1 -use-make
 EBOOK := tex4ebook --lua -d epub -f epub -c tex4ebook.cfg
-WEBSITE := make4ht --lua -c website.cfg -a debug -uf html5+tidy+common_domfilters+dvisvgm_hashes
+WEBSITE := make4ht --lua -c website.cfg -a debug -uf html5+tidy+common_domfilters
 CLEAN := latexmk -cd -lualatex -c -use-make
 CHECK_1 := lacheck
 CHECK_2 := chktex
@@ -302,6 +302,8 @@ show_tools_version:  # Show version of tools used on the build machine
 	@echo ""
 	- tidy -version
 	@echo ""
+	- dvisvgm --version
+	@echo ""
 	- lacheck --version
 	@echo ""
 	- chktex --version

website/assets/script.js

@@ -8,14 +8,4 @@ document.addEventListener('DOMContentLoaded', function() {
       });
     }
   });
-
-  // Add permalinks to headers
-  var heads = document.querySelectorAll('.sectionHead');
-  heads.forEach(function (head) {
-    let permalink = document.createElement("a");
-    permalink.href = '#' + head.id;
-    permalink.classList.add('permalink');
-    permalink.append('🔗');
-    head.append(permalink);
-  });
 });

website/modify_build.rb

@@ -27,7 +27,7 @@ class ModifyBuild
       html_file_name = fn.split("/")[-1]
       content += "#{HOST}/#{html_file_name}\n"
     end
-    File.open("#{build_dir}/sitemap.txt", 'w') { |file| file.write(content) }
+    File.open("#{build_dir}/sitemap.txt", 'w:UTF-8') { |file| file.write(content) }
   end
 
   def build_latex_html
@@ -41,7 +41,7 @@ class ModifyBuild
   end
 
   def modify_file(filename)
-    orig_text = File.read(filename)
+    orig_text = File.read(filename, encoding: "UTF-8")
     text = fix_double_slashes(orig_text)
     text = fix_navigation_bar(text)
     text = fix_titles(text)
@@ -58,9 +58,10 @@ class ModifyBuild
     text = add_text_to_coverpage(text, extract_file_from_path(filename))
     text = fix_js_dependency_link(text)
     text = fix_list_of_tables_figures_duplicates(text)
+    text = add_anchors_to_headers(text)
     text = fix_menus_list_figures_tables(text) if is_list_figures_tables?(filename)
     text = fix_list_of_figures_tables_display(text) if is_list_figures_tables?(filename)
-    File.open(filename, "w") {|file| file.puts text }
+    File.open(filename, "w:UTF-8") {|file| file.puts text }
   end
 
   def is_cover_page?(filename)
@@ -370,15 +371,17 @@ class ModifyBuild
 
   def mark_menu_as_selected_if_on_page(text, filename)
     doc = build_doc(text)
+    return doc.to_html
+
     selected = doc.css(".menu-items .chapterToc > a").find do |el|
       el["href"] == ""
     end
 
     # Special case for index page
-    if ["index.html", "book.html"].include?(filename)
+    #if ["index.html", "book.html"].include?(filename)
-      doc.css(".menu-items .chapterToc.home-link")[0].add_class("selected")
+    #  doc.css(".menu-items .chapterToc.home-link")[0].add_class("selected")
-      return doc.to_html
+    #  return doc.to_html
-    end
+    #end
 
     # Special case for the flowcharts page which is added by us to the menu.
     # This needs to be done for future manually added pages too
@@ -561,6 +564,20 @@ class ModifyBuild
   def build_doc(text)
     Nokogiri::HTML(text)
   end
+
+  def add_anchors_to_headers(text)
+    doc = build_doc(text)
+    content = doc.css(".sectionHead, .subsectionHead")
+    content.each do |el|
+      anchor = el.attribute("id").value
+      # No anchor for whatever reason
+      next unless anchor
+
+      copy_link = %Q{<a href="##{anchor}" class="permalink">🔗</a>}
+      el.inner_html = "#{el.inner_html}#{copy_link}"
+    end
+    doc.to_html
+  end
 end
 
 ModifyBuild.build