Hi Erling, Erling Westenvik wrote on Sat, Jun 10, 2017 at 10:08:57PM +0200:
> Probably a stupid question but: > Why isn't the -T switch documented in man(1)? Not a stupid question at all. First answer: It is, look at man(1) and you will find this sentence: The options -IKOTW are also supported and are documented in mandoc(1). Second answer: The reason why it isn't in the SYNOPSIS, in the usage(), and in the main options list is that jmc@ insisted that the man(1) manual page better be short and simple, and advanced stuff that is more fully documented in mandoc(1), and more often needed in mandoc(1), not be duplicated there. He kind of has a point. The man(1) manual is most important for beginners and should better not overwhelm them. Advanced users are likely to also find their way if finding the advanced features requires carefully studying the *whole* text. I designed the user interface of the OpenBSD versions of man(1), apropos(1), whatis(1), and mandoc(1) such that all four support exactly the same options, such that you only need to learn one set of options, which is not true on other operating systems. If you like a bit of confusion now and then, take a look at: http://mdocml.bsd.lv/man/man.options.1.html Yes, -AxY are the only three option letters not yet taken, and all except -BGJjNOUXyZz have conflicting meanings; the record holders are -c with nine different meanings, -p and -s with eight, -f and -w with seven, and several with six different meanings. Talk about history -- as if nobody ever looked at what anybody else did... On OpenBSD, if you like, you can access all functionality of the four utilities with man(1): apropos == man -k whatis == man -f mandoc == man -cl Also, our options are designed to naturally form four groups and are firmly grounded in BSD history, with one exception adopted from Colin Watson's Debian Linux man-db package: 1. Search options decide which directories are used for searches: -M override MANPATH ("manpath", 4.3BSD man, 1986) -m augment MANPATH ("manpath", 4.3BSD-Reno man, 1990) -S restrict architecture ("subsection", OpenBSD 2.3 man, 1998) -s restrict manual section ("section", OpenBSD 2.3 man, 1998) 2. Input options decide how command line arguments are interpreted: -k use full search query syntax ("keywords", 4BSD man, 1980) (default for -k) search substrings in title lines only -f complete words to be matched in names only ("find", 4BSD man, 1980) (default for man(1)) exact match of complete names -l accept file names, ignore search options ("local", man-db 2.2a7, 1994) 3. Parse options influence interpretation of the input files: -I set default value for .Os macro ("input", OpenBSD 5.2 mandoc, 2012) -K force an input character encoding ("enKoding", groff-1.20, 2005) -m force an input macro language ("macro language", v7 troff, 1979) 4. Output options decide how output is presented: -a show all matching pages, formatted ("all", 4.3BSD-Tahoe man, 1988) (default for man(1)) show the first matching page, formatted -T select an output format for formatting ("terminal", v7 nroff, 1979) -O set output format specific options ("output", OpenBSD 4.8 mandoc, 2009) -c do no use a pager ("copy to stdout", 4.3BSD-Reno man, 1990) -h show the SYNOPSIS sections only ("head", 4.3BSD-Net/2 man, 1991) (default for -k and -h) show title lines only -w show file names only ("where", v7 man, 1979) -W select a message level ("warn", OpenBSD 4.8 mandoc, 2009) 5. One special option can influence search, parse, and output options: -C select alternate config file ("config", 4.4BSD-Lite1 apropos, 1994) Unfortunately, this structure cannot easily be represented in the manual pages without bloating them and making them less readable. Several of the option letters could be more mnemonic. But they come from six different programs (troff, nroff, groff, man, apropos, mandoc) and five different operating systems (Version 7 AT&T Unix, 4.xBSD, groff, Debian man-db, OpenBSD) and the oldest (-mTw) have been established since 1979, so people have become so used to them for several decades that it's much too late to change any of them. Yours, Ingo
