-
Notifications
You must be signed in to change notification settings - Fork 2.9k
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.
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
man(1) clarify searching + minor nits #1438
base: main
Are you sure you want to change the base?
Conversation
7464aa7
to
5f1b617
Compare
I think these changes should be sensible and non-controversial, but perhaps controversially I'd love to:
|
6eba44e
to
78e96d0
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looks great! I love these incremental improvements. I wrote a few tiny nitpicks but for the most part I think this looks splendid.
This PR works on my machine and the build failures appear to be due to the build system being throttled, not a syntax error.
echo ' [-m arch[:machine]] [-p [eprtv]] [mansect] page [...]' | ||
echo ' man -f page [...] -- Emulates whatis(1)' | ||
echo ' man -k page [...] -- Emulates apropos(1)' | ||
echo ' man -K | -f | -k expression [...] -- Search manual pages' |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is there any chance 'expression' is confusing and should be 'regexp' ? either are better than 'page', that's for sure.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I agree that regexp is less ambiguous for people new to unix, but the term expression is elegant and used in all the rest of the manual manuals like apropos. Also, man -k expression
does show re_format(7) - POSIX 1003.2 regular expressions
.
Thanks for the review! I worked egrep back into -K description. |
People are often stunned by robust manual search functionality on the community discord, so attempt to tidy doc regarding search by: + consolidate and standardize search options in synopsis and usage + call regular expressions `expression` like other manual pages + explain what search related flags do instead of using similies + crossreference the regular expression manual instead of egrep(1) While here, polish and wax: + use consistent spacing and form (Ql) for quoted literals + clean a few linter errors regarding self xref and nospace + tidy examples + align files + tag spdx Notes on currently outstanding issues: - man.1 example 3 is confusing, and shows no results on my boxen - logic preventing -Kk from being used together isn't working MFC after: 3 days
this may need other changes, but can we not change whitespace on the man pages. |
Attempt to clarify search while maintaining terseness. Inspired by conversations on community discord!
Unresolved:
man -Kk
, seems to start around line 600) is not working on CURRENT. I tried playing with it but I don't understand it enough yet.Cc @tetlowgm