[next] [previous] [top] [last] [contents] [indice ridotto] [violazione licenza] [translators] [docinfo] [indice analitico] [tome] [part]

Chapter 747.   Documentation

⁽¹⁾

There are various documentation sources on GNU/Linux. Most of them are normally available with the distributions, but their inquiry may be a problem for people without experience.

747.1   Pure text

The simplest way to write something is the pure text. This is what happens with the 'readme' and similar files, or with all documentation that has been converted in this format for simplicity.

These files can be read by using two well known programs: more or less. more is traditionally more common in Unix environments; less is more practical and has a richer functionality. The functions of these two programs are similar, even if the second one offers a large number of additional functions which we do not consider.

The syntax of these two programs is as follows:

more [options] [file]...

less [options] [file]...

For the normal usage, options are not required and, if no file is listed in the arguments, the data are read from the standard input.

Once any of these programs has been started, the text of the file is listed according to commands, entered by pressing keys. The approach is similar to that used by VI: some commands require pressing one or more keys in sequence; some other ones require an argument and in this case, they appear in the last screen line or in a window. The table 747.1 presents the list of the common and fundamental commands of the two programs.

The main difference between these two programs is that less can scroll text backwards also when the text is received from the standard input, whereas this is not possible with more. Moreover less allows the use the arrow keys and the page-up and page-down keys to scroll the text and allows also to make backward searches . The table 747.2 lists some additional commands available with less.

less is a program that can be used in a much more complex ways than what we have described above, but they are not necessary for a normal usage.

Examples

$ ls -l | more[Enter]

$ ls -l | less[Enter]

The commands above present on the screen the list of current directories that probably is too long to be seen fully without using these two programs.

$ more README[Enter]

$ less README[Enter]

The commands above present on the screen the content of the file README.

747.1.1   Variable LESSCHARSET

The less program uses the environment variable LESSCHARSET: if it contains the string latin1, the program allows the correct display of the characters and special symbols that are not included in the pure and simple ASCII coding.

747.2   Man pages

Almost all programs have a manual page, or man page. It is a brief document about the usage of that particular program, written in a relatively standard format.

There are various sections of these manual pages, according to the type of information that they contain. It is possible to have multiple pages with the same name, included in different sections. The table 747.3 lists the different sections.

When you want to refer to a manual page, you should enter its name followed be a number within parentheses, which specifies the section. For instance, man(1) refers to the manual page with name man in the first section. Often in the documentation, this kind of references are used for programs, to provide immediately the information on that specific program.

The documentation is accessed by using the program man which usually runs less, or more, to scan the document. The table 747.1 presents the list of the common fundamental commands of these two programs.

747.2.1   Physical location and localisation

The manual pages can be found in different locations within the file system.

• /usr/share/man/

  This is the main location of the manual pages.

• /usr/X11R6/man/

  It stores the manual pages that refer to the graphical system X.

• /usr/local/share/man/

  It is the location of the manual pages of the programs stored under the directory /usr/local/;

• /opt/application/man/

  It is the location of the manual pages of additional application programs (add-on).

These directories are all subdivided or subdivisable in the same way. Each of the starting directories is referred to as mandir.

The actual location of the manual pages file can be expressed in the following format:

mandir[/locale]/mansection[/architecture]

This means that, in addition to the mandir/ directories already described, there is another possible directory, locale/, that is then subdivided in various subdirectories according to the sections of the manual pages (usually from man1/ to man9/). Then each of them can also be subdivided according to differences among architectures.

The directory locale/ is optional and is often missing. It can be used to distinguish among the manual pages of different languages or of different formats. The name of this directory is defined by the POSIX 1003.1 standard according to the following syntax:

language[_territory][.character_string][,version]

• language is a code in lower case letters defined by the ISO 639;

• territory is an optional code of two upper case characters defined by the ISO 3166;

• character_string is a numeric code which identifies the used character set, according to the ISO standard (in practice it is the number of the ISO standard).

• version is an additional not well defined item, whose use is discouraged.

For instance, if we want to find manual pages in Italian, you should find them in the directory mandir/it_IT/mansection. Actually, the character set is not included because by default is ISO-8859-1. In order to actually use these language directories, it is necessary to have the LANG environment variable initialised with the value it_IT.

The directory which defines the architecture is also optional and is necessary only if some section contains manual pages for programs or other features which depends on architecural charcteristics.

747.2.2   /etc/man.config

The behaviour of man can be configured by using the file /etc/man.manconfig or /etc/manpath.config. Among other things, this file contains the arguments used with the programs called to format the text for display or printing. Notice the following extract:

