IMPORTANT: Per accedir als fitxer de subversion: http://acacha.org/svn (sense password). Poc a poc s'aniran migrant els enllaços. Encara però funciona el subversion de la farga però no se sap fins quan... (usuari: prova i la paraula de pas 123456)

Aquesta pàgina és un recopilatori de diferents temes relacionats amb el manuals de Linux que apareixen en aquesta wiki

Instal·lació de manuals (man pages)

Per disposar dels manuals de les crides de sistema POSIX podeu instal·lar:

$ sudo apt-get install manpages-posix

La majoria de crides de sistema estan al paquet manpages-dev:

$ sudo apt-get install manpages-dev 

Si teniu dubtes de quin paquet es necessita per tenir cert manual podeu utilitzar la comanda dpkg i el fet de saber que els manuals es troben a:

/usr/share/man/manx

On x és la secció del manual. Sabem (o podeu consultar al manual de man - $ man man) que les crides de sistema estan a la secció 2. Per tant si volem saber qui ens proporciona el manual de fork:

$ dpkg -S /usr/share/man/man2/fork.2.gz 
manpages-dev: /usr/share/man/man2/fork.2.gz

Pàgines man i pàgines info

Consulteu Pàgines man (man pages) i pàgines info

Ordres

man

Linux proporciona un sistema d'ajuda basat en text al qual s'accedeix mitjançant l'ordre man. La comanda és l'abreviatura de manual.

La comanda ens proporciona ajuda sobre les comandes, fitxers de configuració, funcions i altres ítems del sistema.

De forma recursiva podeu utilitzar el propi man per consultar el manual de la comanda man:

$ man man

Man utilitza la comanda less, per tal de moure's pel manual. L'ús bàsic de less es mostrar el manual pàgina per pàgina, i podeu realitzar les següents accions un cop dins d'un manual:

  • Barra d'espai: mou una pàgina endavant
  • Esc+V: mou una pàgina enrera.
  • Fletza amunt/avall: moure amunt i a avall línia a línia.
  • Cerques: Tecla / (slash)
  • Sortir: tecla q

Per a més informació, pode consultar el manual de less:

$ man less

Els manuals de Linux estan organitzats en 9 categories. Les podeu trobar al manual de man i són:

1 --> Programes executables i ordres de l'interpret de comandes
2 --> Crides de sistema proporcionades pel kernel.
3 --> Crides a llibreries proporcionades per programes de llibreries
4 --> Fitxers de dispositiu (normalment emmagatzemats a /dev)
5 --> Formats de fitxers
6 --> Jocs
7 --> Miscel·lània (paquets macro, convencions...)
8 --> Ordres d'administració del sistema (programes que s'executen freqüentment o exclusivament per l'usuari root)
9 --> Rutines del kernel

A vegades una mateixa paraula té múltiples entrades. Per exemple la paraula passwd té múltiples entrades. Per defecte si no es diu el contrari es mostra l'entrada de la categoria amb el número més baix.

Per consultar la comanda passwd (categoria 1):

$ man 1 passwd 

Per consultar el fitxer de configuració :

$ man 5 passwd

També existeix la comanda info. Consulteu:

Pàgines_man_(man_pages)_i_pàgines_info

Tant els manuals com les pàgines info són documents de referència i no tutorials (com a màxim en algusn casos trobem exemples a la secció EXAMPLES).

Per a tutorials i documentació podeu consultar:

  • Les carpetes /usr/share/doc de cada paquet per veure si contenen documentació
  • Pàgines web d'Internet com The Linux Documentation Project (http://tldp.org).

Seccions d'una pàgina de manual

