Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Harmonize usage documentation #387

Closed
wants to merge 5 commits into from
Closed

Harmonize usage documentation #387

wants to merge 5 commits into from

Conversation

mattias-p
Copy link
Member

@mattias-p mattias-p commented Oct 17, 2024 •
edited
Loading

Purpose

This PR makes man zonemaster-cli and zonemaster-cli --help be generated from the same source, ensuring they stay in sync.

The user documentation is greatly improved with regard to navigation, but very little is done to what you find when you get to the correct place. E.g. there are many cases of outdated facts and unclear language. I intend to make a follow-up PR making improvements in there areas.

Context

Fixes #68. While this PR does not follow the issue to the letter, it does abide to it in spirit. The --help show a brief summary of the man page, not the full man page.

Changes

Application:

  • MooseX::Getopt is replaced with Getopt::Long and Pod::Usage.

Tests:

  • A unit test is added to make sure --help work.
  • A unit test is added to make sure all POD is syntactically correct.

Documentation:

  • The --help output is now a brief summary of the full man page.
  • Options are grouped into logical categories, making it much easier to navigate the options documentation.
  • Options whose defaults were declared in the man page now also show their defaults in the --help text.
  • Underscore aliases are moved to their own category and removed from the --help text.
  • Deprecated options are moved to their own category and removed from the --help text.
  • The synopsis section no longer doubles as an examples section. The old examples are moved to their own examples section.

How to test this PR

  • Unit tests should pass.
  • Visually inspect the help text and man page of both this branch and the develop branch looking for regressions.
  • Manually explore some edge cases like missing required arguments, unknown options, invalid arguments, or conflicting flags.

@mattias-p
Group options in categories
5e88430
@mattias-p
Update option headings
788e118 
* Add formatting
* Make option arguments more consistent
* Group twin options into the same entry
* Demote underscore aliases to a section at the end
@mattias-p
Prepare POD for --help generation
853381f 
* Move examples from SYNOPSIS to new EXAMPLES section.
* Add proper synopsis (with limited view for --help).
* Edit option descriptions to make the first paragraph to be a concise
  summary with a stated default (where available in the old version).
* Mark following paragraphs to only be included in the man page.
@mattias-p
Replace MooseX::Getopt::GLD with Getopt::Long
81e70ad
@mattias-p
Ensure syntactical correctness in POD
9c995eb
@mattias-p mattias-p marked this pull request as ready for review October 17, 2024 14:56
@mattias-p mattias-p closed this Oct 18, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@matsduf matsduf Awaiting requested review from matsduf

@tolvmannen tolvmannen Awaiting requested review from tolvmannen

@tgreenx tgreenx Awaiting requested review from tgreenx

@marc-vanderwal marc-vanderwal Awaiting requested review from marc-vanderwal

@MichaelTimbert MichaelTimbert Awaiting requested review from MichaelTimbert

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
1 participant
@mattias-p