TROFF           /usr/bin/groff -Tps -mandoc
NROFF           /usr/bin/groff -Tlatin1 -mandoc
EQN             /usr/bin/geqn -Tps
NEQN            /usr/bin/geqn -Tlatin1
TBL             /usr/bin/gtbl
# COL           /usr/bin/col
REFER           /usr/bin/grefer
PIC             /usr/bin/gpic
VGRIND          
GRAP            
PAGER           /usr/bin/less -is
CAT             /bin/cat

Something that it is useful, if you use foreign languages, is the option -T of nroff and of geqn. By using it as in the example (-Tlatin1), it allows to view the accented characters in the translated manual pages.

747.2.3   Using "man"

man [options] name...

The man program formats and prints to the standard output the manual page specified by name. The scrolling of the manual page text is done through an external program, called automatically by man. Usually this is either more or less. Consequently the commands to scroll the text depend on the type of used program. If it is one of the two discussed above, the commands listed in the table 747.1 are always valid.

Some options

section_number

If a number appears before the name of the command or of the argument, it means that one wants to get the manual page from a specific section, as described in the table 747.3.

-f

It works in the same way as whatis.

-h

It presents a short help guide on its use.

-k

It produces the same results asapropos.

Example

$ man ls[Enter]

It presents the manual page of the program ls.

$ man 8 lilo[Enter]

It presents the manual page in the eighth section, of the lilo program.

747.2.4   Using "whatis"

whatis parola...

It searches the page names of one or more manual pages for the names entered in the arguments. ⁽²⁾

The results of the search are directed to the standard output. Only full words are matched and displayed.

Examples

$ whatis ls[Enter]

It presents the descriptions that contain the word ls in the page name.

747.2.5   Using "apropos"

apropos string...

It finds the description of one or more manual pages which contain the argument string (the search is done only on the description, including the page name, and not on the content of the manual page)⁽³⁾

The search result is directed to the standard output.

Examples

$ apropos keyboard[Enter]

It presents the descriptions which contain the string keyboard.

747.3   Info

The Info documentation is an hypertext implemented by Info files and readable by using the info program or Emacs. The files of this hypertext are stored in the directory /usr/share/info/.

The Info documentation is organised in files which include nodes. Each node has a name and represents an information unit. Since this is an hypertextual system, each node may include references to other nodes which contain additional or connected information. Almost all nodes contain at least standard references defined from the following items:

• previous -- previous node;

• next -- next node;

• up -- parent node.

The other references can be organised in menus or 'cross-references'. Each Info file contains at least a main node: Top. The nodes are simply identified by using following notation:

[(info_file)][node_name]

If you refer only to the node name, you implicitely refer also to the corresponding file; if you refer only to the file name, you implicitely refer to the node name called Top.

747.3.1   Using "info"

info [options] [item...]

The info executable allows the inquiry of Info files without the need to use Emacs. In no argument has been entered and especially, if the Info file to be inquired has not been entered, the program opens the file /usr/share/info/dir.

Some options

--directory path

It specifies an affitional path to be used for the search of Info files.

-f file | --file=file

It specifies a specific file to be visited.

-n nodo | --node=nodo

It specifies a specific node to be visited.

Examples

$ info -f pippo[Enter]

It starts the display of the pippo file from its main node.

$ info -f pippo pappa[Enter]

It selects the menu option pappa that should be contained in the main node of the pippo file.

$ info -f info[Enter]

It starts the display of the info file from its main node.

$ info info[Enter]

It selects the menu option info from the main node of the dir file (/usr/share/info/dir) which is the predefined one.

747.3.2   Using the info executable

To access the information contained in these file with the info executable, you should know some commands that are not always intuitive. These commands are entered by simply pressing the key of the corresponding letter or symbol. Some of these commands require arguments that must be entered and followed by the [Entry] key. The most important commands can be found in the table 747.5.

When you use an hypertext, it is very important to know how you can backtrack. In this case, the command l allows to go back and is especially useful after the selection of an help command such as h or ?.

The picture 747.6 shows the main node of the info file, i.e. of the document which explains how this hypertext type works.

File: info,  Node: Top,  Next: Getting Started,  Prev: (dir),  Up: (dir)

Info: An Introduction
*********************

   Info is a program for reading documentation, which you are using now.

   To learn how to use Info, type the command `h'.  It brings you to a
programmed instruction sequence.  If at any time you are ready to stop
using Info, type `q'.

   To learn advanced Info commands, type `n' twice.  This brings you to
`Info for Experts', skipping over the `Getting Started' chapter.

* Menu:

