Linux: Man Page Obsolete by --help

Linux: Man Page Obsolete by --help

these days, man page is getting the sack. Instead, the embedded inline doc --help option is emphasized. Often, the info from --help is more complete than man page. Many programs don't even bother to write a man page, but the Linux distributor such as Debian, writes one for them, pro forma.

For example, i wanted to know what's the --minimal option do in xfce4-display-settings. So, i man xfce4-display-settings. The output doesn't mention it.

XFCE4-DISPLAY-SETTINGS(1)                 User Commands                 XFCE4-DISPLAY-SETTINGS(1)

NAME
       xfce4-display-settings - Display settings for Xfce

DESCRIPTION
   Usage:
              xfce4-display-settings [OPTION...]

   Help Options:
       -?, --help
              Show help options

       --help-all
              Show all help options

       --help-gtk
              Show GTK+ Options

   Application Options:
       -v, --version
              Version information

       --display=DISPLAY
              X display to use

COPYRIGHT
       Copyright © 2004-2008
               The Xfce development team. All rights reserved.

       Please report bugs to <http://bugzilla.xfce.org/>.

xfce4-display-settings 4.6.0 (Xfce 4.6.0)   March 2009                  XFCE4-DISPLAY-SETTINGS(1)

but if i do --help, there it is:

◆ xfce4-display-settings --help
Usage:
  xfce4-display-settings [OPTION...]

Help Options:
  -h, --help                    Show help options
  --help-all                    Show all help options
  --help-gtk                    Show GTK+ Options

Application Options:
  -s, --socket-id=SOCKET ID     Settings manager socket
  -v, --version                 Version information
  -m, --minimal                 Minimal interface to set up an external output
  --display=DISPLAY             X display to use

Lots other programs are like that, especially newer ones, and in particular those scripts from Ruby community written in Ruby.

this is in fact a good thing, because it lets doc in sync with the software. With man page, it's a separate program, and it's prone to have version discrepancy.

What About GNU info doc?

note that, Richard Stallman's GNU project, wanted us all to use his info doc format instead.

the info doc format is truly superior to man. Info is essentially a text-based hyperlink system, hyperlink as in today's HTML, yet it precedes HTML by a decade. The info doc supports chapters, navigation, cross-reference, search, and is easy to use.

however, there's a major problem: the verbosity of the content. Due to it being part of Richard Stalmann's GNU project, there's certain writing style, like emacs's manual, it's extremely verbose. For example, in the GNU Emacs Manual , it has several chapters telling user what copy paste means, what text editor means, what text selection means.

also, info doc is full of Richard Stalmann's FSF propaganda.

info doc, like GNU's double-dash syntax diff --brief, are never embraced by unix users. And today, with incredible growth of open source software, by Google, by git, ruby, …, GNU and Info is falling into obscurity.

Why is Unix Man Page Dying

Let me explain the significance of this. The thesis is, unix man page is becoming obsolete.

Used to be, in the 90s or before, any unix software, is basically a text command, and its doc, is the man page. Tech and software changed in past few decades. Obviouly, many software is not just a text oriented unix shit anymore. Browser is best example.

But, what about text oriented software, such as programing lang, or commands that manipulate stuff such as starting web server, optimize png, etc. Turns out, they are moving away from man page as doc. Instead, the command simply have a --help opition. Examples are, git, python, ruby, clojure, and basically everything since 2010.

Now, let's look at why this change, this evolution. First of all, man page is ancient tech. In order to create it, u have to learn the nroff or such format, and have to compile it. If not compiled, part of it is binary gibberish, unreadible. And, man pages r separate from the software. U have to write it independently. Also, major shit, is man page sits in a dir of its own. Like, the collection of docs. There's lots problem of man pages.

In since 1990s, program started to use the lisp idea of integrating doc within the software code. Started by perl, and python java ruby. Etc. The advantage is that, the code and its doc, is integrated. As u write the code, u can see the doc and change it too. As opposed to, a separete file that's the man page, and require separate compilation process. This is the biggest advantage for the coder.

For the user, same. Whatever command u type, xyz, u can read its doc by adding --help. Not so with the unix man. This is why, the significance, the underlying reason, of this shift.

But worst of all, man page was in an era of 80s where u write it in a incomprehensible way, because u assume its readers are also buddy unix coders and are c lang experts. Fuck the unix fuckheads.