Les pàgines del manual electrònic es divideixen en diferents apartats, les més freqüents són:

  • NOM: Nom de la pàgina del manual seguit d’una descripció del contingut.
  • SINOPSIS: Sintaxis de la comanda amb les seves opcions i arguments. Els [] indiquen que la opció o l’argument és opcional i ... que la opció o l’argument anterior es poden repetir.
  • DESCRIPCIÓ: Descripció detallada de la comanda. Hi ha una explicació de les diferents opcions.
  • EXEMPLES: Exemples d’ús de la comanda.
  • VEURE TAMBÉ: Indica les altres pàgines del manual relatives al tema.
  • ERRORS: Conté les observacions respecte a les diferències que es poden trobar entre la comanda GNU de la pàgina consultada i la mateixa comanda en un altre sistema UNIX.

Buscar als manuals. Opció -k

L'opció -k ens permet buscar als manuals per paraula. Per exemple, podem buscar manuals relacionats amb les xarxes, buscant:

$ man -k network | head
/etc/network/interfaces (5) [interfaces] - network interface configuration for ifup and ifdown
aireplay-ng (1)      - inject packets into a wireless network to generate traffic
aseqnet (1)          - ALSA sequencer connectors over network
athstats (8)         - simple tool to inspect and monitor network traffic statistics
avahi-autoipd (8)    - IPv4LL network address configuration daemon
...

Aquesta opció busca als manuals que tenim instal·lats al sistema.

Manuals en castellà i altres idiomes

Es poden instal·lar els manuals en castellà amb:

$ sudo apt-get install manpages-es manpages-es-extra

Cal tenir en compte que el sistema us intentarà mostrar els manuals en el vostre idioma i sinó els troba els mostrarà en angles. Si utilitzeu una Ubuntu en català, no us mostrarà automàticament els manuals. Haureu d'executar:

$ export LANG=es_ES
$ man ping

En català, AFAIK, no hi ha manuals. Podeu trobar manuals de altres idiomes als repositoris. Executeu:

$ sudo apt-get install manpages

I en comptes de fer Enter tabuleu per tal de veure les opcions.

Per indicar l'idioma:

$ man -L es man

o

$ man --locale=es man

Manuals extres

Podeu trobar manuals extres als repositoris. Executeu:

$ sudo apt-get install manpages

I en comptes de fer Enter tabuleu per tal de veure les opcions que teniu. Per exemples:

$ sudo apt-get install manpages-es-extra manpages-posix manpages-posix-dev manpages-dev

whereis

Consulteu Comandes_bàsiques#whereis. Aquesta comanda ens permet localitzar manuals.

whatis

Segons el manual:

$ man whatis

Mostra les descripcions de les pàgines dels manuals. Per exemple:

$ whatis man
man (1)              - an interface to the on-line reference manuals
man (7)              - macros to format man pages
man (1posix)         - display system documentation

o

$ whatis passwd
passwd (1)           - change user password
passwd (1ssl)        - compute password hashes
passwd (5)           - the password file

L'ordre es proporciona pel paquet man-db':

$ dpkg -S /usr/bin/whatis
man-db: /usr/bin/whatis

GNU help

A més de les pàgines del manual i de la documentació info, les comandes GNU (totes les ordres de coreutils són de GNU i moltes altres ordres també) que es troben a Linux accepten habitualment la opció –help. Les comandes invocades amb aquesta opció tornen una ajuda esquemàtica que descriu la sintaxis general de la comanda i les opcions més utilitzades:

$ date --help
Forma d’ús: date [OPCIÓ]… [+FORMAT]
      o bé: date [-u|--utc|--universal] [MMDDhhmm[[CC]AA][.ss]]
Mostra la data actual en el FORMAT indicat, o estableix la data del sistema.

  -d, --date=CADENA    Mostra la data descrita a la CADENA en lloc de la data
                       actual («now», ara).
  -f, --file=FITXER_DATES
                       Com aplicar «--date» una volta per cada línia de
                       FITXER_DATES.
  -r, --reference=FITXER
                       Mostra la data de la darrera modificació del FITXER.
...


Aquesta ajuda resulta pràctica quan es coneix la comanda i es tenen dubtes sobre la sintaxis o el nom d’una opció.

