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