config: default preferences for 0.2.4

Although rationale is default preferences
that could match most common use cases,
this remains highly subjective.

src/dtsh/config.py

@@ -398,11 +398,6 @@ def pref_yaml_theme(self) -> str:
         """Theme for YAML syntax highlighting."""
         return self.getstr("pref.yaml.theme")
 
-    @property
-    def pref_yaml_expand(self) -> bool:
-        """whether to expand included files in YAML views."""
-        return self.getbool("pref.yaml.expand")
-
     @property
     def pref_yaml_actionable_type(self) -> ActionableType:
         """Actionable type for YAML views."""

src/dtsh/dtsh.ini

@@ -156,11 +156,6 @@ prompt.sparse = yes
 # Default: True
 pref.always_longfmt = no
 
-# Maximum width in number characters for commands output redirection.
-# Type: Integer
-# Default: 255
-pref.redir2_maxwidth = 255
-
 # Whether to print sizes with SI units (bytes, kB, MB).
 # Otherwise, sizes are printed in hexadecimal format.
 # Type: Bool
@@ -280,16 +275,17 @@ pref.tree.actionable_type = none
 #   - "none": do not create hyperlinks
 #   - "link" (default): link text like browsers do
 #   - "alt": append alternative actionable view
-pref.2sided.actionable_type = link
+pref.2sided.actionable_type = alt
 
 
-# Symbol to anchor child-bindings to their parent in tree-views.
+# Symbol to anchor child-bindings to their parent
+# in tree-views.
 # Set it to an empty value to disable.
 #
+# Example anchor: ${wchar.arrow_right_hook}
+#
 # Type: String
-# Default: Rightwards arrow with hook.
-# pref.tree.cb_anchor = ${wchar.arrow_right_hook}
-# NOTE: disabled, may be confusing.
+# Default: disabled
 pref.tree.cb_anchor =
 
 # Default rendering for actionable texts (aka links).
@@ -316,20 +312,27 @@ pref.actionable_type = link
 pref.actionable_wchar = [${wchar.arrow_ne}]
 
 
+# Maximum width in number characters for commands output redirection.
+# Type: Integer
+# Default: 255
+pref.redir2_maxwidth = 255
+
+
 # Command output redirection to HTML: theme.
 #
 # Configure text and background colors for HTML documents.
 #
 # Possible values:
-# - "svg": default theme for SVG documents (dark bakground, light text)
-# - "html": default theme for HTML documents (light bakground, dark text)
+# - "svg": default theme for SVG and HTML documents
+#   (looks like reading in a console with a dark color profile)
+# - "html": theme recommended for printable HTML documents (no background)
 # - "dark": darker
 # - "light": lighter
-# - "night": darkest
-#
+# - "night": darkest, highest contrasts
+
 # Type: String
-# Default: default
-pref.html.theme = html
+# Default: svg
+pref.html.theme = svg
 
 # Command output redirection to HTML: font family.
 # This the family name, e.g. "Source Code Pro".
@@ -340,21 +343,21 @@ pref.html.theme = html
 # Note:
 # - the generic "monospace" family is automatically appended last
 # - the "Courier New" font family is installed nearly everywhere,
-#   but will likely not provide all box drawing characters required
+#   but will unlikely provide all box drawing characters required
 #   to properly render (sharp) trees and tables
 # - "DejaVu Sans Mono" is almost as widespread, and trees and tables
-#   should render fine, at least for the default font size
-# - the "Source Code Pro" font family is quite popular among software
-#   engineers, and trees and tables should render fine for more
-#   font sizes
+#   should render fine, at least for the default HTML font size ("medium")
+# - fonts families like "Source Code Pro" are quite popular
+#   among software engineers, and may offer better rendering for
+#   non default font sizes
 #
 # The HTML client should pick up the first font it finds: to use the
 # default monospace font configured in e.g. your browser's settings,
 # just leave this preference empty.
 #
 # Type: String
-# Default: "Source Code Pro, DejaVu Sans Mono, Courrier New"
-pref.html.font_family = Source Code Pro, DejaVu Sans Mono, Courrier New
+# Default: "DejaVu Sans Mono"
+pref.html.font_family = DejaVu Sans Mono
 
 # Command output redirection to HTML: font size.
 #
@@ -371,36 +374,34 @@ pref.html.font_size = medium
 
 # Command output redirection to HTML: compact output.
 #
-# Compact output does not separate successive captured commands
-# by a blank line.
+# When this preference is set, DTSh won't separate successive captured commands
+# by an additional blank line.
+# Recommended for HTML.
 #
 # Type: bool
-# Default: no
-pref.html.compact = no
+# Default: Yes
+pref.html.compact = yes
 
 
 # Command output redirection to SVG: theme.
 #
 # Configure text and background colors for SVG documents.
 #
 # Possible values:
