this post was submitted on 27 Mar 2025
994 points (90.7% liked)
linuxmemes
24143 readers
1635 users here now
Hint: :q!
Sister communities:
Community rules (click to expand)
1. Follow the site-wide rules
- Instance-wide TOS: https://legal.lemmy.world/tos/
- Lemmy code of conduct: https://join-lemmy.org/docs/code_of_conduct.html
2. Be civil
- Understand the difference between a joke and an insult.
- Do not harrass or attack users for any reason. This includes using blanket terms, like "every user of thing".
- Don't get baited into back-and-forth insults. We are not animals.
- Leave remarks of "peasantry" to the PCMR community. If you dislike an OS/service/application, attack the thing you dislike, not the individuals who use it. Some people may not have a choice.
- Bigotry will not be tolerated.
3. Post Linux-related content
- Including Unix and BSD.
- Non-Linux content is acceptable as long as it makes a reference to Linux. For example, the poorly made mockery of
sudoin Windows. - No porn, no politics, no trolling or ragebaiting.
4. No recent reposts
- Everybody uses Arch btw, can't quit Vim, <loves/tolerates/hates> systemd, and wants to interject for a moment. You can stop now.
5. π¬π§ Language/ΡΠ·ΡΠΊ/Sprache
- This is primarily an English-speaking community. π¬π§π¦πΊπΊπΈ
- Comments written in other languages are allowed.
- The substance of a post should be comprehensible for people who only speak English.
- Titles and post bodies written in other languages will be allowed, but only as long as the above rule is observed.
6. (NEW!) Regarding public figures
We all have our opinions, and certain public figures can be divisive. Keep in mind that this is a community for memes and light-hearted fun, not for airing grievances or leveling accusations. - Keep discussions polite and free of disparagement.
- We are never in possession of all of the facts. Defamatory comments will not be tolerated.
- Discussions that get too heated will be locked and offending comments removed. Β
Please report posts and comments that break these rules!
Important: never execute code or follow advice that you don't understand or can't verify, especially here. The word of the day is credibility. This is a meme community -- even the most helpful comments might just be shitposts that can damage your system. Be aware, be smart, don't remove France.
founded 2 years ago
MODERATORS
you are viewing a single comment's thread
view the rest of the comments
view the rest of the comments
Noooo, you cannot have a consistent UI/UX experience across platforms with decades old commands and tools, my imaginary grandma might get confused, also you need three IT degrees to type "man command" into a term window.
Tbf, most man files are not easy to understand. Between man, tldr, ArchWiki, and an occasional O'Reilly book I can usually get things done, but documentation on Linux still has a lot of room for improvement.
Other than stuff like
ffmpeg- which has so many features that a man page just can't cut it; andsed- which doesn't have a simple hyperlink saying "you go here to learn sed regexp", most man pages do what I need them to do.You just need to learn the basics of how the man page is organised and what the brackets in the SYNOPSIS section mean and that makes using them much easier.
We also have
man manfor that purpose.I don't think you get what I mean.
I don't mean that man itself isn't functional, I mean the way most man pages are written isn't clear enough to communicate how to use the programs they refer to.
I'd include the man page for man in that, and I'd encourage anyone else to look at it from the eyes of someone who can follow written instructions and ask "How does this manual/help file compare to others I have read?".
So, for example, in the examples, it says:
man -a intro Display, in succession, all of the available intro manual pages contained within the manual. It is possible to quit between successive displays or skip any of them.
Those two lines are the only place within man's man page (at least the one you get from man man) that use the string "intro". What is an intro in this context? Guess you got to run it to find out.
What is -a for? About 200+ lines down there is a two sentence explanation.
The first sentence tells you how man normally behaves, saying: "By default, man will exit after displaying the most suitable manual page it finds." This sentence is unclear ("When does man exit after displaying the most suitable manual page it finds? When I run man ls I see the manual for ls on my screen until I press 'q' to 'quit' out of it.") and not immediately connected to the purpose of the flag/option.
The second sentence says: "Using this option forces man to display all the manual pages with names that match the search criteria." This is a lot clearer, and my only complaint about it can be that it's not the first sentence in the explanation.
Yeah, one big problem of
manI found was the severe lack of explanation of what the command is mainly intended to do. It's as if the user is expected to run themanafter knowing what purpose a specific program exists for, which, I guess is what it is intended for. I tend to rely on the package manager's information and other similar sources for that information andmanmainly for determining the exact usage.I don't at all expect
manto be useful for someone who can just follow written instructions.The reason being than
manis just supposed to tell the user, what typy stuff needs to be done for specific functionality. And most programs tend to be doing some small thingy and not fulfilling the user's whole requirement in one go.Meaning, to be happy with just
man, one needs to be able to create a solution for themselves by properly fitting little parts and that is already more than half way to being able to do programming.Your
man -a introexample and what followed, made me more confused than before of what you were trying to say, so I am just trying to go with the feel of it for now....
Maybe knowing that you can use
/and then whatever string of text to find something in the man page (because it useslessto paginate the output) would be useful for some of what you said. So you can do/-aand press Enter to start searching for "-a". And the reason for it being so far is because it is in the "OPTIONS" section.I now feel like someone who reads a lot of legal documents would be fine with
manpages. Was this format made by someone in that field?Yeah I'm okay with the basic navigation options. The primary point is that man pages do look like they had written by someone who does not do technical writing. Whether that's someone coming from a law background, programming, or whatever.
It's not written for an end user who wants to know how to use the tools they have available. It will tell you what a command "does", sometimes, but it doesn't explain itself. It presumes a certain amount of pre-existing knowledge, or familiarity with the syntax of man writers.
For another example, the man for ls repeatedly lists options referencing "implied" entries without ever explaining what "implied" means in this context. It presupposes that the reader knows what that term means. I know what an implication is in an English class, and the antonym for "implied" is "explicit", but in a man page? No clue. Not like there's reference to or examples of "explicit" entries to contrast with "implied" entries. You just have to know what it means in context, or figure it out some other way.