docs: improve formatted output for oras discover

[FeynmanZhou]

What this PR does / why we need it:

This PR improves formatted output for oras discover. For example, if the referrers have associated referrers, ORAS should enable users to show the manifest content of the subject image and all referrers in multiple formats.

Which issue(s) this PR fixes (optional, in fixes #<issue number>(, fixes #<issue_number>, ...) format, will close the issue(s) when PR gets merged):
Fixes #1403

Please check the following list:

• Does the affected code have corresponding tests, e.g. unit test, E2E test?
• Does this change require a documentation update?
• Does this introduce breaking changes that would require an announcement or bumping the major version?
• Do all new files have an appropriate license header?

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 84.52%. Comparing base (756d60f) to head (452ec63).
Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1625   +/-   ##
=======================================
  Coverage   84.52%   84.52%           
=======================================
  Files         126      126           
  Lines        5681     5681           
=======================================
  Hits         4802     4802           
  Misses        625      625           
  Partials      254      254           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[FeynmanZhou]

Based on the community discussion on Feb 18, @oras-project/oras-cli ORAS maintainers agreed on these things:

• Show root image and its all referrers in the JSON output by default. This ensures data consistency among other data format output (e.g. tree, table)
• Use referrers as the field name in the top-level and second-level referrers, instead of manifests
• Show the referrers with full depth by default, introduce a flag --depth to allow users to limit the maximum depth of referrers in the formatted output.
• Use JSON Schema and text to list the fields in formatted output

[Copilot]

PR Overview

This PR enhances the documentation for the formatted output of the oras discover command, aiming to clearly present both the subject image and its associated referrers' manifests in tree view and JSON output formats.

• Clarifies the description of the referrers' manifest output.
• Adds examples for recursive tree view and pretty JSON output.
• Updates field descriptions in the formatted output documentation.

Reviewed Changes

File	Description
docs/proposals/formatted-output.md	Updates and additions to improve clarity and formatting for oras discover output

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

[Copilot]

PR Overview

This PR improves the formatted output for oras discover by updating field names and adding recursive output examples and a new depth flag.

• Renames the "manifests" field to "referrers" for consistency.
• Adds detailed examples for JSON, tree, and table outputs with recursive referrers.
• Introduces the --depth flag to control the recursion depth of referrers.

Reviewed Changes

File	Description
docs/proposals/formatted-output.md	Updates documentation to improve output format examples and details

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

[wangxiaoxuan273]

Based on the community discussion on Feb 18, @oras-project/oras-cli ORAS maintainers agreed on these things:

• Show root image and its all referrers in the JSON output by default. This ensures data consistency among other data format output (e.g. tree, table)
• Use referrers as the field name in the top-level and second-level referrers, instead of manifests
• Show the referrers with full depth by default, introduce a flag --depth to allow users to limit the maximum depth of referrers in the formatted output.
• Use JSON Schema and text to list the fields in formatted output

Based on the offline discussion on March 7, the following conclusions have been reached:

• Table view of oras discover will be deprecated.
• Timeout will not be introduced as we don't see valid scenarios for it.

[wangxiaoxuan273]

LGTM

[TerryHowe]

The current unresolved comments should be addressed, but generally looks good

[Wwwsylvia]

LGTM with nit

[TerryHowe]

/lgtm

[Wwwsylvia]

LGTM

[shizhMSFT]

LGTM

[FeynmanZhou]

Hi @oras-project/oras-cli , I've rebased the branch. Now it should be ready to merge. Thanks.

[Wwwsylvia]

LGTM