resolves #132 load a base theme with defaults for required keys

- load base theme before loading custom theme
- read base theme from flat layout, do not postprocess
- don't read base theme if using base theme
- don't use base theme before loading default theme
- remove unnecessary keys in default theme, reorg
- update information about base theme in theming guide
- fix image_align key in theming guide
- remove most defensive fallbacks when using theme keys
- minor code cleanups

2 files changed, 159 insertions, 77 deletions

diff --git a/data/themes/base-theme.yml b/data/themes/base-theme.yml
new file mode 100644
index 00000000..0427c400
--- /dev/null
+++ b/data/themes/base-theme.yml
@@ -0,0 +1,87 @@
+# NOTE file is read "as is"; variables are not parsed; key layout must be flat
+# FIXME internal use of vertical_rhythm & horizontal_rhythm needs to be deprecated
+vertical_rhythm: 12
+horizontal_rhythm: 12
+page_background_color: 'FFFFFF'
+page_layout: portrait
+# 36 is equivalent to 0.5in
+page_margin: 36
+page_size: LETTER
+base_align: left
+#base_font_color: '333333'
+base_font_color: '000000'
+#base_font_family: Times-Roman
+base_font_family: Helvetica
+base_font_size: 12
+# QUESTION should we rename to min_font_size?
+base_font_size_min: 9
+base_font_style: normal
+base_line_height: 1.15
+base_line_height_length: 13.8
+base_border_color: 'EEEEEE'
+base_border_width: 0.5
+link_font_color: '0000EE'
+literal_font_family: Courier
+heading_font_style: bold
+heading_h1_font_size: 24
+heading_h2_font_size: 18
+heading_h3_font_size: 16
+heading_h4_font_size: 14
+heading_h5_font_size: 12
+heading_h6_font_size: 10
+heading_line_height: 1.15
+heading_margin_top: 4
+heading_margin_bottom: 12
+title_page_align: center
+title_page_line_height: 1.15
+title_page_logo_top: 10%
+title_page_title_top: 40%
+title_page_title_font_size: 18
+title_page_subtitle_font_size: 14
+title_page_authors_margin_top: 12
+outline_list_indent: 30
+outline_list_item_spacing: 6
+description_list_description_indent: 30
+description_list_term_font_style: normal
+# NOTE currently block_padding _is_ the sidebar padding
+block_padding: 12
+block_margin_top: 0
+block_margin_bottom: 12
+caption_align: left
+caption_font_style: italic
+caption_margin_inside: 4
+caption_margin_outside: 0
+abstract_font_size: 13.5
+abstract_line_height: 1.4
+abstract_padding: 0
+admonition_border_color: 'EEEEEE'
+admonition_border_width: 0.5
+blockquote_border_color: 'EEEEEE'
+blockquote_border_width: 4
+code_font_family: Courier
+code_font_size: 10.5
+code_line_height: 1.2
+code_padding: 9
+code_border_color: 'EEEEEE'
+code_border_width: 0.5
+conum_line_height: 1.15
+example_border_color: 'EEEEEE'
+example_border_width: 0.5
+image_align: left
+lead_font_size: 13.5
+lead_line_height: 1.4
+prose_margin_top: 0
+prose_margin_bottom: 12
+sidebar_background_color: 'EEEEEE'
+sidebar_title:
+sidebar_title_align: center
+sidebar_title_font_style: bold
+table_border_color: '000000'
+table_border_width: 0.5
+table_cell_padding: 2
+table_head_font_style: bold
+thematic_break_border_color: 'EEEEEE'
+thematic_break_border_style: solid
+thematic_break_border_width: 0.5
+toc_indent: 15
+toc_line_height: 1.4
diff --git a/data/themes/default-theme.yml b/data/themes/default-theme.yml
index 2d3c16e4..3da159cf 100644
--- a/data/themes/default-theme.yml
+++ b/data/themes/default-theme.yml
@@ -24,12 +24,10 @@ font:
 page:
   background_color: ffffff
   layout: portrait
