Proposed Simplification of Configuration Docs

[RollingStar]

We're having some discussion in #4987 and I want to bring the community in. This is a bit esoteric so if the headline of this post doesn't interest you, feel free to skip this.

I want beets to be user friendly for "basic" actions. Right now I think the config page has grown too long and too complicated because beets is so useful and has so many options.

This is my vision:

1. sort config_default.yaml and put items into categories https://github.com/beetbox/beets/blob/d927262bd51154b9860d55eabf66dd7d4eba2890/beets/config_default.yaml
2. sort config page of docs to match config_default. (For maintainers: config_default and the config doc page[s] should be in lockstep; there should be a commented note at the top of config_default and the doc pages)
3. split config page of docs into basic/advanced
4. split config yaml into basic/advanced yamls (not sure how hard it would be to have cascading configs; I think JOJ0 does this now).
5. Support function definitions in their own user_inline.py file to take advantage of code markup and symbol definitions in IDEs. Per JOJ0's feedback, I think we can leave it optional for a while and leave a warning that it may be unsupported at a future date. Inline python in yaml is, frankly, janky, and we should not be attached to it as the future of this project.

For #4 , JOJ0 had the idea that all config options should be exposed to the command line. I'm fine with that, but I think CLI is less useful to most people than a config file. As a Windows user, I can use a PuTTY instance to connect to my linux box, but the shell isn't very advanced (no zsh). I can also run Powershell on Windows, or if I'm feeling advanced, Windows Terminal (haven't tried it). Or WSL2. Meanwhile, with a config file and the right plugin, I can connect to any beets instance under the sun, and use my favorite text editor to edit it. VS Code + YAML highlighting is my editor of choice. The command line is intuitive for the linux world but not everyone is that comfortable with it.

The idea is that a user should not have to be mucking around in a 75-item docs page if they just want to change a destination path. Most users don't need to change musicbrainz: or terminal_encoding: as often as they change quiet: or inline (plugin). The difference is semantic and not code-based. As such, I don't think it's a huge problem which items get designated "basic" vs. "advanced" - they will work the same. We're just trying to accommodate more basic users. Advanced users are more able to find their way around a config doc and file anyway. Today's basic user is tomorrow's advanced user, if you give them a comfortable journey.

Global Options
	library
	directory
	plugins
	include
	pluginpath
	ignore
	ignore_hidden
	replace
	path_sep_replace
	asciify_paths
	art_filename
	threaded
	format_item
	format_album
	sort_item
	sort_album
	sort_case_insensitive
	original_date
	artist_credit
	per_disc_numbering
	aunique
	sunique
	terminal_encoding
	clutter
	max_filename_length
	id3v23
	va_name
UI Options
	color
	colors
	terminal_width
	length_diff_thresh
	import
Importer Options
	write
	copy
	move
	link
	hardlink
	reflink
	resume
	incremental
	incremental_skip_later
	from_scratch
	quiet
	quiet_fallback
	none_rec_action
	timid
	log
	default_action
	languages
	ignored_alias_types
	detail
	group_albums
	autotag
	duplicate_keys
	duplicate_action
	duplicate_verbose_prompt
	bell
	set_fields
	singleton_album_disambig
MusicBrainz Options
	enabled
	searchlimit
	extra_tags
	genres
	external_ids
Autotagger Matching Options
	max_rec
	preferred
	ignored
	required
	ignored_media
	ignore_data_tracks
	ignore_video_tracks
Path Format Configuration
Configuration Location
	Environment Variable
	Command-Line Option
	Default Location
Example

[Serene-Arc]

I think if we have a split, then there should be a simple page with the common options, and then a page with everything at least. There should be a master resource location where every option can be seen and searched, rather than being in multiple locations.

[xeruf]

That would be nice, just starting to use beets and had to skim the config file back and forth to find out what I need - maybe the former should be a quickstart with common configs but also common commands.

[xeruf]

Well that kinda exists, but that should be available as manpage as well?
https://beets.readthedocs.io/en/stable/guides/main.html