PBM-1663 Improve Profile's feature UX

[rasika-chivate]

Enhance the user experience of the Profile feature. For more detailed information, refer to the ticket:

https://perconadev.atlassian.net/browse/PBM-1663

[Copilot]

Pull request overview

This pull request enhances the documentation for PBM's Profile feature UX by adding comprehensive guidance on using the --profile flag with multiple storage configurations. The changes make it clearer how to select different storage backends (main or external profiles) when running backup-related commands.

Changes:

• Added detailed documentation for using --profile flag with pbm list and pbm status commands
• Created a new comprehensive section explaining --profile flag usage, including commands that support it, allowed values, reserved names, and naming rules
• Added examples demonstrating how to list backups and check status from different storage profiles

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
docs/reference/pbm-commands.md	Enhanced pbm list and pbm status command documentation with --profile flag usage examples, tabular output descriptions, and storage selection guidance
docs/features/multi-storage.md	Added comprehensive "Select a storage with --profile" section covering commands, allowed values, reserved names, and profile naming rules

Comments suppressed due to low confidence (8)

docs/reference/pbm-commands.md:455

• The line has an incorrect trailing double quote. The line currently reads: - '--profile=<profile_name>' to list backups from an external storage configured as a profile" but should end with a period or no punctuation instead of a mismatched quote.

- `--profile=<profile_name>` to list backups from an external storage configured as a profile"

docs/reference/pbm-commands.md:899

• The markdown admonition syntax is incorrect. It should be ??? example "Output" (note the closing quote) instead of ??? example "Output: (missing closing quote and has an extra colon). The opening quote mark is present but there's no closing quote, and the colon should be inside the quoted string or removed entirely.

??? example "Output:

docs/reference/pbm-commands.md:934

• The flag description contains the same incorrect formatting as seen in line 479. The text Selects the storage to 'query: main' is malformed and confusing. It should be rewritten for clarity, such as: Selects the storage to query: 'main' for the main storage, or '<profile_name>' for an external storage profile. or simply match the clearer description pattern used elsewhere in the documentation.

| `--profile`| Selects the storage to `query: main` for the main storage, or `<profile_name>` for an external storage profile. If omitted, the default storage is used. |

docs/reference/pbm-commands.md:469

• The example output shows a typo: cno should be no in the SELECTIVE column. The pattern shows no for other entries, and cno appears to be a typo.

    2024-10-11T12:00:00Z   physical   s3-west     cno        no    2024-10-11T12:01:00Z

docs/reference/pbm-commands.md:900

