diff options
Diffstat (limited to '')
| -rw-r--r-- | manual/intro.me | 324 |
1 files changed, 324 insertions, 0 deletions
diff --git a/manual/intro.me b/manual/intro.me new file mode 100644 index 0000000..9ab871b --- /dev/null +++ b/manual/intro.me @@ -0,0 +1,324 @@ +.\" Copyright (C), 1995, Graeme W. Wilford. (Wilf.) +.\" Copyright (c) 2001, 2002, 2003, 2007 Colin Watson. +.\" +.\" You may distribute under the terms of the GNU General Public +.\" License as specified in the file docs/COPYING.GPLv2 that comes with the +.\" man-db distribution. +.\" +.\" Thu Sep 21 19:22:47 BST 1995 Wilf. (G.Wilford@ee.surrey.ac.uk) +.\" +.\" chap1.me +.BS 1 Introduction +.BS 2 "\*M" +.lp +\*M is a package that is designed to provide users with information +in a fast and friendly manner while at the same time offering flexibility to +the system administrator. +.TS +tab(@); +l s s s +l lfB l. +It is made up of several user programs: +.sp 6p +.\" Leave the next line alone! + @\(bu man@\- an interface to the system reference manuals +@\(bu whatis@\- search the manual page names +@\(bu apropos@\- search the manual page names and descriptions +@\(bu manpath@\- determine search path for manual pages +@\(bu lexgrog@\- directly read header information in manual pages +.T& +l s s s +l lfB l. +.sp 6p +several maintenance programs: +.sp 6p +@\(bu mandb@\- create or update the manual page index caches +@\(bu catman@\- create or update the pre-formatted manual pages +.T& +l s s s +l lfB l. +.sp 6p +and a special pre-formatter that knows about compressed manual pages: +.sp 6p +@\(bu zsoelim@\- satisfy .so requests in roff input +.TE + +In addition to these compiled programs, there are two shell scripts, +.b mkcatdirs +and +.b checkman +in the +.i tools +subdirectory. +These scripts aid the creation of cat directories and +check for duplicated manual pages, respectively. +.lp +The following manual pages are provided with this package to explain correct +format and usage. +.b man (1), +.b whatis (1), +.b apropos (1), +.b manpath (1), +.b lexgrog (1), +.b manpath (5), +.b mandb (8), +.b catman (8) +and +.b zsoelim (1). +.BS 3 "The concept" +.lp +\*M originally started out life as program suite man\-1.1B, written by John W. +Eaton <jwe@che.utexas.edu> and maintained by Rik Faith <faith@cs.unc.edu> +to which support proposed by the newly +formed FSSTND committee regarding cat directories was added. +.lp +Since then, \*M's most innovative feature: the database cache scheme\** +.(f +\** originally conceived after observing the actions of the Perl-based +manual pager suite, man-pl written by Tom Christiansen +<tchrist@convex.com> +.)f +has been significantly developed. The basic idea was to reduce manual page +search times to a minimum. The following piece of text is included from the +man-db-2.2 distribution: +.(q +The theory: If you go to a library to take a book out, what do you do? +.sp +a) Go and look where it might be on a micro-fiche/terminal, take a look +where it is supposed to be on the shelf, and then go look at the new +arrivals if it's not where it's supposed to be? +.sp +OR +.sp +b) Start at one end of the ground floor, look along every bookshelf +until you've completed that floor, then go up a level and start again +until you've found what you're looking for? +.)q +.lp +Since then the database +.b index +scheme has evolved greatly. +Every manual page and stray cat page on the system is registered in an +.b index +database cache which stores various details about the file including the +timestamp, the location and the whatis\** +.(f +\** one line description of the manual page +.)f +information. +This information is kept up to date by regular runs of +.b mandb . +In some configurations +.b man +also looks for filesystem changes each time it is invoked and helps to +keep the database cache current, but this imposes a penalty on manual page +search times. +.BS 2 "The manual page system" +.lp +The simplest manual page system will have a single manual page hierarchy. +This will typically be +.ip +.i /usr/share/man +.lp +beneath which will be several subdirectories of the form +.i man<sec> +where +.i <sec> +is +.b 1 , +.b 2 , +.b 3 , +.b 4 , +.b 5 , +.b 6 , +.b 7 +or +.b 8 . +These are referred to as +.i sections +of the +manual. +Others may exist and they are not restricted to single +character names. eg. +.ip +.i /usr/share/man/manfoo +.lp +is a valid section subdirectory. +Other common sections include +.b 9 , +.b n , +.b l , +.b p +and +.b o . +.lp +Within these section subdirectories reside the manual pages themselves. Their +filenames follow the pattern +.ip +.i /usr/share/man/man<sec>/<name>.<sec><ext> +.lp +where in most cases +.i <ext> +is an empty string. +An example is manual page +.b cp +.ip +.i /usr/share/man/man1/cp.1 +.lp +which resides in +.i section +.b 1 +and has no special +.i extension . +.lp +.BS 2 "Sections of the manual" +.lp +The manual is split up into sections to ease access and to cater for manual +pages that share the same name. +It is common for a program and function to share the same name. +.b kill +is a good example. +This is both a program which can be used to send a process a signal and +an operating system call with similar functionality. +Their manual pages are stored under sections +.b 1 +and +.b 2 +respectively. +Thus, sections are used to separate out the program manual pages from the +function manual pages and so on. +The table below shows the +.i section +numbers of the manual followed by the types of pages they contain. + +.TS +center box tab (@); +c | c +c | l. +Section@Section contents +_ +1@user executable programs or shell commands +2@system calls (functions provided by the kernel) +3@library calls (functions within system libraries) +4@special files (usually found in \fI/dev\fR) +5@file formats and conventions eg. \fI/etc/passwd\fR +6@games +7@macro packages and conventions eg. \fBman\fR(7), \fBgroff\fR(7). +8@system administration commands +9@kernel routines [\|Non-standard\|] +n@new [\|obsolete\|] +l@local [\|obsolete\|] +p@public [\|obsolete\|] +o@old [\|obsolete\|] +.TE + +.BS 2 "The format of manual pages" +.lp +The format in which manual pages are stored is \*N/\*T or more generally \*R. +This is a typesetter style language\** +.(f +\** similar in some aspects to +.b TeX +.)f +which requires formatting before being viewed. +In fact some manual pages require pre-format processing to +correctly format tables or equations. +.lp +If the page is to be viewed on screen in a text environment, \*N is +used as the primary formatter. If the page is to be printed or displayed in a +graphical environment, \*T is used. Traditionally, \*T formatted files for a +.b C/A/T +(Computer aided Typesetter) which is now obsolete. + +The \*(GN \*R (\*G\**) +.(f +\** Written by James Clark <jjc@jclark.com> and now maintained by +Ted Harding <ted.harding@nessie.mcc.ac.uk> and Werner Lemberg <wl@gnu.org> +.)f +suite of programs offer a choice of output types +including +.b X , +.b dvi +and +.b postscript . +When configuring \*M, the preference is +to use \*G rather than \*T. +.BS 2 "Arguments to configure" +.lp +To allow the configuration program, +.b configure , +to be non-interactive, it can be passed various options to alter the +default settings. +Generic +.b configure +options are discussed in +.i docs/INSTALL . +Options that are specific to the \*M package are described below. +.if r MAN-OPTIONS-ONLY \{ +.lp +MAN\-OPTIONS\-BEGIN +\} +.lp +.ip \-\-enable\-cache\-owner[=ARG] +By default, system-wide cache files will be owned by user man. +Use this option with an argument to change the cache file owner. +.ip \-\-disable\-cache\-owner +Use this option to leave the ownership of system-wide cache files +unconstrained. +Users will be allowed to modify them. +.ip \-\-disable\-setuid +By default, +.b man +will be installed as a setuid program to the user that owns the +system-wide cache files. +Use this option to install +.b man +as a non-setuid program instead. +.ip \-\-enable\-mandirs=OS +By default, \*M supports manual page directories in any of several layouts +used by free and proprietary versions of \*U. +However, in certain cases, this can cause \*M to find the wrong page by +mistake, especially when the names of some manual pages on the system +contain periods. +Use this option with an argument of GNU, HPUX, IRIX, Solaris, or BSD +(or more than one of these, separated by commas) to support only the layouts +typically used on each of those systems. +Note that \*M is not currently capable of writing cat pages in the proper +BSD layout. +.ip \-\-with\-device=DEVICE +Use this flag to alter the default output device used by \*N. DEVICE is +passed to \*N with the \-T option. +.b configure +will test that \*N will run with the supplied device argument. +.ip \-\-with\-db=LIBRARY +configure will look for database interface libraries in the order gdbm, +Berkeley DB and finally ndbm and will #define appropriate variables relative +to the first one found. +To override the built-in order on platforms having a choice of interface +library, use this option to specify which library to use. +.ip \-\-enable\-automatic\-create +If this flag is used, +.b man +will automatically create index databases for users' private manual page +hierarchies. +.ip \-\-disable\-automatic\-update +Normally, +.b man +will update entries in index databases if it finds newly installed manual +pages (if the +.b \-\-update +flag is used) or delete entries if manual pages are removed. +This flag suppresses this behaviour. +.ip \-\-disable\-cats +Normally, +.b man +will automatically try to create cat files corresponding to manual files +when a manual page is read. +This flag suppresses this behaviour. +.ip \-\-disable\-manual +Don't build or install the \*M manual. +This may be useful when cross-compiling, or to reduce the installation size. +.if r MAN-OPTIONS-ONLY \{ +.lp +MAN\-OPTIONS\-END +\} |