* Getting Started::             Getting started using an Info reader.
* Advanced Info::               Advanced commands within Info.
* Create an Info File::         How to make your own Info file.

--zz-Info: (info.gz)Top, 20 lines --All----------------------------------------
Welcome to Info version 2.18. "C-h" for help, "m" for menu item.

The first top line contains especially the name of the file and of the node.

File: info, Node: Top,  Next: Getting Started,  Prev: (dir), Up: (dir)

The line before the last, the second from the bottom, displays again the name of the file and of the node, in addition to the node size expressed in rows and to the word All.

--zz-Info: (info.gz)Top, 20 lines --All-------------------------------

The word All means in this case that the node appears completely in the space provided by the screen or by the window. The last screen line is used to provide information to the user and to allow the entry of arguments possibly required by some command.

At the beginning of each node, together with the name of the file and of the node, there are some standard references (to other nodes). They are represented symbolically by the terms Next, Prev (previous) e Up (parent). The person who has defined the Info file has defined also which nodes can be referred to by the above words and accessible by using the corresponding commands n, p and u.

The Up reference does not always refer to a main node (Top) of the file that is inquired, but to a node that at that time, for some reason, represents a main reference. The same approach applies to the Next and Prev references that reflect only a temporary sequence.

The node text may be longer than the lines available on the screen or on the window. You can scroll the text by using the space bar to scroll down and the [Canc] key to scroll up. However you should pay attention: if too many scrolls are used, it continues with other nodes, by using a predefined path that usually does not reflect the Next and Prev references mentioned before.

An hypertext is useful to reach the desired information by using a non sequential path. The Info documents use two types of references (in addition to the standard ones): The menu and the cross references. The first ones appear as the text * Menu: plus a list of references; i.e. they are separated from the normal text. The cross references appear instead in the normal text and they are emphasised by the initials * Note Cross:.

The menu options can be selected by using the command m followed by the node name; the cross references can be selected by using the command f followed by the node name.

It is useful to have two different commands because the names may be entered in a short format (only a few letters), by entering only the latters that allow to distinguish them from other names. By separating the menu references from those that appear in the text, there are less possibilities of misanderstandings.

To simplify the selection of the references included in the text of a node (including the menu), you can use the [Tab] key to position the cursor at the beginning of the next item and the [Enter] key to select the node referred by the item where the cursor is positioned.

If you know exactly the name of a node that you want to reach, you can use the command g followed by the name of that node.

During the navigation within the Info documentation, it is always useful to remember the command l which allows to go back to the previous node.

747.4   Documentation enclosed with the packages

The packages of the most important programs are accompanied by documentation written in different ways (text, LaTeX, TeX, SGML, PostScript, etc.). It is normally located in a child subdirectory of /usr/share/doc/.

747.5   HOWTO

The HOWTO documents are not included as an integral part of the package, because they are additional guides with objectives that are wider that the simple documentation of a single package. Most of the GNU/Linux distributions include also the HOWTO documents. Usually they are installed in a child directory of /usr/share/doc/HOWTO/.

747.6   FAQ

Another source of GNU/Linux documentation is found in the FAQ or Frequently asked questions. They contain unordered information in a question and reply format. Usually they are stored in a child directory of /usr/share/doc/FAQ/.

747.7   LDP

Besides the standard documentation included more or less in all GNU/Linux distributions, there are complete books that are distributed for free. They are included in the LDP project, meaning Linux documentation project.

These documents, normally available both in PostScript and in HTML format, can be found from the <http://www.ibiblio.org/pub/Linux/docs/LDP/> and from corresponding mirror sites.

747.8   Other documentation

In addition to the documentation mentioned in the previous sections, there are other documents which can be found from the <http://www.ibiblio.org/pub/Linux/docs/> and from related mirror sites.

Special attention should be reserved to the following links.

• Gary's Encyclopedia

  <http://eupedia.org>

• Connected: An Internet Encyclopedia

  <http://www.freesoft.org/CIE/index.htm>

• Internet Requests for Comments

  <http://www.ietf.org/rfc/>

Appunti di informatica libera 2006.01.01 --- Copyright © 2000-2006 Daniele Giacomini -- <daniele (ad) swlibero·org>, <daniele·giacomini (ad) poste·it>

1) Translation last update on 2003.09.11 from Mario Pesce <mario (ad) datamission·co·uk>.

2) In the past the search was based on a database built by using the command makewhatis.

3) In the past, the search was done in a database built by using the command makewhatis.

It should be possible to link to this page also with the name documentation.htm

[next] [previous] [top] [last] [contents] [indice ridotto] [violazione licenza] [translators] [docinfo] [indice analitico]