Are MAN pages made deliberately difficult to read?
Linux - NewbieThis Linux forum is for members that are new to Linux.
Just starting out and have a question?
If it is not in the man pages or the how-to's this is the place!
Welcome to LinuxQuestions.org, a friendly and active Linux Community.
You are currently viewing LQ as a guest. By joining our community you will have the ability to post topics, receive our newsletter, use the advanced search, subscribe to threads and access many other special features. Registration is quick, simple and absolutely free. Join our community today!
Note that registered members see fewer ads, and ContentLink is completely disabled once you log in.
If you have any problems with the registration process or your account login, please contact us. If you need to reset your password, click here.
Having a problem logging in? Please visit this page to clear all LQ-related cookies.
Introduction to Linux - A Hands on Guide
This guide was created as an overview of the Linux Operating System, geared toward new users as an exploration tour and getting started guide, with exercises at the end of each chapter.
For more advanced trainees it can be a desktop reference, and a collection of the base knowledge needed to proceed with system and network administration. This book contains many real life examples derived from the author's experience as a Linux system and network administrator, trainer and consultant. They hope these examples will help you to get a better understanding of the Linux system and that you feel encouraged to try out things on your own.
Click Here to receive this Complete Guide absolutely free.
Are MAN pages made deliberately difficult to read?
Why are the man pages so complex?
I know they sometimes list some pretty complex things, but sometimes after reading a Ďmaní page I think that the programmer has deliberately tried to make something sound more complex than it actually is.
I donít want to start a flame war, but surely this must hold Linux back in some way.
man pages are traditionally brief. Their purpose in life is to serve as a refresher for the experienced user, rather than as a walk-through or tutorial for the new user. Those purposes are better served with info, or the hTML folders in docs...or...
I wrote a full article on Linux documentation here
I knew it would come in handy some day!
And please, it's a rough spot with me: nothing, anywhere, is deliberately made more complicated than absolutely necessary. Computers are difficult to start with, and every developer works themselves the hardest trying to ensure that their work is as simple to understand as possible. It's just that man pages are often written by the programmer, and programmers aren't always good at explaining things in plain talk.
I don't think they are deliberately hard. As with most documentation, there is a choice to be made, between writing for the newcomer to the topic and writing for the person who understands the context and intentions of the software but wants to find some of the specific detail. Man pages are often written more from the second perspective than the first. In my experience, even highly experienced users refer to man pages from time to time to get information about features they haven't used for a while, maybe never. If man pages were always written for the novice as a tutorial, then someone would be complaining about always having to wade through boring introductory stuff to get to the meat.
Hypertext provides a partial answer to this dilemma, since it lets you jump past the stuff you don't want to see. Man pages are anachronistic now but many people still feel some pressure to write at least a basic man page for their software because, historically, man pages have been one of the best-known places to start looking for help. GNU info format has provided a sort of hypertext, but the world is probably still waiting for a better format for this kind of thing, that makes it fairly straightforward to write clear documentation without turning it into a spider's web of cross-links.
At LCA in Dunedin (NZ) a few weeks back I had the opportunity to have a chat with the manpage maintainer.
Nice fella, but he (and the folks that help him) have more work than they can handle keeping the man pages up to date.
I'm sure he would appreciate your updates for any pages your think are remiss.
Maybe try him at <michael dot kerrisk at gmx dot net>
i am in the process of saving manpages out to text files and putting on my webpage whereby people can make .PDFs from them and print them, whilst it doesnt help the content, things are generally easier to read and digest from a book or other source whilst working on the problem.
That being said , like mentioned, man pages are not tutorials, they are refreshers for command options etc.
There are ways of viewing manpages that are easier to read then the straight text version.
First, you can view them in the konqueror web browser. Enter "man:<topic>" in the address bar.
Another way is to produce a postscript version of a manpage: man -t <topic> >topic.ps
or to view it directly, man -t <topic> | kghostview -
Your distro's help system may have a version of the manpages also.
For info pages, nothing beats producing a printable document from the .texi or .sgml source. For that you need to install the source tarball or rpm or deb. Often, there will be Makefile targets for postscript, dvi and pdf documents.
These manuals can sometimes be 3 or 4 hundred pages in length, and are more like books than help pages.
There info manual for gawk ( 352 pages )- "gawk-Effective Awk Programming" is excellent. The one for find, "Finding Files" is also very good and a good companion to the one for tar. A must print, is the Coreutils. The lions share of the programs in /bin are covered, as well as explaining the permission system.
I think all new users of Linux think the same. At least I was one of this, so I understand the OP.
But manpage try to be short, they don't give you all scenarios as it would narrow the enormous possibilities of some tools. It would be too hard to maintain/translate and too big for small harddisks. Some difficult ones have examples section. You can also get some information from /usr/share/doc/* or by googling with appropriate terms.
When time passes, you will find them very usefull. Important tip: to search in a manpage, hit / and the term you want to search. Then enter. Then n and p for next/previous. q to quit, not control C
programmers aren't always good at explaining things in plain talk.
And with that statement sir, you are qualified for understatement of the year!
On a serious note, I do think that this is what the problem is. Everyone has there strengths and weaknesses, and sometimes it seems like the two correspond. Most people that I know that can do something very well can't really explain it. This goes for more things than programing too. It seems that the people who are REALLY good at something "just get it" and can't really explain it someone. As another example, I can fix cars if taught how to do it, but when I tried to get my Dad to teach me, he responds with "just go and start fixing it". No one taught him, he just seems to "get it". I think it's the same thing with programmers and computers. I can poke at something and figure out how to work it, and explain it to other people, but I'm a lousy programmer, I just don't think that way, and I think it's the same thing for people who program, it makes sense to them, so they lay the documentation out in that way... and thus make it almost completely useless for the newbies.
I totally agree with benjeeqds, I know that it's hard to mantain and update such a huge amount of info and help, and I'm sure that everyone here appreciates that, but, sometimes it's quite frustrating trying to understand any explanation in a man page. ah!, and.. yes... I think that is holding linux back a bit.
Being also a programmer, I found MSDN pretty irritating: it gives you a lot of scenarios but I always wanted one that was not mention and sometimes its impossible to figure out how to do it without googling.
Linux is getting better all of the time. The process of learning new things, unlearning old things, and mixing the old and the new stuff is hard. It would be great if there was a one-click-conversion, but thats what happens when everything changes.
Hopefully if FOSS becomes more poular changes will be less difficult as the process of change becomes more organic. No one will have a vested interest in holding technology in one place, software free to move, change and be adapted as needed.