Skip to content

Print documentation in default config #89

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
GlowingScrewdriver wants to merge 7 commits into
base: main
Choose a base branch
from
Open

Print documentation in default config #89

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
5d878d0
Print a comment for each config field
GlowingScrewdriver Apr 29, 2026
b43d492
Add descriptions for all config sections and fields
GlowingScrewdriver Apr 30, 2026
53b936d
Real descriptions for tile mode
GlowingScrewdriver May 23, 2026
0b67839
Real descriptions for floating mode
GlowingScrewdriver May 23, 2026
8a5f216
Real descriptions for bisect mode
GlowingScrewdriver May 23, 2026
4b08b83
Real descriptions for split and click mode
GlowingScrewdriver May 23, 2026
30b3d58
Section descriptions before section headers
GlowingScrewdriver May 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
258 changes: 199 additions & 59 deletions src/config.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -318,38 +318,41 @@ struct field_def {
char *default_value;
int (*parse)(void *dest, char *value);
void (*free)(void *value);
char *desc;
};

struct section_def {
char *name;
char *desc;
size_t offset;
struct field_def **fields;
};

#define SECTION(name, ...) \
#define SECTION(name, desc, ...) \
(struct section_def) { \
#name, offsetof(struct config, name), (struct field_def *[]) { \
#name, desc, \
offsetof(struct config, name), (struct field_def *[]) { \
__VA_ARGS__, NULL \
} \
}