/usr/share/doc

Els paquets Debian, i altres paquets com els rpm, segons l'estàndard FHS, guardant la documentació relacionada amb el paquet a:

/usr/share/doc/nom_paquet

Manuals a Internet

Ubuntu

Consulteu la pàgina:

http://manpages.ubuntu.com/

Us permet consultar els manuals de totes les versions d'Ubuntu. Les manuals poden canviar. Si busqueu la comanda shutdown el resultat de la cerca és aquí. Veureu que el manual ha canviat amb la introducció de upstart.

Com crear manuals de Linux?

Background

TODO:

2 Background

WoMan is a browser for traditional Unix-style manual page documentation. Each such document is conventionally referred to as a manual page, or man page for short, even though some are very much longer than one page.

A man page is a document written using the Unix “man” macros, which are themselves written in the nroff/troff text processing markup language. 
nroff and troff are text processors originally written for the UNIX operating system by Joseph F. Ossanna at Bell Laboratories, Murray Hill, New Jersey, USA. 
They are closely related, and except in the few cases where the distinction between them is important I will refer to them both ambiguously as roff.

Podeu consultar:

$ sudo apt-get install groff
$ man roff

roff markup consists of requests and escape sequences. A request occupies a complete line and begins with either a period or a single forward quote. An escape sequences is embedded within the input text and begins (by default) with a backslash. The original man macro package defines 20 new roff requests implemented as macros, which were considered to be sufficient for writing man pages. But whilst in principle man pages use only the man macros, in practice a significant number use many other roff requests.

The distinction between troff and nroff is that troff was designed to drive a phototypesetter whereas nroff was designed to produce essentially ASCII output for a character-based device similar to a teletypewriter (usually abbreviated to “teletype” or “tty”). Hence, troff supports much finer control over output positioning than does nroff and can be seen as a forerunner of TeX. Traditionally, man pages are either formatted by troff for typesetting or by nroff for printing on a character printer or displaying on a screen. Of course, over the last 25 years or so, the distinction between typeset output on paper and characters on a screen has become blurred by the fact that most screens now support bit-mapped displays, so that any information that can be printed can also be rendered on screen, the only difference being the resolution.

Nevertheless, Unix-style manual page documentation is still normally browsed on screen by running a program called man. This program looks in a predefined set of directories for the man page matching a specified topic, then either formats the source file by running nroff or recovers a pre-formatted file, and displays it via a pager such as more. nroff normally formats for a printer, so it paginates the output, numbers the pages, etc., most of which is irrelevant when the document is browsed as a continuous scrollable document on screen. The only concession to on-screen browsing normally implemented by the man program is to squeeze consecutive blank lines into a single blank line.

For some time, Emacs has offered an improved interface for browsing man pages in the form of the Emacs man (or manual-entry) command, see man. This command runs man as described above, perhaps in the background, and then post-processes the output to remove much of the nroff pagination such as page headers and footers, and places the result into an Emacs buffer. It puts this buffer into a special major mode, which is tailored for man page browsing, and provides a number of useful navigation commands, support for following references, etc. It provides some support for special display faces (fonts), but no special menu or mouse support. The Emacs man package appears to have been developed over about 10 years, from the late 1980s to the late 1990s.

There is considerable inefficiency in having nroff paginate a document and then removing most of the pagination!

WoMan is an Emacs Lisp library that provides an emulation of the functionality of the Emacs man command, the main difference being that WoMan does not use any external programs. The only situation in which WoMan might use an external program is when the source file is compressed, when WoMan will use the standard Emacs automatic decompression facility, which does call an external program.

I began developing WoMan in the Spring of 1997 and the first version was released in May 1997. The original motivation for WoMan was the fact that many GNU and Unix programs are ported to other platforms and come with Unix-style manual page documentation. This may be difficult to read because ports of the Unix-style man program can be a little awkward to set up. I decided that it should not be too hard to emulate the 20 man macros directly, without treating them as macros and largely ignoring the underlying roff requests, given the text processing capabilities of Emacs. This proved to be essentially true, and it did not take a great deal of work to be able to format simple man pages acceptably.