• The code block is marked as bash but contains output text rather than bash commands. For consistency and accuracy, consider using just three backticks without a language identifier, or use text or console to indicate this is command output rather than executable bash code.

    ```bash

docs/reference/pbm-commands.md:479

• The flag description contains incorrect formatting. The text Selects the storage to 'query: main' appears to be malformed. It should likely read something like Selects the storage to query: 'main' or more clearly describe that you use --profile=main for the main storage. The current syntax with backticks around "query: main" is confusing and grammatically incorrect.

| `--profile`         | Selects the storage to `query: main` for the main storage, or `<profile_name>` for an external storage profile. If omitted, the default storage is used.                              |

docs/features/multi-storage.md:80

• Grammar issue: "Default and the empty string ("")" should be "The default and the empty string ("")" or "Default values and the empty string ("")". The current phrasing is grammatically incorrect as "Default" without an article or more context is incomplete.

- Default and the **empty string ("")** must not be used as profile names.

docs/features/multi-storage.md:78

• The two bullet points about main being reserved should be combined into a single bullet point for better readability. Currently, line 77 states "main is a reserved CLI keyword" and line 78 states "Do not create a configuration profile named main" - these are closely related and would be clearer as a single statement, such as: "main is a reserved CLI keyword that always refers to the main storage. Do not create a configuration profile named main, because it cannot be referenced reliably via --profile."

- `main` is a reserved CLI keyword that always refers to the **main storage**.
- Do not create a configuration profile named `main`, because it cannot be referenced reliably via `--profile`.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (8)

docs/reference/pbm-commands.md:456

• There’s an extra trailing quote at the end of the bullet (after “profile”). This renders as a stray character in the docs and should be removed.

- `--profile=<profile_name>` to list backups from an external storage configured as a profile"

docs/reference/pbm-commands.md:469

• The sample output shows cno in the SELECTIVE column, which looks like a typo (likely should be no). This could confuse users about valid values.

    2024-10-11T12:00:00Z   physical   s3-west     cno        no    2024-10-11T12:01:00Z

docs/reference/pbm-commands.md:479

• The --profile flag description contains the phrase “query: main”, which reads like a formatting/wording mistake and is hard to understand. Consider rephrasing to clearly state that --profile=main selects the main storage and --profile=<profile_name> selects an external profile.

| `--profile`         | Selects the storage to `query: main` for the main storage, or `<profile_name>` for an external storage profile. If omitted, the default storage is used.                              |

docs/reference/pbm-commands.md:877

• The updated pbm status summary now describes listing backups “in a tabular format”, but pbm status reports overall PBM/cluster status (agents, running ops, PITR, etc.). This intro is misleading; it should describe the broader status output rather than focusing on backup tables.

Shows the status of backups and their states in a tabular format, making backup information easier to read and scan.

The output provides the following information:

docs/features/multi-storage.md:71

• The code block under the ??? example admonition is indented with tabs. MkDocs Material admonitions typically require consistent 4-space indentation; tabs can cause the code block to render outside the admonition or break formatting.

??? example "Examples"
	```bash
	# List backups from main storage
	pbm list --profile=main

	# List backups from an external storage profile
	pbm list --profile=minio

	# Show status using an external storage profile
	pbm status --profile=minio

	# Write a backup to an external storage profile
	pbm backup -t physical --profile=minio --wait
	```

docs/features/multi-storage.md:106

• The YAML example uses tab indentation (e.g., before endpointUrl, bucket, and credentials). Tabs are not valid for YAML indentation and will make the example fail if copied; replace tabs with spaces and ensure consistent nesting under s3: and credentials:.

```yaml title="minio.yaml"
storage:
  type: s3
  s3:
	endpointUrl: "http://localhost:9000"
	bucket: mybucket
	region: my-region
	credentials:
		access_key_id: myaccesskey
		secret_access_key: mysecretkey
	

docs/reference/pbm-commands.md:935

• Two issues with the newly added --profile row: (1) the description contains the confusing “query: main” wording (likely a typo/formatting mistake), and (2) the table cell is missing a space before the second | (it’s | --profile| ...), which makes the Markdown table inconsistent with the surrounding rows.

| `--profile`| Selects the storage to `query: main` for the main storage, or `<profile_name>` for an external storage profile. If omitted, the default storage is used. |
| `-o`, `--out=text`     | Shows the status as either plain text or a JSON object. Supported values: `text`, `json` |

docs/reference/pbm-commands.md:888

• In this sentence, --profile should be wrapped in backticks for consistent CLI flag formatting (as done elsewhere in the docs).

If multiple storages are configured, you can query status information for a specific storage using the --profile flag:

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[jcechace]

(typically the main storage)

This is not exactly correct.

pbm backup will use main
pbm delte-backup <name> will look at all backups
pbm delte-backup --older-than=<ts> will use main
pbm cleanup will user main
pbm list will list all backups
pbm status will list all backups

so 3.5/5

[rasika-chivate]

Fixed.

[jcechace]

You cannot actually do that in 2.13.0, pbm profile add "main" will be rejected with error.

[rasika-chivate]

Fixed

[jcechace]

What does "Default" mean here?. Same as with "main", cli will also reject empty string ("") as profile name.

Imho this item can be removed or just use something like

"PBM CLI will reject empty string ("") and "main" as profile names"

[rasika-chivate]

Ok.