From ce17e00f96601fd3aa8c4c7f463324f2cfbf2bcc Mon Sep 17 00:00:00 2001
From: Mirek Kratochvil <miroslav.kratochvil@uni.lu>
Date: Tue, 20 Jul 2021 11:31:37 +0200
Subject: [PATCH] add explanatory comments to the table formatting style

If you guys believe the rant wasn't necessary, you need to re-read TeX Book
chapter 1.
---
 ch2.tex    | 12 ++++++++----
 macros.tex | 22 ++++++++++++++++++++--
 2 files changed, 28 insertions(+), 6 deletions(-)

diff --git a/ch2.tex b/ch2.tex
index dd03b06..3e0abb8 100644
--- a/ch2.tex
+++ b/ch2.tex
@@ -24,8 +24,10 @@ Use induction on sets of cars $C$. The statement holds trivially for $|C|\leq1$.
 \end{proof}
 
 \begin{table}
-\floatbox{table}[\FBwidth]
-{\centering\footnotesize\sf
+% uncomment the following line if you use the fitted top captions for tables
+% (see the \floatsetup[table] comments in `macros.tex`.
+%\floatbox{table}[\FBwidth]{
+\centering\footnotesize\sf
 \begin{tabular}{llrl}
 \toprule
 Column A & Column 2 & Numbers & More \\
@@ -40,8 +42,10 @@ Asd qsd 1sd & \textcolor{green!80!black}{GOOD} & 234234299 & -- \\
 Asd & NUMBER & \textbf{123123} & -- \\
 Asd qsd 1sd & DIFFERENT & 234234234 & (no data) \\
 \bottomrule
-\end{tabular}}
-{\caption{An example table. Table caption should clearly explain how to interpret the data in the table. Use some visual guide, such as boldface or color coding, to highlight the most important results (e.g., comparison winners).}}
+\end{tabular}
+%}{  % uncomment if you use the \floatbox (as above), erase otherwise
+\caption{An example table.  Table caption should clearly explain how to interpret the data in the table. Use some visual guide, such as boldface or color coding, to highlight the most important results (e.g., comparison winners).}
+%}  % uncomment if you use the \floatbox
 \label{tab:z}
 \end{table}
 
diff --git a/macros.tex b/macros.tex
index fb75656..8e28e4c 100644
--- a/macros.tex
+++ b/macros.tex
@@ -55,11 +55,29 @@
 \captionsetup{style=thesis}
 \captionsetup[algorithm]{style=thesis,singlelinecheck=off}
 \captionsetup[listing]{style=thesis,singlelinecheck=off}
-\floatsetup[table]{capposition=top,framefit=yes}
+
+% Uncomment for table captions on top. This is sometimes recommended by the
+% style guide, and even required for some publication types.
+%\floatsetup[table]{capposition=top}
+%
+% (Opinionated rant:) Captions on top are not "compatible" with the general
+% guideline that the tables should be formatted to be quickly visually
+% comprehensible and *beautiful* in general (like figures), and that the table
+% "head" row (with column names) should alone communicate most of the content
+% and interpretation of the table. If you just need to show a long boring list
+% of numbers (because you have to), either put some effort into showing the
+% data in an attractive figure-table, or move the data to an attachment and
+% refer to it, so that the boredom does not impact the main text flow.
+%
+% You can make the top-captions look much less ugly by aligning the widths of
+% the caption and the table, with setting `framefit=yes`, as shown below.  This
+% additionally requires some extra markup in your {table} environments; see the
+% comments in the example table in `ch2.tex` for details.
+%\floatsetup[table]{capposition=top,framefit=yes}
 
 \ifEN\floatname{listing}{Listing}
 \else\floatname{listing}{Výpis kódu}\fi
-\lstset{%
+\lstset{ % use this to define styling for any other language
   language=C++,
   tabsize=2,
   showstringspaces=false,