User:SwifT/Complete Handbook/So far so good

Handbook syntax

Used symbols and colors

Okay, we are now at the end of this first part. As you might have seen, the previous sections suddenly started using some Linux-specific commands. I will quickly explain how this handbook uses those Code Listings and other syntax.

Code listings

A code listing can be a command that needs to be executed. When this is the case, the command is prepended with a symbol that refers to the prompt.

A prompt is a short string given by the system to the user, telling that the user can give a command. By default, the prompt for a regular user would look like so:

user $ 

When you are the root user, the prompt will look like so:

root # 

As you can see, it differs with the ending character: regular users have a prompt that ends at $, but the root user has an ending character of #. For this reason, we will use this single character throughout the rest of the document to refer to the prompt. When the character is a $ you can (should) execute the command as a regular user. When the character is a # you can (should) execute the command as the root user.

For instance, the ls command (which lists the content of the current working directory) can very well be ran as a regular user, but to install a package (like bzip2) you need to be root:

user $ls

root #emerge --ask bzip2

As you can see, the command itself is highlighted. When there is output from the command to the screen that you do not need to type, it will be in plain text. When we add some comments, you will notice that it has a different layout. For instance, to change your password:

user $passwd

Old password: ## (Enter your old password)
New password: ## (Enter the new password)
Re-enter new password: ## (Re-enter the new password to verify)
Password changed.

We will also use code listings to show the contents of a file.

Warnings

When the information in this handbook is incorrect due to a bug or a temporary issue, I use a warning to inform you about this temporary setback. I prefer to do it this way than to fix the content itself because I feel that documentation should not be used to fix bugs (or provide workarounds).

An example warning would look like so:

Warning
Due to bug #100456 in the Evolution ebuild you can not install version 2.2.3-r2 for the time being. Please use 2.2.3-r1 until a fix has been found.

Important

When we want to stress out something important, we will normally put this in the paragraphs using emphasised text or bold text. However, when it is quite urgent and would require a larger rewrite, we will temporarily use an importancy-box like so:

Important
Make sure /etc/hostname is removed afterwards. Otherwise the error will remain since the baselayout package first checks this file prior to /etc/conf.d/hostname.

Notes

At the end of a chapter we might add a few notes, either as a certain type of footnote or a reference to another resource. If the amount of notes aren't too large, we will use a note box like so:

Note
The Linux Documentation Project has a few guides on networking as well. Definitely worth a read.

What can you expect

Installing Gentoo

In the next part, we will give you lots and lots of Linux technical information to allow you to install Gentoo Linux on your system. Unlike with the Gentoo Handbook we will try to be even more verbose, but less step-by-step.

Why? Because you should be able to install Gentoo the way you like it without the need to take a look at the step by step descriptions. Not that the Gentoo Handbook is written badly, but just... differently.