PRELIMINARY NOTE This is only for Unix-like systems or, more specifically, systems having a "man" manual repository. Anyway, you can find everything transcripted later in this README. The primary goal was to provide a man page for foo so that newbies could get enlightenment when typing "man foo". The secondary goal was to give some perspective about command options for experienced users and programmers alike. Hope you all find it useful, and may you want to contribute suggestions and comments to: The final goal should be to include metasyntactics in an extension of the POSIX specification. PREVISUALIZE nroff -mandoc foo.7 | less INSTALL Edit the Makefile if you want to change the predefined name of the C compiler (gcc) or the destination path (/usr/local). Execute: make install To install manually: First copy over the file foo.7 to the directory /usr/local/man/man7/ or to the directory /usr/local/share/man/man7/ (Create the directory if necessary, but make certain that it appears either in the MANPATH environment variable, or in the file-s /etc/man.config or similar). Optionally, you can create the links bar.7 and baz.7 inside the same directory. Compile: cc -o foo foo.c and put foo in /usr/local/bin or elsewhere in your PATH. EXECUTE foo man foo TRANSCRIPTION of the man page foo(7) Metasyntactic words foo(7) NAME foo -- abstraction representing any name SYNOPSIS foo [options] The options are sequences of characters that can alter the behavior of the command. They are separated from each other by at least one space, and consist typically in one or more letters preceeded by at most two hyphens (minus signs). This man page tries to explain the usual meanings of every possible option in every possible command. Obviously, it can not even pretend to be complete but merely orientative, so look at it with caution and use it with extreme care and judgement. This should be your last resort. Never use it unless there is no other source of information available: Try first man foo SUBSTITUTING the word foo by the desired command name. In the same way, try also any or all of the follow­ ing: info foo help foo foo -h DESCRIPTION foo is the preferred way to represent any command, pro­ gram, shell built-in, function or subroutine name. The words bar(7), baz(7) and others serve the same purpose, specially once foo(7) has already been used. Together they are called metasyntactic variable names. This man page, for instance, could have been called options or even unix, linux, or any other thing of that sort. That is why foo was chosen. OPTIONS -- make subsequent hyphens no longer be interpreted as signaling the beginning of an option EXAMPLES rm -- [filename starting with the character - ] --[option] mark option as having more than one character EXAMPLES --help, --version ... (mainstream usage of -- ) Multi-character options tend to have single letter equivalents: EXAMPLES -h, --help -z, --zip Exceptions are gcc(1), find(1), the X(7) server and its related programs, which use long options preceded by a single hyphen: EXAMPLES -display, -geometry ... - use standard input in place of a file (most used in command pipes) -[number] select the mode of operation when there are more than two EXAMPLES telnet, nice ... -[letter] -a --all do not stop after processing the first item EXAMPLES (numerous; mainstream usage of -a) --ascii, --text input/output in plain ASCII text EXAMPLES grep, gzip, mc -a [argument] --append [stuff], --add [stuff] proceed without overwriting preexistent data EXAMPLES tee, ar, mail -b set mode --bytes set byte output mode EXAMPLES free, cpio ... --binary set binary operation mode EXAMPLES md5sum, whereis --batch do not listen to manual input EXAMPLES top, gimp --brief generate more concise output (Related to -q and -s, and opposite to --verbose) EXAMPLES file, gprof --bus operate on bus EXAMPLES hdparm, lspci -b [size] --block [size] specify the size of data portions (on/to disk) EXAMPLES (mainstream usage of -b) --buffer [size] limit intermediate storage size (in-memory) EXAMPLES less, smbclient --border [size] set margins EXAMPLES emacs, xterm -c --check examine things before working on them (note the difference with --test) EXAMPLES sort, mke2fs ... --comp disable/reenable compression or compaction (Related to -z) EXAMPLES pstree, poff -c [argument] --compile [non-numeric], --command [non-numeric] process some instructions (Similar to --exec) EXAMPLES gcc, sh, su ... --count [number] declare its argument to be a natural number (Similar to -n) EXAMPLES from, eject -d --daemon start permanent background execution EXAMPLES run, fdmount ... -d [argument] --debug, --diagnose perform additional tasks for error detection EXAMPLES (mainstream usage of -d) --dir [directory] set directory mode or the directory to operate EXAMPLES if, apache --delete [stuff] CAUTION: this is normally irreversible EXAMPLES tar, tr, losetup e typically without prepending hyphen --extract [filename] uncompress, be it a part or the whole EXAMPLES unace, unrar ... -e [arguments] --exec [commands] execute some instructions (Similar to -c) EXAMPLES sed, mysql ... (mainstream usage of -e) --exclude [stuff] make exceptions, do not execute on arguments CAUTION: contrast with the previous usage EXAMPLES dump, par -f --force override internal security mechanisms (Resembling, but not exactly the same as -y) CAUTION: dangerous EXAMPLES ln, rm, rmmod --fake do not perform any real action (Similar to --test) CAUTION: opposite to the previous usage EXAMPLES mount -f [argument] --file [filename] specify the file to use EXAMPLES (mainstream usage of -f) -g --graphic launch visual interface for mouse interaction EXAMPLES vim, mtr -g [argument] --group [identifier] specify group EXAMPLES useradd, lsof ... (mainstream usage of -g) -h --help, --usage display some help and exit (Similar to -?) EXAMPLES (mainstream usage of -h) --human output in a more easily readable format (Also has to do with --help) EXAMPLES df, du -h [argument] --headers [modifier] determine how (and whether) to print headers EXAMPLES w, nl, lpr ... -i --interactive, --inquire enable/disable confirmation (Opposite to -y) EXAMPLES (mainstream usage of -i) --insensitive make no distinction between upper case and lower case letters (Related to --ignore) EXAMPLES locate, diff --ignore ignore things, usually errors EXAMPLES make, top, env --invert invert the output somehow (Similar to --reverse) EXAMPLES ico, kfax -i [argument] --include, --insert, --install [filename] incorporate the contents of a file EXAMPLES dpkg, rpm ... --initial (rarely used) EXAMPLES expand, clisp -j [argument] --jump [destination] set the order in which things get evaluated EXAMPLES less, iptables ... -k --keep do not perform normal elimination EXAMPLES rman, bzip2 ... (mainstream usage of -k) --kill eliminate the things dictated by the output (note the difference with --delete) CAUTION: normally irreversible, and opposite to the previous usage EXAMPLES fuser, sudo -l control output format (usually making it larger) --list generate list formatted output EXAMPLES fdisk, pgrep ... (mainstream usage of -l) --long not always in the same sense as --verbose EXAMPLES cmp, mkisofs --log enable/disable logging (output to a file) EXAMPLES xterm, cvs -l [argument] --lines [number] set line count/numbering EXAMPLES col, wc, nm ... -m [argument] --map [mapping] use an alternative map instead of the default EXAMPLES bash, lilo, reset ... -n --not negate something, usually a part of the main output (not just verbosity, like -q, -s or --brief) EXAMPLES sed, mesg ... -n [argument] --number [number] declare [argument] to be a natural number (Similar to --count) EXAMPLES lp, dmesg ... -o [argument] --output [filename], --object [filename] specify the destination file to write results to EXAMPLES (mainstream usage of -o) --option [value] set an option EXAMPLES set, mount -p --print print output EXAMPLES read, cal ... -p [argument] --port [number] specify port (commonly in TCP/IP programs) EXAMPLES nmap, sshd ... --protocol [argument] specify protocol (also in TCP/IP programs) EXAMPLES iptables --prefix [prefix] use words with same beginning EXAMPLES bison, mktemp -q --quiet In traditional practice, it is verbosity what has to be asked for explicitely, making this option superfluous. (Related to --silent and --brief, and opposite to --verbose) EXAMPLES gdb, ping ... (mainstream usage of -q) -r --recursive apply to all directories underneath EXAMPLES (mainstream usage of -r) --reverse somehow reverse output/presentation (Similar to --invert) EXAMPLES cat, xterm ... --restrict disable part of the functionality EXAMPLES bash, jobs, ps --recover resume operation as if it had not been interrupted EXAMPLES vim, nmap ... -s --silent supress output (in a much greater degree than -q) (Related to --quiet and --brief, and opposite to --verbose) EXAMPLES (mainstream usage of -s) -s [argument] --size [size] limit total input (as opposed to -b, which limits size for fragments) EXAMPLES shred, xargs ... -t --test do not perform any real action (Similar to --fake) EXAMPLES lilo, unzip ... (mainstream usage of -t) -t [argument] --terminal [term] specify a terminal EXAMPLES skill, ul, emacs --tag [label] handle paragraphs EXAMPLES fmt, vi ... -u --update do not replace if newer EXAMPLES man, mv ... -u [argument] --user [identifier] specify user EXAMPLES (mainstream usage of -u) -v --verbose output information about execution (Opposite to --brief, --quiet and --silent) EXAMPLES (mainstream use of -v) --version output information about the program EXAMPLES chattr, lsof ... If there is a -V option, the trend is for -V to have this meaning, with a few exceptions: fsck, lsof, sox -w --wait do not start execution immediately EXAMPLES host, open ... --write write to the device EXAMPLES mount, hwclock ... -w [argument] --width [value] set width EXAMPLES ptx, banner ... --warnings [modifier] enable/disable warnings EXAMPLES passwd, jw ... -x same meanings and usage as -e -y --yes do not ask for confirmation (Opposite to --interactive, and related to --force) CAUTION: dangerous! EXAMPLES e2fsck, apt-get (mainstream usage of -y) -z --zip apply compression EXAMPLES (mainstream usage of -z) -[Capital] a capital or upper case letter is used only after the corresponding lower case letter has already been used. This implies, on the one hand, that what -V means for a program can be -v on another program and viceversa. On the other hand, resorting to capitals frequently implies there are already so many options present that the need for good documentation can not be ignored. -? help (Similar to -h) +[option] +[letter] do the opposite to whatever the normal option does EXAMPLES chmod, xlock ... +[number] open at the line specified by [number] EXAMPLES more, vi ... FILES foo can also represent any filename. CAUTION: In ordinary practice, filenames beginning with foo, bar, etc. designate files that can be safely deleted or overwritten at any time without warning. BUGS Nothing really prevents foo from becoming the name of a real program in the future. Only the inclusion of meta­ syntactic variable names as part of the POSIX standard could avoid that possibility. REPORTING BUGS Send corrections/enhancements to . At least two examples should be found for an usage to be included. COPYING Copyright © 2002 Juanjo Garcia This is free software; see the source for copying condi­ tions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified ver­ sions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above con­ ditions for modified versions, except that this permission notice may be included in translations approved by the Free Software Foundation instead of in the original English. AUTHOR Written by Juanjo Garcia. HISTORY 1959 - Use of the word foo among programmers is first con­ stated at M.I.T. 1978 - The words foo and bar reputedly gained widespread acceptance since their appeareance as subroutine names in examples from famous books, like "The C programming lan­ guage" by Kernighan & Ritchie. 2001 - Rfc3092 describing foo was published following the work of Eric S. Raymond in the jargon file. SEE ALSO sh(1) or bash(1), man(1), apropos(1), whatis(1), info(1).