-# - "svg": default theme for SVG documents (dark bakground, light text)
-# - "html": default theme for HTML documents (light bakground, dark text)
+# - "svg": default theme for SVG and HTML documents
+#   (looks like reading in a console with a dark color profile)
+# - "html": theme recommended for printable HTML documents (no background)
 # - "dark": darker
 # - "light": lighter
-# - "night": darkest
+# - "night": darkest, highest contrasts
 #
 # Type: String
-# Default: default
+# Default: svg
 pref.svg.theme = svg
 
 # Command output redirection to SVG: font family.
 # This the family name, e.g. "Source Code Pro".
 #
-# Note that box drawing is still character based
-# when formatting to SVG: the same considerations
-# as for HTML format apply.
-#
 # See also: pref.html.font_family
 #
 # Fira Code:
@@ -410,11 +411,11 @@ pref.svg.theme = svg
 # - it's the default font expected by the rich API when exporting
 #   to SVG, it's thus well tested
 # - but the CSS style will be lost if the SVG file is used
-#   as an HTML <img>
+#   in an HTML <img> tag
 #
 # Type: String
-# Default: Fira Code, DejaVu Sans Mono, Courrier New
-pref.svg.font_family = Fira Code, DejaVu Sans Mono, Courrier New
+# Default: Fira Code
+pref.svg.font_family = Fira Code, DejaVu Sans Mono
 
 # Command output redirection to SVG: font aspect ratio.
 # This is the width to height ratio, typically 3:5.
@@ -428,7 +429,7 @@ pref.svg.font_ratio = 0.61
 # Add a title to SVG output.
 #
 # Type: string
-# Default: empty
+# Default: No title
 pref.svg.title =
 
 # Command output redirection to SVG: contents decoration.
@@ -441,8 +442,8 @@ pref.svg.decorations = no
 
 # Command output redirection to SVG: compact output.
 #
-# Compact output does not separate successive captured commands
-# by a blank line.
+# When this preference is set, DTSh won't separate successive captured commands
+# by an additional blank line.
 #
 # Type: bool
 # Default: no
@@ -462,19 +463,15 @@ pref.svg.compact = no
 #
 # Type: String
 # Default: monokai
-pref.yaml.theme = monokai
-
-# Whether to expand included files
-# in YAML views.
-pref.yaml.expand = yes
+pref.yaml.theme = nord
 
 # YAML views: rendering for actionable texts (aka links).
 #
 # Type: String
 #   - "none": do not create hyperlinks
 #   - "link" (default): link text like browsers do
 #   - "alt": append alternative actionable view
-pref.yaml.actionable_type = alt
+pref.yaml.actionable_type = link
 
 
 # Pygments theme for DTS syntax highlighting.
@@ -502,6 +499,8 @@ pref.dts.actionable_type = alt
 
 # Whether to show missing fields in form views.
 #
+# If unset, fields with no value are hidden.
+#
 # Type: bool
 # Default: yes
 pref.form.show_all = yes

tests/test_dtsh_config.py

@@ -122,7 +122,7 @@ def test_dtshconfig_defaults() -> None:
     assert ActionableType.NONE == ActionableType(
         cfg_defaults.pref_tree_actionable_type
     )
-    assert ActionableType.LINK == cfg_defaults.pref_2Sided_actionable_type
+    assert ActionableType.ALT == cfg_defaults.pref_2Sided_actionable_type
     # 2-sided views child marker (disabled).
     assert not cfg_defaults.pref_tree_cb_anchor
 
@@ -131,24 +131,17 @@ def test_dtshconfig_defaults() -> None:
     assert cfg_defaults.pref_actionable_text
 
     # HTML.
-    assert "html" == cfg_defaults.pref_html_theme
-    assert (
-        "'Source Code Pro','DejaVu Sans Mono','Courrier New'"
-        == cfg_defaults.pref_html_font_family
-    )
+    assert "svg" == cfg_defaults.pref_html_theme
+    assert "'DejaVu Sans Mono'" == cfg_defaults.pref_html_font_family
 
     # SVG.
     assert "svg" == cfg_defaults.pref_svg_theme
-    assert (
-        "'Fira Code','DejaVu Sans Mono','Courrier New'"
-        == cfg_defaults.pref_svg_font_family
-    )
+    assert "'Fira Code','DejaVu Sans Mono'" == cfg_defaults.pref_svg_font_family
     assert 0.61 == cfg_defaults.pref_svg_font_ratio
 
     # YAML.
-    assert "monokai" == cfg_defaults.pref_yaml_theme
-    assert cfg_defaults.pref_yaml_expand
-    assert ActionableType.ALT == cfg_defaults.pref_yaml_actionable_type
+    assert "nord" == cfg_defaults.pref_yaml_theme
+    assert ActionableType.LINK == cfg_defaults.pref_yaml_actionable_type
 
     # DTS.
     assert "monokai" == cfg_defaults.pref_dts_theme