btrbk.conf syntax: Clarify the scope of "sections"

[camoz]

Hi,

I was a bit confused when first reading btrbk.conf(5) and creating my own btrbk.conf, about what a "section" actually is. The man page section "SECTIONS" only lists sections, but says nothing about what they actually are. The only info is in "DESCRIPTION":

The options specified always apply to the last section encountered, superseding the values set in upper-level sections. This means that global options must be set before any sections are defined.

But this again does not really say what a section is.

Then, when looking at the provided example config, IMO it heavily suggests that the scope of a section is defined by its indentation (like in python), as there are no other syntactical elements like brackets, that could specify its scope.

From what I understand now, a section extends until the beginning of the next section. This is rather unintuitive from an end-user perspective (maybe more intuitive for the dev) and should be explained somewhere. But some things are still unclear, IMO: Is there a section hierarchy? What do the mentioned "upper-level sections" exactly mean? All previous sections? Or the immediately preceding section? And which sections can contain what other sections?

While going through the issues here, it seems that there are also a few other people which were confused by it.

As backup software is a pretty critical piece of software, IMO it's important to have a simple, intuitive config format, and if not, then at least a very precise description of how it works. A fundamental change to the config file syntax would obviously break many setups, so I guess that's not an option. Therefore, I think the man page btrbk.conf(5) should be expanded, elaborating more on how sections are defined and how they interact with each other.

Also, sometimes the word context is used in btrbk.conf(5). AFAICS it refers to "sections". Maybe that could be unified as well.

Random example of some of my confusion:

This fails with ERROR: Option "snapshot_dir" is only allowed in global or volume or subvolume context:

target /mnt/backup_btrfs/@snapshots
snapshot_dir /mnt/snapshots
subvolume /

But this runs fine (just first two lines swapped):

snapshot_dir /mnt/snapshots
target /mnt/backup_btrfs/@snapshots
subvolume /

(I understand now why, just for illustration...)

Summary (assuming config file syntax change won't happen)

• mention in btrbk.conf(5) that indentation has no meaning
• mention in example config that indentation has no meaning
• explain in btrbk.conf(5) how sections are defined, what their scope is, and how exactly they interact with each other, including precedence/hierarchy/...
• Define the word context (e.g. that it means "a section or global context" or so)

[luxagen]

As a side note, the inability to explicitly "close" a (vol/subvol) section in order to add more options to the parent item or at the global level tends to make my btrbk.conf much larger than it would otherwise be.

I also use indentation to indicate the nesting of sections in my config, so I'd be 100% okay with btrbk changing to make indentation significant à la Python. Just my two cents.