"backintime" man page: Improve

[buhtz]

The man page is wired. The synopsis e.g. is just wrong and indicates that switches like --keep-mount are generally working. But they don't. Some of that switches are connected to on of the "commands", e.g. snapshot-path. This need to be reflected somehow in the man page.

I am not sure yet how to do this. Is anyone aware of another application as an example?

Here is a quick & dirty draft. The content is not valid but just an example. Not sure if this follows unixoide conventions?

SYNOPSIS
    backintime [GLOBAL OPTIONS] COMMAND [COMMAND OPTIONS] [ARGUMENTS]

GLOBAL OPTIONS:
    --config PATH       Specify configuration file path
    --debug             Enable debug output
    --help, -h          Display help information
    --license           Display license information
    --quiet             Suppress non-error messages
    --version           Display version information

COMMANDS:
    backup              Perform backup operations
    backup-job          Manage backup jobs
    benchmark-cipher    Benchmark encryption cipher
    check-config        Check configuration syntax
    decode [PATH]       Decode encrypted file or directory
    last-snapshot       Display information about the last snapshot
    last-snapshot-path  Display path of the last snapshot
    pw-cache            Manage password cache service
    remove              Remove a snapshot
    restore             Restore files from a snapshot
    snapshots-list      List available snapshots
    snapshots-list-path List paths of available snapshots
    snapshots-path      Display snapshot storage path
    unmount             Unmount snapshot storage

COMMAND OPTIONS:
    backup:
        --checksum          Enable checksum verification during backup
        --local-backup      Perform backup only on local filesystem
    
    snapshots-list-path, snapshots-path:
        --keep-mount        Keep snapshot storage mounted after operation
    
    restore:
        --profile NAME      Specify profile for restoration
        --profile-id ID     Specify profile ID for restoration
    
    pw-cache:
        start|stop|restart|reload|status  Control password cache service
    
    remove:
        --delete-and-do-not-ask-again  Delete snapshot without confirmation
    
    decode:
        [PATH]              Path to encrypted file or directory
    
    ARGUMENTS:
        SNAPSHOT_ID         Identifier of a specific snapshot

DESCRIPTION:
    Back In Time is a backup application ...

EXAMPLES:
    backintime backup --checksum
    backintime --help
    backintime snapshots-list-path --keep-mount
    backintime snapshots-path --keep-mount
    backintime backup --checksum

EDIT: Maybe a good opportunity to switch from troff to markdown source format. It is possible to generate man pages from markdown files. Never tried it. ... Did some more research. There is no ideal format doing this. Markdown has its short commings compared to man page (roff) and work only with a lot of extra addons. Let's stick with regular roff.

EDIT2: Also the headings should be improved. Currently:

$ man -k backintime
backintime (1)       - a simple backup tool for Linux.
backintime-askpass (1) - a simple backup tool for Linux.
backintime-config (1) - BackInTime configuration files.
backintime-qt (1)    - a simple backup tool.