Skip to content

Print documentation in default config#89

Open
GlowingScrewdriver wants to merge 9 commits into
moverest:mainfrom
GlowingScrewdriver:config-desc
Open

Print documentation in default config#89
GlowingScrewdriver wants to merge 9 commits into
moverest:mainfrom
GlowingScrewdriver:config-desc

Conversation

@GlowingScrewdriver

Copy link
Copy Markdown

This change causes wl-kbptr --help-config to print comments containing descriptions for all fields and sections in the default config. Since --help-config prints an exhaustive list of all config fields and sections, what is printed is effectively full documentation on configuration.

May fix #50

Comments themselves are dummy
The descriptions need work, but the code is there.
@GlowingScrewdriver

GlowingScrewdriver commented Apr 30, 2026

Copy link
Copy Markdown
Author

I've opened this PR as a draft, since the descriptions themselves aren't complete. Apart from that, the code changes are ready for review.

At present, the difference in the default config looks like this:

Details
diff --git a/config.old b/config.new
index 9d6dbac..7c1fc33 100644
--- a/config.old
+++ b/config.new
@@ -4,53 +4,139 @@
 # be loaded if it exits. Below is the default configuration.
 
 [general]
+## General configuration ##
+# Home row keys
 home_row_keys=
+
+# Modes to use
 modes=tile,bisect
+
+# Status code to exit with when cancelled
 cancellation_status_code=0
 
+
 [mode_tile]
+## Configuration for tile mode ##
+# Label color
 label_color=#fffd
+
+# Selected label color
 label_select_color=#fd0d
+
+# Background color for unselectable
 unselectable_bg_color=#2226
+
+# Background color for selectable
 selectable_bg_color=#0304
+
+# Border color for selectable
 selectable_border_color=#040c
+
+# Font family for label
 label_font_family=sans-serif
+
+# Font size for label
 label_font_size=8 50% 100
+
+# Symbols to use for labels
 label_symbols=abcdefghijklmnopqrstuvwxyz
 
+
 [mode_floating]
+## Configuration for floating mode ##
+# Source
 source=stdin
+
+# Color of labels
 label_color=#fffd
+
+# Selected label color
 label_select_color=#fd0d
+
+# Background color of unselectable
 unselectable_bg_color=#2226
+
+# Background color of selectable
 selectable_bg_color=#1718
+
+# Border color of selectable
 selectable_border_color=#040c
+
+# Font family for label
 label_font_family=sans-serif
+
+# Font size for label
 label_font_size=12 50% 100
+
+# Symbols to use for labels
 label_symbols=abcdefghijklmnopqrstuvwxyz
 
+
 [mode_bisect]
+## Configuration for bisect mode ##
+# Label color
 label_color=#fffd
+
+# Font size for labels
 label_font_size=20
+
+# Font family for labels
 label_font_family=sans-serif
+
+# Padding for labels
 label_padding=12
+
+# Pointer size
 pointer_size=20
+
+# Pointer color
 pointer_color=#e22d
+
+# Background color for unselectable
 unselectable_bg_color=#2226
+
+# Background color for even area
 even_area_bg_color=#0304
+
+# Border color for even area
 even_area_border_color=#0408
+
+# Background color for odd area
 odd_area_bg_color=#0034
+
+# Border color for odd area
 odd_area_border_color=#0048
+
+# Border color for history
 history_border_color=#3339
 
+
 [mode_split]
+## Configuration for split mode ##
+# Pointer size
 pointer_size=20
+
+# Pointer color
 pointer_color=#e22d
+
+# Background color
 bg_color=#2226
+
+# Background color for area
 area_bg_color=#11111188
+
+# Color for vertical marker
 vertical_color=#8888ffcc
+
+# Color for horizontal marker
 horizontal_color=#008800cc
+
+# Border color for history
 history_border_color=#3339
 
+
 [mode_click]
+## Configuration for click mode ##
+# Mouse button
 button=left
+

@moverest

Copy link
Copy Markdown
Owner

That looks great! If I was to nitpick, I'd have the description for the section before it like the rest but honestly it's fine.

Comment thread src/config.c Outdated
Comment thread src/config.c Outdated
@GlowingScrewdriver

Copy link
Copy Markdown
Author

@moverest descriptions are mostly ready, and I've moved the comments before the section like you suggested.

@GlowingScrewdriver GlowingScrewdriver marked this pull request as ready for review May 24, 2026 05:03
Comment thread src/config.c Outdated
Comment thread src/config.c Outdated
Comment thread src/config.c Outdated
Comment on lines +366 to +367
home_row_keys, "", parse_home_row_keys, free_home_row_keys,
"Home row keys"

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It would make sense to explain this one with more details. See #6.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done

Comment thread src/config.c Outdated
),
G_FIELD(
modes, "tile,bisect", parse_str, free_str,
"Modes to use; will be chained"

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
"Modes to use; will be chained"
"Modes (tile, bisect, split or float) to use; will be chained."

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done

`print_comment` is a helper that prints multi-line
strings as comments.
@GlowingScrewdriver

Copy link
Copy Markdown
Author

Apologies for the long silence -- my day job caught up.

I've filled in the remaining descriptions. I've also introduced a helper (print_comment) to print multi-line comments, since some of the descriptions ended up being rather long.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Documentation

2 participants