Unix Handbook Style Guide

Synopsis

A reader learning to use a terminal needs to know exactly what to type and how to recognize the result. An administrator arriving at a Solaris console may already know the task and need only the local procedure. The command examples use the same conventions for both readers.

Writing a chapter

Give each chapter a title readers can recognize in a search result. Write a one-sentence page description naming the task, the system when relevant, and what the reader will learn. Open with a short synopsis explaining the outcome and what the reader needs to begin. “Check whether a service will start at boot on OmniOS” says more than “Service management.”

Use formal American English. Avoid addressing the reader as “you” or “your” in headings, instructions, and explanations. Give instructions in the imperative, as in “Press q to leave the manual page.” In explanations, name what performs the action, as in “The shell expands the wildcard before running the command.”

Write out contractions in handbook prose. Use the serial comma in English lists, as in “files, pipes, and processes.” Begin with the task or observation and omit conversational openings such as “let’s” or “we will.” Apply the same style to captions and explanatory comments. Preserve quotations, product names, prompts, and output verbatim.

In the beginner course, introduce each term at the point of use. Spell out unfamiliar abbreviations the first time they appear, as in “process ID (PID).” Explain how to leave a manual page before asking the reader to consult one. Carry a small working example forward and link back to the step that produced any file the reader needs. In a system guide, assume shell familiarity, name the release, and give the quickest way to check the result on that system.

In an explanation chapter, start with an observation the reader can reproduce. In a comparison, ask the same question of each system and show what counts as an answer. “Is this service running?” and “Will it start at boot?” need separate checks.

Command examples

Introduce each block with its purpose. A shell block contains the lines to enter, with the leading prompt omitted. Keep quotation marks, variable references such as "$HOME", and other characters the shell needs. Start beginner exercises in an ordinary user account. Supply small input files or show how to create them.

To print each distinct fruit name once, run this pipeline in a Bourne-style shell. The first command supplies the input. The second sorts the names in the C locale and drops duplicates.

Shell input
printf '%s\n' plum pear plum | LC_ALL=C sort -u

Example output

pear
plum

The repeated plum appears once. When a result varies, point out the field to inspect. A reader checking a process ID needs to recognize the right process even when its number differs.

Use a sh fence for Bourne-style input and name a particular shell when its features matter. Label file contents with the filename and show them in a separate block. For an interactive exchange, use a console block and the label Example terminal transcript. In this shell transcript, the shell prints the first prompt, read accepts the name typed on the next line, and printf displays the greeting.

Example terminal transcript

$ read -r name
Ada
$ printf 'Hello, %s\n' "$name"
Hello, Ada

Privileges and changes of context

Identify any value the reader must supply, especially a device name or a destination path. Put a warning just before a step that can overwrite data, with a way to confirm the target. For an administrative action, state which account, role, or authorization the system requires. Use doas or sudo only where the procedure assumes that tool is installed and configured. The calling shell opens the destination for a redirection such as >. The shell needs permission to write there even when the command runs with elevated privileges.

Label an existing root session Run in the root shell. End the block before a reboot, a new login, a change of host or shell, or a result the reader must inspect. Tell the reader how to recognize the new context before giving the next command.

Portability and manual pages

Name the layer responsible for a difference. A feature can belong to the shell, a utility implementation, a distribution, or the operating system. For example, the -f option takes a format string in OpenBSD’s stat and requests filesystem information in GNU Coreutils’ stat. A reader following the wrong manual can get a plausible answer to a different question. Link the first relevant name(section) reference to the manual for the system and release in use. For GNU utilities, an upstream manual is also appropriate. OpenBSD stat(1) · GNU Coreutils stat

Consult the Portable Operating System Interface (POSIX) standard for behavior portable programs can rely on. Check practical examples on the editions named in the chapter and record the shell and release in the review notes. Identify a documented procedure as such when the system is unavailable. For historical systems, use period manuals and identify the release or machine behind a transcript. In a family tree, give the date and explain whether a line represents shared code, influence, or compatibility.

Preparing a chapter for Hugo

Use TOML front matter for the chapter title, description, navigation weight, and draft status. The page template supplies the title. Start the chapter body with ## Synopsis and use second- and third-level headings that readers can link to. Keep a descriptive URL when moving a chapter in the contents, and preserve any published anchors that readers use to reach a specific procedure.

Keep exercise files beside the chapter that introduces them and link to those files where readers first need them. Give diagrams a caption that explains what to look for and alt text that conveys the relevant information. In the rendered page, check that commands can be copied without prompts or output, a linked heading opens at the intended passage, and the exercise works from the supplied files.

UNIX is a registered trademark of The Open Group.