-  # NOTE multiply inches by 72 to get pt values
-  #margin: [0.5 * 72, 0.67 * 72, 0.67 * 72, 0.67 * 72]
   margin: [0.5in, 0.67in, 0.67in, 0.67in]
-  # size can be a named size (e.g., A4) or custom dimensions (e.g., [8.25in, 11.69in])
-  size: Letter
+  size: LETTER
 base:
+  align: justify
   # color as hex string (leading # is optional)
   font_color: 333333
   # color as RGB array
@@ -56,13 +54,12 @@ base:
   font_size_small: round($base_font_size * 0.85)
   font_size_min: $base_font_size * 0.75
   font_style: normal
-  align: justify
+  border_color: eeeeee
   border_radius: 4
   border_width: 0.5
-  border_color: eeeeee
 # FIXME vertical_rhythm is weird; we should think in terms of ems
 #vertical_rhythm: $base_line_height_length * 2 / 3
-# correct line height for Noto Serif metrics
+# correct line height for Noto Serif metrics (comes with built-in line height)
 vertical_rhythm: $base_line_height_length
 horizontal_rhythm: $base_line_height_length
 link:
@@ -75,6 +72,7 @@ heading:
   #font_color: 181818
   font_color: $base_font_color
   font_family: $base_font_family
+  font_style: bold
   # h1 is used for part titles
   h1_font_size: floor($base_font_size * 2.6)
   # h2 is used for chapter titles
@@ -83,105 +81,101 @@ heading:
   h4_font_size: $base_font_size_large
   h5_font_size: $base_font_size
   h6_font_size: $base_font_size_small
-  font_style: bold
   #line_height: 1.4
-  # correct line height for Noto Serif metrics
+  # correct line height for Noto Serif metrics (comes with built-in line height)
   line_height: 1.2
   margin_top: $vertical_rhythm * 0.2
   margin_bottom: $vertical_rhythm * 0.8
 title_page:
   align: right
-  title_top: 55%
-  title_font_size: $heading_h1_font_size
-  title_font_color: 999999
-  title_line_height: 0.9
-  subtitle_font_size: $heading_h3_font_size
-  subtitle_font_style: bold_italic
-  subtitle_line_height: 1
-  authors_margin_top: $base_font_size * 1.25
-  authors_font_size: $base_font_size_large
-  authors_font_color: 181818
-  revision_margin_top: $base_font_size * 1.25
-#prose:
-#  margin_top: 0
-#  margin_bottom: $vertical_rhythm 
+  logo:
+    top: 10%
+  title:
+    top: 55%
+    font_size: $heading_h1_font_size
+    font_color: 999999
+    line_height: 0.9
+  subtitle:
+    font_size: $heading_h3_font_size
+    font_style: bold_italic
+    line_height: 1
+  authors:
+    margin_top: $base_font_size * 1.25
+    font_size: $base_font_size_large
+    font_color: 181818
+  revision:
+    margin_top: $base_font_size * 1.25
 block:
-  #margin_top: 0
-  #margin_bottom: $vertical_rhythm
+  margin_top: 0
+  margin_bottom: $vertical_rhythm
+  # NOTE currently block_padding _is_ the sidebar padding
   padding: [$vertical_rhythm, $vertical_rhythm * 1.25, $vertical_rhythm, $vertical_rhythm * 1.25]
 caption:
-  font_style: italic
   align: left
+  font_style: italic
   # FIXME perhaps set line_height instead of / in addition to margins?
-  margin_inside: $vertical_rhythm * 0.25
+  margin_inside: $vertical_rhythm / 3
+  #margin_inside: $vertical_rhythm / 4
   margin_outside: 0
