LinuxQuestions.org
Download your favorite Linux distribution at LQ ISO.
Go Back   LinuxQuestions.org > Forums > Linux Forums > Linux - Newbie
User Name
Password
Linux - Newbie This 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!

Notices


Reply
  Search this Thread
Old 03-01-2006, 04:33 AM   #1
benjeeqds
LQ Newbie
 
Registered: Mar 2006
Posts: 5

Rep: Reputation: 0
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.

Does anybody else agree?
 
Old 03-01-2006, 04:43 AM   #2
Hosiah
Member
 
Registered: Sep 2004
Location: Des Moines, Iowa
Distribution: Slackware, Mandriva, Debian derivatives, +BSD/ Solaris/ Minix/ plan9/ GNU/HURD...
Posts: 185

Rep: Reputation: 30
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.
 
Old 03-01-2006, 04:48 AM   #3
heema
Senior Member
 
Registered: Sep 2003
Location: Egypt
Distribution: Arch
Posts: 1,528

Rep: Reputation: 47
you could look at the info pages instead
 
Old 03-01-2006, 04:57 AM   #4
Dr_P_Ross
Member
 
Registered: Nov 2003
Location: Edinburgh, UK
Distribution: Arch
Posts: 43

Rep: Reputation: 18
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.
 
Old 03-01-2006, 04:58 AM   #5
syg00
LQ Veteran
 
Registered: Aug 2003
Location: Australia
Distribution: Lots ...
Posts: 15,715

Rep: Reputation: 2120Reputation: 2120Reputation: 2120Reputation: 2120Reputation: 2120Reputation: 2120Reputation: 2120Reputation: 2120Reputation: 2120Reputation: 2120Reputation: 2120
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>
 
Old 03-01-2006, 05:05 AM   #6
ethics
Senior Member
 
Registered: Apr 2005
Location: London
Distribution: Arch - Latest
Posts: 1,522

Rep: Reputation: 45
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.
 
Old 03-01-2006, 05:50 AM   #7
jschiwal
LQ Guru
 
Registered: Aug 2001
Location: Fargo, ND
Distribution: SuSE AMD64
Posts: 15,733

Rep: Reputation: 671Reputation: 671Reputation: 671Reputation: 671Reputation: 671Reputation: 671
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.
 
Old 03-01-2006, 05:58 AM   #8
ethics
Senior Member
 
Registered: Apr 2005
Location: London
Distribution: Arch - Latest
Posts: 1,522

Rep: Reputation: 45
to put a man page to a text file you can do
Code:
man <command> | col -b > <filename>.txt
 
Old 03-01-2006, 06:18 AM   #9
nx5000
Senior Member
 
Registered: Sep 2005
Location: Out
Posts: 3,307

Rep: Reputation: 55
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
good luck

Last edited by nx5000; 03-01-2006 at 06:20 AM.
 
Old 03-01-2006, 07:10 AM   #10
pixellany
LQ Veteran
 
Registered: Nov 2005
Location: Annapolis, MD
Distribution: Arch/XFCE
Posts: 17,802

Rep: Reputation: 738Reputation: 738Reputation: 738Reputation: 738Reputation: 738Reputation: 738Reputation: 738
Quote:
Originally Posted by benjeeqds
I donít want to start a flame war, but surely this must hold Linux back in some way.

Does anybody else agree?
As several have said, they are for reference only. There are abundant tutorials out there for learning--although you certaily CAN learn by man pages plus good old-fashined cut and try.

Is this "holding Linux back"? No
 
Old 03-01-2006, 07:23 AM   #11
Yoda47
Member
 
Registered: Jan 2006
Location: MI, USA
Distribution: Open SUSE Tumbleweed / Fedora 25
Posts: 46

Rep: Reputation: 15
Quote:
Originally Posted by Hosiah
...
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.
 
Old 03-01-2006, 07:28 AM   #12
fabman
LQ Newbie
 
Registered: Jul 2004
Posts: 1

Rep: Reputation: 0
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.
 
Old 03-01-2006, 07:47 AM   #13
ethics
Senior Member
 
Registered: Apr 2005
Location: London
Distribution: Arch - Latest
Posts: 1,522

Rep: Reputation: 45
I don't think it's holding Linux back, it's hard enough getting people to read the man pages, or even google, letalone worrying if they'll understand it
 
Old 03-01-2006, 08:07 AM   #14
nx5000
Senior Member
 
Registered: Sep 2005
Location: Out
Posts: 3,307

Rep: Reputation: 55
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.
 
Old 03-01-2006, 08:10 AM   #15
jerril
Member
 
Registered: Nov 2005
Location: Ontario, Canada
Distribution: Ubuntu
Posts: 114

Rep: Reputation: 15
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.

jer
 
  


Reply


Thread Tools Search this Thread
Search this Thread:

Advanced Search

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is Off
HTML code is Off



Similar Threads
Thread Thread Starter Forum Replies Last Post
who - man pages kshkid Programming 17 03-01-2006 02:37 AM
C man pages sono2 Programming 4 09-12-2005 01:24 AM
C man pages sono2 Linux - Software 2 09-09-2005 12:24 PM
C man pages sono2 Linux - General 1 09-09-2005 10:36 AM
ATi linux made difficult for debian shorty_boy Debian 21 09-09-2004 01:58 PM

LinuxQuestions.org > Forums > Linux Forums > Linux - Newbie

All times are GMT -5. The time now is 07:50 PM.

Main Menu
Advertisement
My LQ
Write for LQ
LinuxQuestions.org is looking for people interested in writing Editorials, Articles, Reviews, and more. If you'd like to contribute content, let us know.
Main Menu
Syndicate
RSS1  Latest Threads
RSS1  LQ News
Twitter: @linuxquestions
Facebook: linuxquestions Google+: linuxquestions
Open Source Consulting | Domain Registration