BSDwiki/ Find appropriate documentation

Find appropriate documentation

Author: KevinDKinsey

Reviewer: name contact BSD flavour

Reviewer: name contact BSD flavour

Concept

  • Understand that BSD systems are well documented and there are many detailed resources available to a system administrator.
  • Be able to use the documentation(((documentation))) found on the system itself as well as be aware of the resources available on the Internet.

TODO: there is another section about this, so need to make sure they are not covering same details. TODO: if one section should be removed, we can just merge the concept and content together TODO: Recognize the different sections of the manual

Introduction

Some people say BSD systems "aren't user-friendly"; others reply, "BSD is user-friendly; it's just picky about who its friends are." Consider this section a lesson in making friends with your BSD system.

There are some excellent built-in sources of documentation on (almost) every BSD system. The "System Manager's Manual" ("manpages") is powerful and legendary (and the origin of the saying "RTFM", which is defined below). Example files, Developer whitepapers and 3rd part program documentation can be found on many systems. And, because UNIX in general was (and still is) the backbone of the Internet, there are literally millions of pages of on-line information (assuming, of course, that you can find web pages that are both relevant and trustworthy/authoritative.

RTFM! (Read the friendly manual)

From the earliest days of their existence, BSD systems have made extensive use of program documentation through "manpages", that is to say, the system's built-in manual pages. While the interface may not be familiar to people who have no background in Unix-like systems, the "man" system is exceptional in the amount of and quality of documentation available, and ease of access.

A "manpage" exists for almost every program, device, library, system call, and configuration file on the system. If you are aware of a program (let's say kill), simply typing man kill at the shell's prompt will present you the documentation for kill(1), piped through your $PAGER (sometimes this is more(1), but it is often less(1) --- don't get confused, because less is really more).

Advantages of Man pages

  1. they include a brief synopis of the command syntax, flags, and options at the very top of the manual page;
  2. they are typically written by the developers themselves, so they tend to be more complete and accurate (than online "HOWTO's", for example);
  3. "manpages" are available on the system locally and from the basic terminal, and so they aren't subject to network interruptions or the current state of the GUI.

If you are running a GUI, then you can have your manpages put into a GUI window (try "xman"). Also, note that it is possible to install a BSD system without manual pages; if typing "man man" at your shell prompt produces an error (or no output), consult with someone about getting them installed.

For more details about manpage sections and usage, see Recognize the different sections of the manual.

But I Don't Know What Manpage to Read!

In the event that you can only remember a portion of the file, try using whatis(1) or apropos(1). These programs search a database of installed documentation for the string you pass in as an argument. Whatis returns fewer results (only exact matches), and apropos returns any manual page references that contain the string at all (so sometimes it's a good idea to pipe apropos to your $PAGER).

The Manual is Too Cryptic!!!

The manual intends to describe every program with enough detail to describe all of the behaviors and options available to the user. It might be criticized because many manpages lack examples in sufficient quantity to apply to every conceivable situation (an arguably impossible task). However, the manual pages are written to describe "everything to most people" instead of "exactly what you wanted to know today". Reading The Fine Manual usually has an answer, even if it is not as "easy" to glean as some other sources of information.

Other BSD Documentation

The "Doc" Tree

Each Project has a team responsible for documentation of the system. There is lots of data available if the documentation is installed. A large number of small books and articles in many lanuages exist under /usr/share/doc on many systems. Check your Project's website for information about Handbooks, FAQs and other resources produced by the Project's Documentation team.

Handbooks, Websites, Mailing Lists

Many of the "Doc Tree" resources are also available at your Project's web site. Look for FAQs, handbooks and many of the other resources maintained by Project members to be available in a web format.

Example files

Example files live in a good many places on BSD systems, including "defaults" directories such as /etc/defaults, /etc/rc.d/defaults, /boot/defaults, and so on. A good many example files and sample scripts for making life easier as a BSD sysadmin are located under /usr/share/examples.

Developer Whitepapers and Miscellaneous files

Many of these documents are very old (pre-dating modern BSD systems - e.g, dating back to the 1980s), but your "branch" of the tree may have newer papers as well. Check the subdirectories of /usr/share/doc such as papers, smm, psd, and so on.

Other historical and occasionally useful docs live in /usr/share/misc, such as an ASCII table, the "BSD Family Tree" and more.

3rd party program docs

GNU Info pages and Perldoc

Many programs that are "contributed" software (for example, those from the Free Software Foundation) also have "Info Pages", which are displayed with (you guessed it) info foo (where "foo" is the program name). If the software is FSF software, the info pages have a slightly different format; otherwise, info simply displays the manual page in a way similar to man.

Other sources of documentation

Occasionally software developers will "skimp" on manual pages for their software in favor of creating documentation in other formats. If you find a manual page to be unsatisfying, try looking for text, HTML or PostScript/PDF documentation under /usr/local/share or /usr/local/doc, /usr/local/share/doc, etc.

Also, an Internet search can yield good results, particularly if it is very specifically worded, or, if a "general" search, you constrain the search to BSD-related websites, newsgroups, and mailing-lists.

Examples

Practice Exercises

More information

apropos(1), man(1), man.conf(5), whatis(1), and info(1); share/doc/ and share/examples/; in addition, each BSD project maintains an online handbook and several mailing lists