Linux: Manpage Getting Obsolete by --help?

By Xah Lee. Date:

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)

       xfce4-display-settings - Display settings for Xfce

              xfce4-display-settings [OPTION...]

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

              Show all help options

              Show GTK+ Options

   Application Options:
       -v, --version
              Version information

              X display to use

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

       Please report bugs to <>.

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
  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 the 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 obsecurity.

If you have a question, put $5 at patreon and message me.