Version 15 of man

Updated 2007-12-16 11:35:27 by dkf

Tcl/Tk man pages:

Unix Manual Pages

by Theo Verelst

   man [-k] [-s {on some systems}] [section] page

The man command on Linux, Unix, and under cygwin on all windows versions except the small portable ones, allows you to view manual pages for (in principle) all commands on the system. If we'd want to know what the command 'ps' (process status) works like, we'd type

   man ps

and get:

 PS(1)                               CYGWIN                               PS(1)

        ps [-aefls] [-u UID]

        -a, --all
               show processes of all users

        -e, --everyone
               show processes of all users

        -f, --full
               show process uids, ppids

        -h, --help
               output usage information and exit

        -l, --long
               show process uids, ppids, pgids, winpids

        -s, --summary
               show process summary

if we don't know the options and usage of a certain man version, we type on the target machine:

   man man

to get the manual page of man itself:

 man(1)                                                                  man(1)

        man - format and display the on-line manual pages
        manpath - determine user's search path for man pages

        man  [-acdfFhkKtwW]  [--path]  [-m system] [-p string] [-C config_file]
        [-M pathlist] [-P pager] [-S section_list] [section] name ...

        man formats and displays the on-line manual pages.  If you specify sec-
        tion,  man  only looks in that section of the manual.  name is normally
        the name of the manual page, which is typically the name of a  command,
        function,  or  file.   However,  if  name contains a slash (/) then man
        interprets it as a file specification, so that you can do  man  ./foo.5
        or even man /cd/foo/bar.1.gz.

        See  below  for  a  description  of where man looks for the manual page

        -C  config_file
               Specify  the  configuration  file  to  use;   the   default   is
  ... (etc)

A good manual page probably has:

   Section indication
   NAME of the command with description
   SYNOPSIS in generic format the possibly optional and symbolic or literal arguments and their order
   DESCRIPTION in human readable form, concise and short what the command does
   OPTIONS available, their exact form in a list, and short and concise description of each and the combinations
   SEE ALSO cross reference to related commands

and possibly:

   BUGS obviously: known bugs or limitations
   ENVIRONMENT VARIABLES the command uses or affects.

One can use

   man -k <keyword>

to search for keyword in all manual page headers and get a list of results per line. In such usage lines, it used to be standard to take <> as indicating literals, and as optional arguments, and ... as possible repetition.

To make this work, the whatis command must be initialized by updating the man database, probably with something like calling the script:


Under linux I guess that could be /sbin/makewhatis, probably only accessible by root.

Under cygwin on windows, where this all works, the tcl/tk manual pages are not automatically available if you installed you own TCL/TK. Cygwin currently has I think wish8.3 or so installed, and has possible manual pages for them, but that would not necessarily be for your version, which can be delusive.

Also, under windows XX, tcl/tk comes not with man formatted manual, only window help file compiled format (or something, which unfortunately cannot have its font size set separately (annoying when running a 1600x1200 workstation like setup wanting some things small as possible, and a manual page at a neatly readable non-eye-straining size).

One could get the Linux files for the same version, and install those under /cygdrive/c/cygwin/usr/man/mann or something.

Man is conceptually a concatenation of two programs, driven by a database, first a formatter, usually nroff (see manual page on unix/linux), and then a pager, usually a 'more' (or 'less') variation, which show its input text one terminal page at a time, paced by <space> for a new screen, <newline> to scroll one line, and <b> for one page back (when available, not possible on stream inputs):

   nroff -man /somepath/somemanualpage.n | more

What does all this mean for Windows inhabitants? It's common among Tcl'ers to say, "it's in the man page" to mean "what you search appears in the standard documentation which appears in a Tcl distribution". Under Unix, as described above, a canonical installation makes this standard documentation visible through man COMMAND. The standard documentation is also present under Windows, even in the absence of Cygwin, but there the easiest access is through [describe how to navigate to Tcl Help].

Tcllib contains doctools as one way of writing documentation that can then be converted into man page (as well as other) formats.

See also A little man page viewer as well as tkman.
LV TkMan is a wonderful tool, once you set it all up. Be certain to install the auxiliary tools to make it as powerful as possible.

TV (june 28 '04) I'm making a Tcl/Tk man pages comments page .

LV I don't know why we need so many variations on this topic. It seems to me that one of these should be chosen, the contents of the other pages moved there, and then references to the other pages changed to the one page to rule them all ... so to speak.