Creazione di una man page sotto Linux

Sommario

Una pagina di manuale detta « man » è l'elemento indispensabile di un programma. In effetti, essa fornisce le informazioni essenziali riguardo l'uso di un programma e necessita poco spazio sul disco. questo articolo vi permetterà di realizzare la votra pagina di manuale molto velocemente.

Avvertenza

Questo articolo non è destinato a spiegarvi l'uso di ogni macro macro, per maggiori informazioni,consultare la pagina di manuale denomminata groff_man(7)

Introduzione

Un buon programma è sempre munito di una documentazione. in effetti il manuale è l'elemento essenziale e indispensabile per l'utente finale. Imaginate la prima reazione di un utente se quello si trova nell'incapacita di capirne il funczionnamento !!! Scrivere un manuale d'uso, è semplice, occupa pochissimo spazio, possibilità di converzione nei formati correnti. Iniziamo questo How-To con la presentazione di una pagina di manuale " man page".

Presentazione

Le rubriche

queste sone le rubriche principali di un pagina di manuale :

  • Nome

Nome del programma usato.

  • Synopsis

qui si trovano la sintassi del comando del programma, le opzioni e i i parametri.

  • Description

Utilizzazione del programma.

  • Options

Tutte le opzioni usate dal programma e la loro descrizione.

  • Examples

Esempio d'utilizzazione dell'applicazione.

  • Autore

La persona che ha realizzazato l'applicazione.

  • Bugs

Permette di segnalare in caso di errore.

  • Copyright

I diritti di autore.

  • Disponibilità

Generalmente il sito in cui è ossibile scaricare l'applicazione.

  • Files

Lista dei file utilizzati dall'applicazione.

  • See also

Elenca i programma che hanno un link diretto con l'applicazione.

  • History

Storia delle modifiche del programma.

Le macro

