A Rant about lack of man pages on Linux
last updated June 21, 2005
I started using UNIX back in 1987 or so, on SunOS 3 or 4 on 68000 based machines. I was 17 or 18 years old, and knew quite a bit about DOS, and programming in Turbo Pascal, but hardly anything about UNIX.
One of the things I remember was poking around in /usr/bin, /bin, /usr/sbin /etc, and seeing all sorts of unfamiliar, cryptically named commands which offered tantalizing hints about what they might do. Sometimes I could guess what the commands would do, other times my guesses were way off. Who knew that "biff" had anything to do with email, just from looking at the name?
The first thing I was shown was the "man" command. For any command you stumbled upon in the /bin, /usr/bin, /etc directories, you could pretty much count on the "man" command being able to tell you a little something abput that command, often all you needed to know. The man always knew. I don't recall the man stumbling often, like this:
[scameron@zuul] man adddebug No manual entry for adddebugNow, the man stumbles nearly all the time, except for well established old-timey UNIX commands. I wrote a little script to find a list of commands for which there is no corresponding man page. Here is the script: find_missing_man_pages
And here is the list of commands for which there is no man page on Redhat Enterprise Linux AS release 4.
[ aclocal aclocal-1.4 aclocal-1.5 aclocal-1.6 aclocal-1.7 aclocal-1.9 activation-client adddebug addr2name.awk align allxojpanels alsalisp annotate appletproxy ApplySnapshot apr-config apu-config ark artsbuilder artscat artsc-config artscontrol artsd artsdsp artsmessage artsplay artsrec artsshell artswrapper aserver asnparser aspell aspell-import atlantik atlantikdesigner audiofile-config audit2allow autoconf-2.13 autoheader-2.13 automake automake-1.4 automake-1.5 automake-1.6 automake-1.7 automake-1.9 autoreconf-2.13 autoscan-2.13 autoupdate-2.13 awish b2m bashbug-64 bcat bdfindex bdftobogl bdftogd bdftops berkeley_db33_svc berkeley_db41_svc berkeley_db_svc bg5ps blackjack bluepin bluez-pin bonobo-activation-run-query bonobo-slay bterm build-classpath build-classpath-directory build_docbook_index build-jar-repository build-progress.sh c++ c89 calibrate_ppa callbootd callgrind callgrind_annotate callgrind_control cancel.cups canlisp cannaping capifax capifaxrcvd catalogmanager catchsegv ccexample cddb-slave2-properties cg_annotate cheatmake checkXML chinput chkcon chkconc ch_lab ch_track ch_utt ch_wave CleanLog collateindex.pl compile_encoding composeglyphs consolehelper-gtk create-branching-keyboard create_cvsignore create_makefile create_makefiles c_rehash crfreq croco-0.6-config crxdic crxgram cscope-indexer csslint-0.6 ct ctangle cups-config-daemon cupsdconf cupsdoprint cvs2dist cvsaskpass cvsbackport cvs-clean cvslastchange cvslastlog cvsrevertlast cvsservice cweave cxxmetric cxx_to_docbook DataManager DataManagerII db1_dump185 db2_archive db2_checkpoint db2_deadlock db2_dump db2_load db2_printlog db2_recover db2_stat db33_archive db33_checkpoint db33_deadlock db33_dump db33_load db33_printlog db33_recover db33_stat db33_upgrade db33_verify db41_archive db41_checkpoint db41_deadlock db41_dump db41_load db41_printlog db41_recover db41_stat db41_upgrade db41_verify db_archive db_checkpoint db_deadlock db_dump db_dump185 dbf2pg db_load db_printlog db_recover db_stat db_upgrade dbus-glib-tool db_verify dcop dcopclient dcopfind dcopidl dcopidl2cpp dcopidlng dcopobject dcopquit dcopref dcopserver dcopserver_shutdown dcopstart debugsh decode-dimms.pl decode-edid.pl decode-vaio.pl decode-xeon.pl design_filter desktop-file-install desktop-file-validate desktop-menu-tool detect_ppa devhelp devhelp-bin diff-jars disol dltest dmalloc dns-helper docbook2txt doxygen doxytag doxywizard dp dprof2calltree dpxdic drkonqi dsirc dvd-ram-control dvd+rw-booktype dvd+rw-format dvd+rw-mediainfo dvipdft ebb ebrowse ef eggcups egroupwarewizard ellcc emacs-21.3 emacsclient emacs-nox emacs-nox-21.3 emacspeak encode_keychange eog erb etags.emacs etags.xemacs eu-elflint eu-nm eu-readelf eu-size eu-strip evolution-2.0 example_to_doc++ exif.py extend_dmalloc extensionproxy extractrc fcp feedbrowser festival_server festival_server_control festival-synthesis-driver fig2ps2tex.sh file-roller fileshareset find-jar findmissingcrystal fixkdeincludes fixmswrd.pl fixnt fixproc fixuifiles fmtest forcpp forsort freetype-config fribidi fribidi-config fringe_client fsh fshd fsview ftdump fterror fti.pl ftlint ftmemchk ftmetric ftmulti ftp-rfc ftsbit ftstring ftstrpnm fttimer ftview fwindex g++32 g++4 gataxx gcc32 gcc4 gconfigger gconf-merge-tree gcore gcov32 gcov4 gd2copypal gd2topng gdialog gdk-pixbuf-config gdk-pixbuf-query-loaders-32 gdk-pixbuf-query-loaders-64 gdlib-config gdm-binary gdmchooser gdmflexiserver gdmgreeter gdmlogin gdmphotosetup gdmthemetester gdmXnestchooser gdparttopng gdtopng genkdmconf genkey genpolusers gethostip GetSyncID gftp-gtk gftp-text ggv ghns gif2epsn gif2ps gif2rgb gif2x11 gifasm gifbg gifburst gifclip gifclrmp gifcolor gifcomb gifcompose giffiltr giffix gifflip gifhisto gifinfo gifinter gifinto gifovly gifpos gifrotat gifrsize gifspnge giftext gifwedge gkb_xmmap glade-2 glines gnect gnibbles gnobots2 gnome-accessibility-keyboard-properties gnome-at-properties gnome-audio-profiles-properties gnome-background-properties gnome-bug gnome-cd gnome-config gnome-control-center gnome-default-applications-properties gnome-default-printer gnome-desktop-item-edit gnome-display-properties gnome-doc gnome-dump-metadata gnome-font-properties gnome-font-viewer gnome-gen-mimedb gnome-im-properties gnome-im-settings-daemon gnome-keybinding-properties gnome-keyboard-layout gnome-keyboard-properties gnome-keyring-daemon gnome-keyring-manager gnomemeeting-config-tool gnome-mouse-properties gnome-moz-remote gnome-name-service gnome-nettool gnome-network-preferences gnome-open gnome-panel-screenshot gnome-pilot-make-password gnome_segv gnome-session-properties gnome-session-remove gnome-sound-properties gnome-sound-recorder gnome-system-monitor gnome-terminal gnome-theme-manager gnome-theme-thumbnailer gnome-thumbnail-font gnome-typing-monitor gnome-ui-properties gnomevfs-cat gnomevfs-copy gnomevfs-info gnomevfs-ls gnomevfs-mkdir gnomevfs-rm gnome-volume-control gnome-volume-manager gnome-volume-properties gnome-window-properties gnomine gnopernicus gnotravex gnotski goad-browser gok go-rhn.sh gpdf gpg-error gpg-error-config gpgsplit gphoto2-config gphoto2-port-config gpilotd-control-applet gpilotd-session-wrapper grep-changelog groupwarewizard gsl-config gsl-histogram gsl-randist gstack gst-complete-i386-0.8 gst-complete-x86_64 gst-complete-x86_64-0.8 gst-compprep-i386-0.8 gst-compprep-x86_64 gst-compprep-x86_64-0.8 gst-feedback-i386-0.8 gst-feedback-x86_64 gst-feedback-x86_64-0.8 gst-inspect-i386-0.8 gst-inspect-x86_64 gst-inspect-x86_64-0.8 gst-launch-i386-0.8 gst-launch-x86_64 gst-launch-x86_64-0.8 gst-md5sum-i386-0.8 gst-md5sum-x86_64 gst-md5sum-x86_64-0.8 gstreamer-properties gst-register gst-thumbnail gst-typefind-i386-0.8 gst-typefind-x86_64 gst-typefind-x86_64-0.8 gst-xmlinspect-i386-0.8 gst-xmlinspect-x86_64 gst-xmlinspect-x86_64-0.8 gst-xmllaunch-i386-0.8 gst-xmllaunch-x86_64 gst-xmllaunch-x86_64-0.8 gswitchit-plugins-capplet gsx gtali gthumb-import gtk-demo gtkdoc-fixxref gtkdocize gtkdoc-mkdb gtkdoc-mkhtml gtkdoc-mkman gtkdoc-mktmpl gtkdoc-scan gtkdoc-scangobj gtkdoc-scanobj gtk-query-immodules-2.0-32 gtk-query-immodules-2.0-64 gucharmap guile guile-config guile-snarf guile-tools h2ps hal-device-manager hal-get-property hal-set-property hidd hltest hotshot2calltree hpijs hpojip-test htdb_dump htdb_load htdbm htdb_stat HtFileType htmlview httx htt_xbe hxplay hxplay.bin iagno ical2vcal icon2gif icon-slicer ifnames-2.13 iiimf-le-tools ijs-config imagetops im-switch in.fshd InitRservTest install-brltty install-todos instmodsh ior-decode-2 ipf-mod.pl irkick isc-config.sh isdnbill isodebug ispell isql iusql jbibtex jpegorient jvmjar k3b kab2kabc kabc2mutt kaboodle kaccess kaddprinterwizard kaddressbook kalarm kalarmd kandy kandy_client kapptemplate karm kasteroids katana kate katomic kaudiocreator kbabel kbabeldict kbackgammon kban kbanner.kss kbattleship kblackbox kblankscrn.kss kblob.kss kbounce kbugbuster kbuildsycoca kcachegrind kcalc kcharselect kcheckpass kclock.kss kcminit kcmshell kcolorchooser kcoloredit kconfig_compiler kconf_update kcontrol kcontroledit kcookiejar kcron kdat kdbg kdcop kdebugdialog kde-config kded kdedoc kdeeject kdeinit kdeinit_shutdown kdeinit_wrapper kdeinstallktheme kdekillall kdelnk2desktop.py kdemangen.pl kde-menu kdepasswd kdesktop kdesktop_lock kdessh kdesu kdesud kdesu_stub kdevassistant kdevdesigner kdevelop kdevelop-htdig kdevprj2kdevelop kdf kdialog kdict kdm kdm_config kdmctl kdm_greet kdontchangethehostname kdvi kedit keditbookmarks keditfiletype kenolaba keuphoria.kss keyrand kfax kfile kfind kfiresaver.kss kfloppy kflux.kss kfmclient kfontinst kfontview kfouleggs kfountain.kss kget kghostview kgoldrunner kgpg kgrantpty kgravity.kss khc_indexbuilder khelpcenter khexedit khotkeys khotnewstuff kicker kiconedit kimage_concat kinstalltheme kio_devices_mounthelper kioexec kio_http_cache_cleaner kioslave kio_uiserver kitchensync kjobviewer kjots kjumpingcube klaptop_acpi_helper klaptop_check klauncher kleopatra klickety klines klines.kss klipper klocaldomainurifilterhelper klorenz.kss kmahjongg kmail kmail_antivir.sh kmail_clamav.sh kmailcvt kmail_fprot.sh kmail_sav.sh kmailservice kmenuedit kmid kmines kmix kmixctrl knewstickerstub knode knotes kolabwizard kolf kolourpaint kompare konqueror konquest konsole konsolekalendar kontact kooka kopete kopete_latexconvert.sh korgac korganizer korganizerIn korn kpac_dhcp_helper kpager kpalmdoc kpartsaver.kss kpat kpdf kpdic kpendulum.kss kpersonalizer kpilot kpilotDaemon kpm kpoker kpolygon.kss kppplogview kprinter krandom.kss krandrinithack krandrtray krb5 krb5-auth-dialog krdb krdc kreadconfig krec kregexpeditor kreversi krfb krfb_httpd krootimage krotation.kss kruler ksame kscd kscience.kss ksendbugmail kshell kshisen ksig ksirc ksirtet kslideshow.kss ksmiletris ksmserver ksnake ksnapshot ksolarwinds.kss kspaceduel kspace.kss ksplash kstart kstring2key ksvgtopng kswarm.kss ksync ksysguard ksysguardd ksystraycmd ktalkd ktalkdlg ktelnetservice ktest ktimer ktip ktnef ktradertest ktron ktuberling kuickshow kuiviewer kvg kview kviewshell kvm.kss kwalletmanager kwatchgnupg kwave.kss kwebdesktop kwifimanager kwikdisk kwin kwin4 kwin4proc kwin_killer_helper kwin_rules_dialog kwrapper kwrite kwriteconfig kxkb kxsconfig kxsrun lamhalt lamnodes launchmail ldrdf lessecho lesspipe.sh lha libart2-config libart-config libgcrypt-config libglade-convert libgnutls-config libgnutls-extra-config libIDL-config libIDL-config-2 libieee1284_test libpng12-config libst-config libusb-config libwmf-config libwmf-fontmap libwww-config licensecheck linc-cleanup-sockets lisa lnkforward lnusertemp loadshlib lp.cups lpq.cups lpr.cups lprm.cups lprsetup.sh lpstat.cups lpunlock lshal lskat lskatproc lspgpot lss16toppm magicdev magicfilter-t magnifier mahjongg mail-files mailsettings mailshar mailstat makedb make_driver_db_cups make_driver_db_lpr make_encmap makekdewidgets makeobj make_wagon_desc MasterAddTable MasterInit MasterSync mcheck mcmfmt mcomp mcopidl meinproc memhog memprof2calltree memusage memusagestat mergebdf mergeword metacity metacity-message metacity-theme-viewer metacity-window-demo mf-nowin mfw midisend mini-wm mkafmmap mkocp mkoctfile-2.1.57 mkofm mksmbpasswd.sh mkstub modulator money2qif mozilla-config mozilla-thunderbird mp2bug mp2doc mrmlsearch msgfmt.py msghack msql2mysql mute mxtar myisamchk myisam_ftdump myisamlog myisampack my_print_defaults mysqlbinlog mysqlbug mysqlcheck mysql_config mysql_convert_table_format mysql_create_system_tables mysqldumpslow mysql_explain_log mysql_find_rows mysql_fix_extensions mysqlhotcopy mysqlimport mysql_install_db mysqlmanager mysqlmanagerc mysqlmanager-pwgen mysql_secure_installation mysql_setpermission mysql_tableinfo mysqltest mysql_tzinfo_to_sql mysql_waitpid nabi name-client na_play na_record nautilus nautilus-cd-burner nautilus-file-management-properties nenscript net-snmp-config NetworkManager NetworkManagerDispatcher NetworkManagerInfo newslock ngram_build ngram_test nhpf NMLaunchHelper NMLoadModules noatun noatunsynaescope.bin noatuntippecanoe.bin noatuntyler.bin nspluginscan nspluginviewer numademo numastat ocs octave-2.1.57 octave-bug-2.1.57 octave-config-2.1.57 odbc_config ODBCConfig odbcinst odbctest odvicopy odvips odvitype oid2name oldrdist ols ols_test omfonts ooffice ootags op2calltree op_import oprofiled oprof_start orbit2-config orbit-config orbit-event-server orbit-idl orbit-idl-2 orbit-ird orbit-name-server orient.py ospcat otangle otp2ocp outocp over oxdvi oxdvi.bin package_crystalsvg pack_isam pam-panel-icon panel-test-applets pango-querymodules-32 pango-querymodules-64 pbmtpg pcprofiledump pcre-config pda pdftosrc pdvips pdvitype pear perl5.8.5 pg_autovacuum pgbench pg_dumplo pg_encoding pg_filedump pg_id pg_logger pgpewrap pgpring php php-config phpextdist phpize pi-csd pi-getromtoken pilot-archive pilot-clip pilot-datebook pilot-dedupe pilot-file pilot-schlep pi-nredir pitchmark pj-gs.sh planner pltcl_delmod pltcl_listmod pltcl_loadmod pm png2mng.pl pngtobogl pngtogd pngtogd2 po2xml post-grohtml poxdvi poxdvi.bin poxdvizilla ppmtolss16 pprof2calltree pr3287 pre-grohtml PrepareSnapshot preparetips protoize pruneemptydirs ps2pdf14 pspell-config pstoimg pstree.x11 ptal-connect ptal-device ptal-devid ptal-hp ptal-pml ptex pvffilter pvfnoise pv.sh pxdvi pxdvi.bin pxdvizilla pydoc pygettext.py pygtk-codegen-2.0 pylupdate pynche pyrexc python2.3 pyuic qtdoc r++ rateup raw2gif raw_to_xgraph rb rcs-checkin rdf2bin rdfdump rdflib rdoc rdx rebuild-jar-repository reduce-font reminders remsync Replicate resetall reslisa resolveip resolve_stack_dump resynth rftp rgb2gif rhgb rhgb-client rhythmbox ri rlm_dbm_cat rlm_dbm_parser rlogin-cwd rmail.postfix rmail.sendmail RservTest rssclient rssservice rsvg-view run-with-aspell rx same-gnome sasl2-sample-client sasl2-sample-server sasl-sample-client sasl-sample-server sb scfg_make scfg_parse scfg_test scfg_train screensaver-properties-capplet scrollkeeper-extract scrollkeeper-get-cl scrollkeeper-get-content-list scrollkeeper-get-extended-content-list scrollkeeper-get-index-from-docpath scrollkeeper-get-toc-from-docpath scrollkeeper-get-toc-from-id scrollkeeper-install scrollkeeper-uninstall sdl-config secpolicy seinfo sepcut sesearch seuser seuseradd seuserdel seusermod sfconvert sfinfo sgmlspl sgmlwhich showchar sig2fv sigfilter siod sip SlaveAddTable SlaveInit sloxwizard smbencrypt smbprint sol sound-juicer soxplay spax speaker-test spectgen spell sperl5.8.5 split2po srcore startkde suidperl swappo swig switchdesk-helper sx tcl tclhelp tclsh8.4 tdbtool termidx test-moniker test_ppa testrb test-speech texexpand text2gif text2wave tex_to_images tgz themus-theme-applier theora_dump_video theora_encode theora_player tiffset tilt_analysis tilt_synthesis timed-read timed-run tixindex tixwish8.1.8.4 tkpasswd tn3270d tn5250-config tn5250d tora transxx traptoemail tsiadd tsidel tsidump tsiguess tsiyincheck tsiyindump ttf2afm ttf2psm ttfprint ttindex ttmkfdir typelib-dump ucd5820stat umbrello unix-lpr.sh unprotoize update-desktop-database update-gdk-pixbuf-loaders update-gtk-immodules url_handler.sh utmpdump uulog uuname uupick uuto uxterm uz vacuumlo valgrind valgrind-listener vboxcnvt VFlib2-config vfperf vftest vino-preferences viterbi vm vncconfig.py w3c wacdump wagon wagon_test weather webbot webpng wfst_build wfst_run whiptail wish8.4 wishx wmf2eps wmf2fig wmf2gd wmf2svg wmf2x word-list-compress workman2cddb.pl x86_64-redhat-linux-c++ x86_64-redhat-linux-c++32 x86_64-redhat-linux-c++4 x86_64-redhat-linux-g++ x86_64-redhat-linux-g++32 x86_64-redhat-linux-g++4 x86_64-redhat-linux-gcc x86_64-redhat-linux-gcc32 x86_64-redhat-linux-gcc4 xchat xdelta-config xdvi.bin xdviprint xemacs-21.4.15 xemacs-nox-21.4.15 xf86gammacfg xidump ximian-connector-setup-2.0 xminicom xml2pot xml-i18n-toolize xml_parser xmlproc_parse xmlproc_val xmms-config xojpanel xpstat xpvm xql.pl xsane-gimp xscreensaver.kss xsetwacom xslt-config xsri xt5250 xtrace yelp zegrep zfgrep zipcloak zipnote zipsplit zonetab2pot.py ash.static aumix-minimal ping6 tracepath6 traceroute6 amd2ldif amd2sun am-eject anaconda apol bonobo-activation-sysconf build-locale-archive checkrad check-radiusd-config convert4r4 cpuspeed ctl-hlfsd dbconverter-2 dbskkd-cdb ddcprobe dftest diskdumpctl_proc diskdumpctl_sysfs dmidecode dns-keygen dongle_attach dovecot dump-acct dump-utmp execcap exicyclog exigrep exim_checkaccess exim_dbmbuild exim_dumpdb exim_fixdb exim_lock eximon eximon.bin exim_tidydb exinext exipick exiqgrep exiqsumm exiwhat fancontrol fancontrol.pl firstboot fix-amd-map fix-mouse-psaux fixrmtab foomatic-fix-xml foomatic-nonumericalids foomatic-printermap-to-gimp-print-xml foomatic-replaceoldprinterids gdmconfig gdm-restart gdm-safe-restart gdmsetup gdm-stop genhomedircon getpcaps glibc_post_upgrade.i686 glibc_post_upgrade.x86_64 gnome-pty-helper hald hal_lpadmin hardlink htt httpd.worker htt_server iconvconfig iconvconfig.i686 iconvconfig.x86_64 in.authd inetdconvert inputattach isdndial isdnhangup isdnstatus javaconfig kppp lchage lgroupadd lgroupdel lgroupmod libgcc_post_upgrade lid lnewusers lokkit lostaltmail lpasswd lpc.cups luseradd luserdel lusermod memtest-setup mkdict mksock modeline2fb mouseconfig netconfig nstat ntp-keygen ntp-wait openldap ospfclient packer printconf printconf-backend printconf-gui printconf-tui ptal-cups ptal-init ptal-mlcd ptal-photod ptal-printd pwmconfig racoonctl rcapid rdistd rtacct rtstat safe_finger sasl2-shared-mechlist sasl2-static-mechlist saslauthd1-checkpass seaudit seaudit-report sesh setpcaps seuserx slapadd-slapd-2.0-dbb slapadd-slapd-2.0-gdbm slapadd-slapd-2.1 slapcat-slapd-2.0-dbb slapcat-slapd-2.0-gdbm slapcat-slapd-2.1 slapd_db_archive slapd_db_checkpoint slapd_db_deadlock slapd_db_dump slapd_db_load slapd_db_printlog slapd_db_recover slapd_db_stat slapd_db_upgrade slapd_db_verify smartd-conf.py squidclient ss sucap sysreport system-cdinstall-helper system-config-boot system-config-network system-config-packages system-install-packages system-switch-im system-switch-mail testsaslauthd timeconfig try-from tux2w3c tuxstat userisdnctl utempter uuchk uuconv uusched wait4amd wait4amd2dieThat's not too cool at all.
Now some of you are probably going to say, "man pages are old and busted, info is the new hotness," or "html is the new hotness," or some other shit is the new hotness. Well, all those other things suck compared to man pages, because half of them can't be used with a text-only terminal, and none of them are standardized the way man pages are so that when they do exist you can find the damn things. All the "fixes" for man pages fix something that really wasn't broken, and in so doing, introduce their own breakage, which is worse being that that breakage typically amounts to hiding the new documentation where nobody can find it in some format you'll be lucky to be able to read 5 years from now.
That's presuming such documentation exists. For much of the stuff above, there simply is no documentation. Just like on Windows, you're left mystified and in the dark. "What does this do? What uses it? Is this a command a user is expected to run directly, or does some larger program rely on this, and it's not meant for human consumption?" I don't know. Sometimes I resort to running "strings" on a binary just to try to get some more clues. And that is a pathetic state of affairs.
Now, it's really not fair to lay all this blame on Redhat or to single them out. Afterall, they are in the business of putting together a distribution, an OS, out of a lot of pieces which they often have had no real hand in developing, and most other distributions -- since they do pretty much the same thing -- are presumably just as lacking in documentation. Redhat's just happens to be the distros with which I am most familiar.
What might be done about this? Well, one could set about writing some man pages for one or two of the above commands, provided one could figure out what the hell they did. Google would be a start in figuring that out, as would getting the source code and digging around in it.
The "man" command might be made smarter, so that for those commands which were documented in heretical formats and locations, "man" could nonetheless do some sort of translation...
What else . . . ?