#define FIELD(type, name, default_value, parse, free) \
(struct field_def[]) { \
#name, offsetof(type, name), default_value, parse, free \
#define FIELD(type, name, default_value, parse, free, desc) \
(struct field_def[]) { \
#name, offsetof(type, name), default_value, parse, free, desc \
}

#define G_FIELD(name, default_value, parse, free) \
FIELD(struct general_config, name, default_value, parse, free)
#define MT_FIELD(name, default_value, parse, free) \
FIELD(struct mode_tile_config, name, default_value, parse, free)
#define MF_FIELD(name, default_value, parse, free) \
FIELD(struct mode_floating_config, name, default_value, parse, free)
#define MB_FIELD(name, default_value, parse, free) \
FIELD(struct mode_bisect_config, name, default_value, parse, free)
#define MS_FIELD(name, default_value, parse, free) \
FIELD(struct mode_split_config, name, default_value, parse, free)
#define MC_FIELD(name, default_value, parse, free) \
FIELD(struct mode_click_config, name, default_value, parse, free)
#define G_FIELD(name, default_value, parse, free, desc) \
FIELD(struct general_config, name, default_value, parse, free, desc)
#define MT_FIELD(name, default_value, parse, free, desc) \
FIELD(struct mode_tile_config, name, default_value, parse, free, desc)
#define MF_FIELD(name, default_value, parse, free, desc) \
FIELD(struct mode_floating_config, name, default_value, parse, free, desc)
#define MB_FIELD(name, default_value, parse, free, desc) \
FIELD(struct mode_bisect_config, name, default_value, parse, free, desc)
#define MS_FIELD(name, default_value, parse, free, desc) \
FIELD(struct mode_split_config, name, default_value, parse, free, desc)
#define MC_FIELD(name, default_value, parse, free, desc) \
FIELD(struct mode_click_config, name, default_value, parse, free, desc)

static void noop() {}

Expand All @@ -358,61 +361,195 @@ static void noop() {}
static struct section_def section_defs[] = {
SECTION(
general,
G_FIELD(home_row_keys, "", parse_home_row_keys, free_home_row_keys),
G_FIELD(modes, "tile,bisect", parse_str, free_str),
G_FIELD(cancellation_status_code, "0", parse_uint8, noop)
"General configuration",
G_FIELD(
home_row_keys, "", parse_home_row_keys, free_home_row_keys,
"Home row keys"
Comment on lines +366 to +367
Copy link
Copy Markdown
Owner

@moverest moverest May 26, 2026

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.

),
G_FIELD(
modes, "tile,bisect", parse_str, free_str,
"Modes to use; will be chained"
Copy link
Copy Markdown
Owner

@moverest moverest May 26, 2026

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."

),
G_FIELD(
cancellation_status_code, "0", parse_uint8, noop,
"Status code to exit with when cancelled"
)
),
SECTION(
mode_tile, MT_FIELD(label_color, "#fffd", parse_color, noop),
MT_FIELD(label_select_color, "#fd0d", parse_color, noop),
MT_FIELD(unselectable_bg_color, "#2226", parse_color, noop),
MT_FIELD(selectable_bg_color, "#0304", parse_color, noop),
MT_FIELD(selectable_border_color, "#040c", parse_color, noop),
MT_FIELD(label_font_family, "sans-serif", parse_str, free_str),
MT_FIELD(label_font_size, "8 50% 100", parse_relative_font_size, noop),
mode_tile,
"Configuration for tile mode",
MT_FIELD(
label_color, "#fffd", parse_color, noop,
"Label color for selectable regions"
),
MT_FIELD(
label_select_color, "#fd0d", parse_color, noop,
"Label color for selected regions"
),
MT_FIELD(
unselectable_bg_color, "#2226", parse_color, noop,
"Background color for unselectable regions"
),
MT_FIELD(
selectable_bg_color, "#0304", parse_color, noop,
"Background color for selectable regions"
),
MT_FIELD(
selectable_border_color, "#040c", parse_color, noop,
"Border color for selectable regions"
),
MT_FIELD(
label_symbols, "abcdefghijklmnopqrstuvwxyz", parse_str, free_str
label_font_family, "sans-serif", parse_str, free_str,
"Font family for labels"
),
MT_FIELD(
label_font_size, "8 50% 100", parse_relative_font_size, noop,
"Font size for labels"
),
MT_FIELD(
label_symbols, "abcdefghijklmnopqrstuvwxyz", parse_str, free_str,
"Characters to use in labels"
)
),
SECTION(
mode_floating,
MF_FIELD(source, "stdin", parse_floating_mode_source_value, noop),
MF_FIELD(label_color, "#fffd", parse_color, noop),
MF_FIELD(label_select_color, "#fd0d", parse_color, noop),
MF_FIELD(unselectable_bg_color, "#2226", parse_color, noop),
MF_FIELD(selectable_bg_color, "#1718", parse_color, noop),
MF_FIELD(selectable_border_color, "#040c", parse_color, noop),
MF_FIELD(label_font_family, "sans-serif", parse_str, free_str),
MF_FIELD(label_font_size, "12 50% 100", parse_relative_font_size, noop),
"Configuration for floating mode",
MF_FIELD(
source, "stdin", parse_floating_mode_source_value, noop,
"Source of selectable regions. Possible values:\n"
"* `detect` -- auto-detect regions with OpenCV\n"
"* `stdin` -- read region definitions from stdin"
),
MF_FIELD(
label_color, "#fffd", parse_color, noop,
"Label color for selectable regions"
),
MF_FIELD(
label_select_color, "#fd0d", parse_color, noop,
"Label color for selected regions"
),
MF_FIELD(
label_symbols, "abcdefghijklmnopqrstuvwxyz", parse_str, free_str
unselectable_bg_color, "#2226", parse_color, noop,
"Background color for unselectable regions"
),
MF_FIELD(
selectable_bg_color, "#1718", parse_color, noop,
"Background color for selectable regions"
),
MF_FIELD(
selectable_border_color, "#040c", parse_color, noop,
"Border color for selectable regions"
),
MF_FIELD(
label_font_family, "sans-serif", parse_str, free_str,
"Font family for labels"
),
MF_FIELD(
label_font_size, "12 50% 100", parse_relative_font_size, noop,
"Font size for labels"
),
MF_FIELD(
label_symbols, "abcdefghijklmnopqrstuvwxyz", parse_str, free_str,
"Characters to use in labels"
)
),
SECTION(
mode_bisect, MB_FIELD(label_color, "#fffd", parse_color, noop),
// TODO[glowingscewdriver]: Explain "even" and "odd" areas
mode_bisect,
"Configuration for bisect mode",
MB_FIELD(
label_color, "#fffd", parse_color, noop,
"Label color for selectable regions"
),
// TODO: we should set minimums for numbers.
MB_FIELD(label_font_size, "20", parse_double, noop),
MB_FIELD(label_font_family, "sans-serif", parse_str, free_str),
MB_FIELD(label_padding, "12", parse_double, noop),
MB_FIELD(pointer_size, "20", parse_double, noop),
MB_FIELD(pointer_color, "#e22d", parse_color, noop),
MB_FIELD(unselectable_bg_color, "#2226", parse_color, noop),
MB_FIELD(even_area_bg_color, "#0304", parse_color, noop),
MB_FIELD(even_area_border_color, "#0408", parse_color, noop),
MB_FIELD(odd_area_bg_color, "#0034", parse_color, noop),
MB_FIELD(odd_area_border_color, "#0048", parse_color, noop),
MB_FIELD(history_border_color, "#3339", parse_color, noop)
MB_FIELD(
label_font_size, "20", parse_double, noop,
"Font size for labels"
),
MB_FIELD(
label_font_family, "sans-serif", parse_str, free_str,
"Font family for labels"
),
MB_FIELD(
// TODO[glowingscrewdriver]: What does this actually do?
Copy link
Copy Markdown
Author

@GlowingScrewdriver GlowingScrewdriver May 24, 2026

Choose a reason for hiding this comment

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

I wasn't able to figure out exactly what label_padding is supposed to do. I just wanted to bring this up in case a) I'm missing something, or b) the behaviour is unintended.

I tried playing around with extreme values (0 and 50, for e.g.) and the only difference I noticed was after the selectable areas become very small.

After bisecting a number of times, the areas are so small that an area's label is drawn outside the area itself. In this scenario, the distance between a label and its area seems to correlate with label_padding.

When the areas are big enough to contain their labels, label_padding doesn't seem to have an effect.

recording.webm

Copy link
Copy Markdown
Owner

@moverest moverest May 26, 2026

Choose a reason for hiding this comment

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

After bisecting a number of times, the areas are so small that an area's label is drawn outside the area itself. In this scenario, the distance between a label and its area seems to correlate with label_padding.

Yes, that's the spacing between the rectangle and the label. It only has an effect when the area is small enough that the label has to be displayed outside of it.

For context, in the early versions, the labels would only be displayed outside the area not inside as the bisect was followed by the bisect mode and that was not configurable, i.e. the default behaviour without any options. This means that the selection areas were always small.

label_padding, "12", parse_double, noop,
"Padding for labels"
),
MB_FIELD(
pointer_size, "20", parse_double, noop,
"Pointer size"
),
MB_FIELD(
pointer_color, "#e22d", parse_color, noop,
"Pointer color"
),
MB_FIELD(
unselectable_bg_color, "#2226", parse_color, noop,
"Background color for unselectable regions"
),
MB_FIELD(
even_area_bg_color, "#0304", parse_color, noop,
"Background color for even areas"
),
MB_FIELD(
even_area_border_color, "#0408", parse_color, noop,
"Border color for even areas"
),
MB_FIELD(
odd_area_bg_color, "#0034", parse_color, noop,
"Background color for odd areas"
),
MB_FIELD(
odd_area_border_color, "#0048", parse_color, noop,
"Border color for odd areas"
),
MB_FIELD(
history_border_color, "#3339", parse_color, noop,
"Border color for selection hisory"
)
),
SECTION(
mode_split, MS_FIELD(pointer_size, "20", parse_double, noop),
MS_FIELD(pointer_color, "#e22d", parse_color, noop),
MS_FIELD(bg_color, "#2226", parse_color, noop),
MS_FIELD(area_bg_color, "#11111188", parse_color, noop),
MS_FIELD(vertical_color, "#8888ffcc", parse_color, noop),
MS_FIELD(horizontal_color, "#008800cc", parse_color, noop),
MS_FIELD(history_border_color, "#3339", parse_color, noop)
mode_split,
"Configuration for split mode",
MS_FIELD(
pointer_size, "20", parse_double, noop,
"Pointer size"
),
MS_FIELD(
pointer_color, "#e22d", parse_color, noop,
"Pointer color"
),
MS_FIELD(
// TODO[glowingscrewdriver] why is this not named
// `unselectable_bg_color`?
Copy link
Copy Markdown
Author

@GlowingScrewdriver GlowingScrewdriver May 24, 2026

Choose a reason for hiding this comment

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

Is there a specific reason that this config field isn't named unselectable_bg_color? In all partitioning modes, when the user selects a region, the area outside that region becomes "unselectable", and is colored differently. In the other modes that color is unselectable_bg_color, but for split it is bg_color.

Just wanted to clarify this since I noticed it while writing the descriptions. It isn't a blocker to this PR.

Copy link
Copy Markdown
Owner

@moverest moverest May 26, 2026

Choose a reason for hiding this comment

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

I can't think of a reason other than I probably didn't notice the inconsistency. Let's keep it as bg_color as to not break compatibility with existing configurations.

bg_color, "#2226", parse_color, noop,
"Background color for unselectable area"
),
MS_FIELD(
area_bg_color, "#11111188", parse_color, noop,
"Background color for selectable area"
),
MS_FIELD(
vertical_color, "#8888ffcc", parse_color, noop,
"Color for vertical split marker"
),
MS_FIELD(
horizontal_color, "#008800cc", parse_color, noop,
"Color for horizontal split marker"
),
MS_FIELD(
history_border_color, "#3339", parse_color, noop,
"Border color for selection history"
)
),
SECTION(
mode_click,
"Configuration for click mode",
MC_FIELD(
button, "left", parse_click, noop,
"Mouse button to trigger"
)
),
SECTION(mode_click, MC_FIELD(button, "left", parse_click, noop)),
};
#pragma GCC diagnostic pop

Expand All @@ -425,13 +562,16 @@ void print_default_config() {
for (int i = 0; i < sizeof(section_defs) / sizeof(section_defs[0]); i++) {
struct section_def *section_def = &section_defs[i];

printf("\n[%s]\n", section_def->name);
printf("\n## %s ##\n[%s]\n", section_def->desc, section_def->name);

for (struct field_def **field_def_ptr = section_def->fields;
*field_def_ptr != NULL; field_def_ptr++) {
struct field_def *field_def = *field_def_ptr;

printf("%s=%s\n", field_def->name, field_def->default_value);
printf(
"# %s\n%s=%s\n\n",
field_def->desc, field_def->name, field_def->default_value
);
}
}
}
Expand Down