4. Reference Pages

4.1 Introduction

A reference manual is a document with a highly structured design that makes it easy for users to find information on a particular component or topic. The basic unit of information in this documentation is a reference page. This guide uses the term reference page to identify an entry in a reference manual.

A reference page may document a single system item, a descriptive topic, a sample program, or some other system feature. This guide uses the term item to describe the system component that is being documented in a reference page, and the term reference page name for the title of the reference page on which the item is documented. (The reference page name is derived from the name for the item, but the two are not always identical.)

On UNIX systems, the system reference manual is always available online, and users can access the manual from the command line by using the man utility. (The name of this utility is an abbreviation of the word manual.) For this reason, each reference page ideally should be a separate file, with a name that can be associated with the item being described.

Try to use the name of the system element being documented as the filename. This name cannot include a slash (/), but can include underscores (_). For this reason, the name may differ from the actual system name of the item. If a suffix is part of the actual system name, include it in the filename.

For example, the reference page for the <sys/time.h> header is sys_time.h.

If source files are stored on systems that do not support long filenames or more than one suffix on a filename, be careful not to create duplicate filenames when filenames are truncated. In this situation, you must also supply a clear mapping of abbreviated filenames to full filenames (and reference page names).

Each reference page corresponds to an entry for the man utility. (The terms manual page, man page, and manpage are all synonyms for the term reference page.) These terms make sense as long as you understand that page refers to the unit of reference information, and does not necessarily correspond to a page in a printed book.

Do not refer to the subject of a reference page as "this name". Generally, you should refer to the subject of a reference page by name at least the first time it appears in each paragraph; for example, "The mknod function".

4.1.1 Further Guidance

Please refer to the PDF version of this document for the full guidance on this topic.

return to top of page