Feature/man pages

[bcdxn]

This PR adds man page (roff/troff) documentation generation to the codebase.

A new template at gen/templates/man.tmpl produces properly formatted .1 section man pages from an OCS spec, including sections for NAME, SYNOPSIS, DESCRIPTION, GLOBAL OPTIONS, COMMANDS, EXIT STATUS, and EXAMPLES.

The core transformation logic lives in gen/docs_man.go, which provides a roffEscape() function that converts Markdown content into valid roff macros. Special roff characters like backslashes and dots are escaped to prevent rendering issues.

Man page output is wired into the existing ocli CLI via a new --format man option.

[Copilot]

Pull request overview

Adds man-page (roff/troff) documentation generation to the gen package alongside existing Markdown/HTML outputs, and updates golden testdata/examples to reflect the new output and flag defaults.

Changes:

• Introduces MAN as a supported DocFormat and implements genDocsMan using a new roff template (gen/templates/man/man.tmpl).
• Refactors existing documentation generators into dedicated files (docs_md.go, docs_html.go) and updates tests to include a golden man-page comparison.
• Updates generated testdata and example specs to include a default value for --status, and adds a golden petstore-cli.man.

Reviewed changes

Copilot reviewed 12 out of 15 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
spec/types.go	Adds String() method for CommandKind.
gen/docs.go	Refactors docs dispatch and wires in ManPage generation.
gen/docs_test.go	Adds golden-file test coverage for man-page output.
gen/docs_md.go	Moves Markdown docs generator into its own file.
gen/docs_html.go	Moves HTML docs generator into its own file.
gen/docs_man.go	Adds man-page generator + roffEscape() + example collection helper.
gen/templates/man/man.tmpl	New roff template for .1 man pages.
gen/testdata/petstore-cli.man	New golden man-page output for petstore example.
gen/testdata/petstore-cli.md	Updates golden Markdown to include default:available for --status.
gen/testdata/cobra/gencli/cmd_petstore_pet_add.gen.go	Updates generated Cobra command to default --status to available.
gen/testdata/urfavecli/gencli/cmd_petstore_pet_add.gen.go	Updates generated urfave/cli command to default --status to available.
gen/testdata/yargs/gencli/cmd-petstore-pet-add.ts	Updates generated yargs command to default --status to available.
examples/petstore-cli.ocs.yaml	Adds default: "available" for --status in the example spec.
codec/testdata/expected.yaml	Updates expected codec output to include the default field.
examples/tea.ocs.yaml	Adds a large example spec (used for demos/fixtures).

Files not reviewed (2)

• gen/testdata/cobra/gencli/cmd_petstore_pet_add.gen.go: Generated file
• gen/testdata/urfavecli/gencli/cmd_petstore_pet_add.gen.go: Generated file

---

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