Expand and improve man page documentation - #1038
Draft
Wilfred wants to merge 1 commit into
Draft
Conversation
The man page was written for 0.58 and had drifted from the actual CLI. Correctness fixes: * `--strip-cr` takes `on`/`off` (defaulting to `on` since 0.58), it is not a boolean flag. * The `\r\n` in the `--strip-cr` description was rendering as `***` in the generated roff. * The `--override` environment variable example was mangled: the unbalanced `*` in `'*.c:text'` opened emphasis that spanned lines, so the three `export` lines were run together and `*.c` lost its `*`. Shell examples are now code blocks, so globs and straight quotes survive verbatim. * `--graph-limit` describes the internal graph in terms of vertices, as `--help` does. * `--tab-width` takes `NUM_SPACES`, not `NUMSPACES`. * `--display=json` requires `DFT_UNSTABLE` to be set. * Fixed "Print the all the languages" in `--list-languages`. Freshness: * Document `--override-binary` (added in 0.65) and `--dump-syntax-dot`. * Document the default value and permitted values of every option. * Set the `.TH` manual section, so the rendered header is no longer blank. Helpfulness: * Document the environment variable for each option, plus an ENVIRONMENT section covering `DFT_OVERRIDE_1` to `DFT_OVERRIDE_9`, `DFT_OVERRIDE_BINARY_1` to `DFT_OVERRIDE_BINARY_9` and `DFT_UNSTABLE`. * Add EXIT STATUS, EXAMPLES and SEE ALSO sections. * Cover stdin, `/dev/null` and the GIT_EXTERNAL_DIFF argument forms in the synopsis and description. difft.1 was regenerated with `just man` using pandoc 3.1.13, which is the version that generated the previous difft.1. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JxMKp5Cf3frsUq4gmGoDBA
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR significantly expands the difftastic man page (difft.1) with comprehensive documentation improvements.
Summary
The man page has been substantially enhanced to provide more complete and detailed information about difftastic's usage, options, and behavior. This includes adding missing command-line syntax forms, expanding option descriptions with defaults and environment variables, and adding new sections for environment variables, exit status, and examples.
Key Changes
--override-binaryoption documentation--dump-syntax-dotoptionImplementation Details
.RS/.REblocks for option details.EX/.EEformathttps://claude.ai/code/session_01JxMKp5Cf3frsUq4gmGoDBA