One problem arose with the significant number of man pages that use roff requests in addition to the man macros, and since releasing the first version of WoMan I have been continually extending it to support more roff requests. WoMan can now format a significant proportion of the man pages that I have tested, either well or at least readably. However, I have added capabilities partly by making additional passes through the document, a design that is fundamentally flawed. This can only be solved by a major re-design of WoMan to handle the major formatting within a single recursive pass, rather than the present multiple passes without any significant recursion. There are some roff requests that cannot be handled satisfactorily within the present design. Some of these are currently handled by kludges that “usually more or less work.”

The principle advantage of WoMan is that it does not require man, and indeed the name WoMan is a contraction of “without man.” But it has other advantages. It does not paginate the document, so it does not need to un-paginate it again, thereby saving time. It could take full advantage of the display capabilities available to it, and I hope to develop WoMan to take advantage of developments in Emacs itself. At present, WoMan uses several display faces to support bold and italic text, to indicate other fonts, etc. The default faces are also colored, but the choice of faces is customizable. WoMan provides menu support for navigation and mouse support for following references, in addition to the navigation facilities provided by man mode. WoMan has (this) texinfo documentation!

WoMan does not replace man, although it does use a number of the facilities implemented in the Emacs man library. WoMan and man can happily co-exist, which is very useful for comparison and debugging purposes.

nroff simulates non-ASCII characters by using one or more ASCII characters. WoMan should be able to do much better than this. I have recently begun to add support for WoMan to use more of the characters in its default font and to use a symbol font, and it is an aspect that I intend to develop further in the near future. It should be possible to move WoMan from an emulation of nroff to an emulation of troff as GNU Emacs moves to providing bit-mapped display facilities.

groff

Per instal·lar groff

$ sudo apt-get install groff

Ens permet consultar com es mostren el fitxer de manual a partir del seu original

$ groff -Tascii -man /home/profe/development/p/bashdebianesqueleton-0.1/debian/manpage.1.ex

També podeu utilitzar:

$ nroff -man /home/profe/development/p/bashdebianesqueleton-0.1/debian/manpage.1.ex

NOTA: consulteu Creació de paquets Debian

IMPORTANT: Sembla ser que groff/nroff no sap treballar amb fitxers UTF-8 (TODO) (tot i que es pot indicar amb -Tutf8). Si poseu la codificació del fitxer manpage.1.ex a iso-8859-1 acceptarà accents correctament

Proporciona infinitat de binaris:

$ dpkg -L groff | grep bin
/usr/bin
/usr/bin/grn
/usr/bin/refer
/usr/bin/pre-grohtml
/usr/bin/grodvi
/usr/bin/grolj4
/usr/bin/post-grohtml
/usr/bin/grolbp
/usr/bin/tfmtodit
/usr/bin/hpftodit
/usr/bin/lookbib
/usr/bin/indxbib
/usr/bin/lkbib
/usr/bin/addftinfo
/usr/bin/pfbtops
/usr/bin/gxditview
/usr/bin/xtotroff
/usr/bin/afmtodit
/usr/bin/mmroff
/usr/bin/chem
/usr/bin/pic2graph
/usr/bin/eqn2graph
/usr/bin/grap2graph
/usr/bin/groffer
/usr/bin/roff2dvi
/usr/bin/roff2html
/usr/bin/roff2pdf
/usr/bin/roff2ps
/usr/bin/roff2text
/usr/bin/roff2x
/usr/bin/pdfroff
/usr/bin/gdiffmk

Docbook

Mom

Exemple de creació de paquets Debian amb manuals

Consulteu l'article Creació de paquets Debian concretament l'exemple del Servidor d'ecos.

Vegeu també