Il linguaggio utilzzato per realizzare un manuale è relativamente semplice:i termini usati innizianno tutti con un punto e sonno noti come macro. Qui sotto è riportata una lista esaustiva delle macro con le relative funzioni. Macro (struttura del documento)

  • .DT - (Tabulazione predefinita)
  • .HP - (Inizio d'indentation)
  • .IP - (Inizio paragrafo con parola chiave alla riga seguente)
  • .TP - (Inizio paragrafo con parola chiave sulla stessa riga)
  • .LP - (Inizio di un nuovo paragrafo)
  • .PD - (Imposta la distanza al valore passato in parametro)
  • .PP - (Iniziare un nuovo paragrafo)
  • .RE - (Fine d'indentation relativa (in un nuovo paragrafo))
  • .RS - (Inizio d'indentation relativa (in un paragrafo))
  • .SS - (Sotto-titolo ma per una sotto sezione)
  • .SH - (Sotto-titolo)
  • .TH - (Tittolo sezione data sorgente manuale)
  • ." - (Commento su una riga)

Macro (font per i caratteri)

  • .B - (Grassetto)
  • .BI - (Gras alternato con Corsivo)
  • .BR - (Grassetto alternato con Roman)
  • .I - (Corsivo)
  • .IB - (Corsivo alternato con Grassetto)
  • .IR - (Corsivo alternato con Roman)
  • .RB - (Roman alternato con Grassetto)
  • .RI - (Roman alternato con Corsivo)
  • .SB - (Small alternato con Grassetto)
  • .SM - (Small)

Tutte quelle macro di formattazione sono riperibili nella pagine di manuale intittolata groff_man(7)

Il comando groff

Il pacchetto groff include molti programmin per l'elaborazione e la formattazione del testo. Groff traduce testo e comandi specifici in output formatatto, esttamente come visualizzate su una man page.

Lo script nroff

Lo script nroff emula il comando nroff utilizzando groff.

Il comando man2html

Permette di convertire le man page in formato HTML.

Esempio pratico

Stesura del manuale

Ora è tempo di mettere in pratica le nozioni acquisite sulle macro. supponiamo di aver realizzato un programma per il VoIP chimato "myvoip", il comando myvoip omonimo del programma consente di effettuare chiamate verso numeri di ret fissa o di cellulare con le funzionalità di un normale telefono. Qui sotto è riportata la lista delle macro da utilizzare:

  • .TH - (Intestazione del manuale)
  • .SH - (Titolo)
  • .SS - (Sotto-titolo)
  • .TP - (Indenta il testo)
  • .PP - (Nuova riga)
  • ." - (Commento su una riga)
  • .B - (Carattere in grassetto)

Ora edittiamo il nostro file utilizzando "vi", digittando : 

  vi myvoip.1

Prendete il tempo necessario per digitare il seguente codice: 

.TH myvoip 1 "Ottobre 17, 2006" "version 1.0" "Manuale utente"
.SH NOME
yvoip \- Chiamare nel modo più semplice.
.SH SYNOPSIS
.B myvoip
[\-f] [\-p] \-ssl ssl invocato
.SH DESCRIPTION
Il programma
.B myvoip
permette di chiamare i vostri amici nel modo più semplice,con funzionaltà di un telefone tradizionale 
faccendovi dimenticare per sempre il cellulare e il telefono fisso.
.PP
Sè non ci sono parametri, la chiamata verrà effetuata automaticamente verso un telefono fisso.
.PP
L'opzione
.B -f
la chiamate vien rediretta verso un telefono fisso.
Per contattare un vicino sul cellulare l'opzione
.B -p
deve'esere passata.
.PP
SSL invocato viene utilizzato per criptare il vostro numero di telefono
in modo che nessuno possa ottenre il votro numero per
questo l'opzione
.B -ssl
dev'esser passata in parametro.
.SH OPTIONS
.TP
.B -f
Chiamata verso un numero fisso.

Prima di proseguire, ricordatevi di verificare il vostro lavoro prima di finalizzarlo digittando: 

   nroff -man myvoip.1 | less

oppure 

 groff -Tascii -man myvoip.1 | less

Ora proseguiamo con la formattazione del documento : 

.TP
.B -p
Chiamta verso un cellulare.
.TP
.B -ssl
Attivazione di ssl invocato.
.SH FILES
.SS DIPENDENZE
.B myvoip
richiede la libreria
.B libmMyvoip
scaricabile su :
ftp.chrix.org/lib/libMyvoip/
.TP
/usr/bin/
.B myvoip
.TP
/usr/share/man/man1
.B myvoip.1.gz
.TP
/usr/share/doc/myvoip-1.0/
.B ChangeLog
.B COPYING
.B INSTALL
.B README
.SH EXAMPLES
.TP
Chiamata verso un fisso:
.B myvoip
.B -f
.TP
Chiamata verso un cellulare:
.B myvoip
.B -p
.TP
Chiamata verso un fisso con ssl invocato:
.B myvoip
.B -f -ssl
.TP
Chiamata verso un cellulare con ssl invocato:
.B myvoip
.B -p -ssl
.SH AUTORI
Christian Eric ( chrix (at) slacky.it )
.SH BUGS
In caso di malfunzionamento, inviare una mail a 
bug-myvoip@chrix.org,
specificando il numero di errore e la versione del 
programma in uso.
.SH COPYRIGHT
Copyright 2005-2006 Free Software Foundation, Inc.
.PP
myvoip is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as
published by the Free Software Foundation; either version 2, or
(at your option) any later version.
.PP
myvoip is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as
published by the Free Software Foundation; either version 2, or
any later version.
.PP
myvoip is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
See the GNU General Public License for more details.
.PP
You should have received a copy of the GNU General Public License
along with groff; see the file COPYING. If not, write to the Free
Software Foundation, 49 Temple Place - Suite 330, Boston, MA
02111-1307, USA.
.SH DISPONIBILITA'
La versione la più recente di myvoip è scaricabile via 
ftp all'indirizzo: ftp.chrix.org/download/myvoip.

Risultato finale

Ora si può procedere all'installazione del manuale.

  • Ogni pagina di di manuale dev'essere compattato in .gz.

Per compattare il nostro file utilizzeremo il comando gzip: 

gzip myvoip.1
  • Ora da root copiare il file in /usr/share/man/man1, come segue: 
cp myvoip.1.gz /usr/share/man/man1
  • Ora il file è accessibile, potete usare il vostro emulatore di terminale preferito per visualizzarlo: 
man myvoip

Conversione in formati diversi

Nostro mauale ultimato, possiamo adattarlo ai formati più usati quali file "txt", "postscript" e "HTML". Per fare ciò useremo lo script "nroff" e i comandi "groff" e "man2html".

  • Formato (txt) con nroff : 
   nroff -man myvoip.1 | col -b > myvoip.txt
  • Formato (PostScript) con groff : 
   groff -man -Tps myvoip.1 > myvoip.ps
  • Formato (HTML) con man2html :

man2html myvoip.1 > myvoip.html

Bibliografia

  • Jens Schweikhardt. The Linux Man Page Howto.
  • Man2html. Manual page Man2html.

Conclusione

Spero che questo articolo vi darà le basi necessarie all'elaboration dei vostri manuali. questo documento non è una guida completa, ma uno strumento che vi aiuterà a realizzare velocemente una man page.

Glossario

  • gnu

GNU is Not Unix.

  • groff

Groff traduce testo e comandi in output formattato.

  • gzip

Permette di compattare file.

  • linux

OS Open Source.

  • ls

Lista il contenuto della directory corrente.

  • man

Visualizza tutta la documentazione relativa ad un comando.

  • macro

consente la formattazione di un manuale unix.

  • man2html

Converte le pagine di manuale in format HTML.

  • nroff

Formatta le man page, emula il comando nroff utilisando groff.

  • su

Consente un acesso all'account root e ad altri account del sistema.

  • vi

Editore di testo per Linux.

Autore

2006 Chrix. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. Read the full license to : gnu general public license 

                                        http://christian.africa-web.org/