+lead:
+  font_size: $base_font_size_large
+  line_height: 1.4
+abstract:
+  font_color: 5c6266
+  font_size: $lead_font_size
+  line_height: $lead_line_height
+  font_style: italic
+admonition:
+  border_color: $base_border_color
+  border_width: $base_border_width
+blockquote:
+  font_color: $base_font_color
+  font_size: $base_font_size_large
+  border_color: $base_border_color
+  border_width: 5
+  cite_font_size: $base_font_size_small
+  cite_font_color: 999999
 # code is used for source blocks (perhaps change to source or listing?)
 code:
   font_color: $base_font_color
-  #font_family: Liberation Mono
-  #font_size: floor($base_font_size * 0.9)
-  #font_size: 10
-  #padding: [9.5, 9.5, 9.5, 9.5]
-  # LiberationMono carries extra gap below line
-  #padding: [10, 10, 7.5, 10]
-  #line_height: 1.45
   font_family: $literal_font_family
   font_size: ceil($base_font_size)
-  #padding: [$base_font_size, $code_font_size, $base_font_size, $code_font_size]
   padding: $code_font_size
   line_height: 1.25
   background_color: f5f5f5
   border_color: cccccc
   border_radius: $base_border_radius
   border_width: 0.75
-blockquote:
-  font_color: $base_font_color
-  font_size: $base_font_size_large
-  border_width: 5
-  border_color: $base_border_color
-  cite_font_size: $base_font_size_small
-  cite_font_color: 999999
-sidebar:
-  border_color: $page_background_color
-  border_radius: $base_border_radius
-  border_width: $base_border_width
-  background_color: eeeeee
-  title_font_color: $heading_font_color
-  title_font_family: $heading_font_family
-  title_font_size: $heading_h4_font_size
-  title_font_style: $heading_font_style
-  title_align: center
-example:
-  border_color: $base_border_color
-  border_radius: $base_border_radius
-  border_width: 0.75
-  background_color: transparent
-admonition:
-  border_color: $base_border_color
-  border_width: $base_border_width
 conum:
   font_family: M+ 1mn
   font_color: $literal_font_color
   font_size: $base_font_size
   line_height: 4 / 3
+example:
+  border_color: $base_border_color
+  border_radius: $base_border_radius
+  border_width: 0.75
+  background_color: transparent
 image:
-  align_default: left
-  scaled_width_default: 0.5
-lead:
-  # QUESTION what about $base_font_size_large?
-  #font_size: floor($base_line_height_length * 0.8)
-  #font_size: floor($base_font_size * 1.15)
-  #line_height: 1.3
-  font_size: $base_font_size_large
-  line_height: 1.4
-abstract:
-  #font_color: 404040
-  font_color: 5c6266
-  font_size: $lead_font_size
-  line_height: $lead_line_height
-  font_style: italic
+  align: left
+prose:
+  margin_top: 0
+  margin_bottom: $vertical_rhythm
+sidebar:
+  border_color: $page_background_color
+  border_radius: $base_border_radius
+  border_width: $base_border_width
+  background_color: eeeeee
+  title:
+    align: center
+    font_color: $heading_font_color
+    font_family: $heading_font_family
+    font_size: $heading_h4_font_size
+    font_style: $heading_font_style
 thematic_break:
   border_color: $base_border_color
+  border_style: solid
+  border_width: $base_border_width
   margin_top: $vertical_rhythm * 0.5
   margin_bottom: $vertical_rhythm * 1.5
 description_list:
@@ -196,6 +190,7 @@ table:
   background_color: $page_background_color
   #head_background_color: <hex value>
   #head_font_color: $base_font_color
+  head_font_style: bold
   even_row_background_color: f9f9f9
   #odd_row_background_color: <hex value>
   foot_background_color: f0f0f0
@@ -204,9 +199,9 @@ table:
   # HACK accounting for line-height
   cell_padding: [3, 3, 6, 3]
 toc:
-  indent: $horizontal_rhythm
   dot_leader_color: dddddd
-  #dot_leader_content: ". "
+  #dot_leader_content: '. '
+  indent: $horizontal_rhythm
   line_height: 1.4
 # NOTE In addition to footer, header is also supported
 footer: