Se ne povu deloki vin ĝis la fino de la sekva teksto, ĝi premas tie.
|
![[LinuxFocus-icon]](images/pagesman/logolftop_319x45.gif){kind=small}
 |
|
![[Photo of the Author]](images/pagesman/Guido-S.gif)
Per Guido Socher (homepage) La aŭtoro: Guido amas Linux ĉar estas tre supla mastruma sistemo, kiu proponas multe pli da ebloj ol ajna alia. Tradukita en franco per: Christophe Bénard <Christophe.BENARD(at)wanadoo.fr> Maldetala: |
Skribi paĝojn de lernolibro
Resumo:
Tute @bon uzebla programo ekde la ŝelo de Unikso devus
esti dokumentita kun liaj puraj paĝoj de lernolibro (man-paĝoj).
Tiu *tutoriel konstituas rapidan enkondukon al la skribo de
tiuj paĝoj.
|
Enkonduko
La dokumentado kalkulas ofte pli ke la programaro li mem, aparte se tiu programara devas esti uzita de aliaj personoj kiuj la aŭtoro. Kvankam mi skribas programon kiu mi ne konsideras publikigi, mi redaktas dokumentadon ĉar kelkaj monatoj poste, mi povus esti forgesinta kiel uzi lin, kaj dokumentado bone strukturita indikos min en kelkaj sekundoj kiel fari pri tio uzon.La *utilitaires tradiciaj uzeblaj en linio de komisioj sub Linux ĉiam estis dokumentitaj sub la formo de paĝoj de lernolibro. Simpla man nomo_de_komisio klarigas vin kiel uzi la komision.
La avantaĝo de la paĝoj de lernolibro sur ĉiuj aliaj formoj de dokumentado oriento kiu
- Ili povas esti afiŝitaj en kelkaj sekundoj sur ajna terminalo Linux
- Ili povas esti facile igitaj pri tio de aliaj formatoj: HTML, PDF, Postscript, Text,...
- La paĝoj de mana povas esti legitaj, ne nur en fenestro de terminalo, sed ankaŭ kun aliaj programoj kiel konqueror (frapu justan: man:nomo_de_komisio)
La sekcioj
La paĝoj de lernolibro estas strukturitaj en sekcioj, ĉiu kiel libro estas strukturita en ĉapitroj. Ekzistas ekzemple du paĝoj de lernolibro sur printf. La unu koncerne la funkcio de la librejo C (sekcio 3) kaj la alia pri la komisio de ŝelo printf (sekcio 1):> whichman -0 printf /usr/share/man/man1/printf.1.bz2 /usr/share/man/man3/printf.3.bz2La malsamaj sekcioj estas la sekvaj:
Sekcio
1 Komisioj de la nivelo de la uzanto
2 Alvokoj sistemo, tio estas, funkcioj proponitaj
de la kerno.
3 Sub-rutinoj, tio estas, funkcioj de librejo.
4 Aparatoj, tio estas, specialaj
dosieroj kiel la enirejoj de /dev.
5 Priskriboj de formato de dosieroj, ekzemple /ktp/passwd.
6 Ludoj, mem-dokumentado.
7 Diversaj, ekzemple *package de lingvo, konvencioj.
8 Iloj de administracio kiu sola root povas ekzekuti.
9 Alia
n freŝdataj Dokumentadoj, kiuj povus esti
delokitaj al sekcio pli proprigita.
l loka Dokumentado referencante tiun
sistemon aparte.
Sekve, frapi "man 1 printf" afiŝos la relativan
dokumentadon al la komisio de ŝelo printf dum "man 3 printf"
afiŝos la priskribon de la funkcio de la librejo C. Limigante la
konfiskon al "man printf" oni afiŝos la unuan paĝon
trovitan (ĝenerale, la sekcio 1 de printf).
Por kontroli se ekzistas pluraj versioj de paĝoj
de lernolibro, oni povas uzi la komision whichman, kiel indikita ĉi-supro
(malŝarĝo ekde
mia hejmpaĝo), aŭ ĝuste
frapi "man:printf" en konqueror, tio kio indikos vin:
MANPATH
La komisio man serĉas la paĝojn de lernolibro bazante sin sur la valoro de la variablo de medio MANPATH. Bedaŭrinde en @de nombreux distribuoj Linux, tiu vojo estas pravalorizita de malĝusta maniero. Ofte /usr/lib/perl5/man, kiuj permesas la aliron al abunda dokumentado sur ĉiuj funkcioj perl , ne estas inkludita. Vi povas aldoni lin al MANPATH (en la dosiero .bashrc aŭ .tcshrc aŭ ...) de tiu maniero:Bash: MANPATH="/usr/local/man:/usr/man:/usr/share/man:/usr/X11R6/man:/usr/lib/perl5/man" export MANPATH Tcsh: setenv MANPATH "/usr/local/man:/usr/man:/usr/share/man:/usr/X11R6/man:/usr/lib/perl5/man"Post esti pravalorizinta la vojon de aliro al la paĝoj de lernolibro, vi povas provi "man Pod::Man" por vidi se vi atingas unu el la paĝoj koncerne perl .
La ŝlosilaj vortoj de formato
Skribi paĝon de lernolibro estas tre facila. @S'agir pri simpla lingvo de kiu la vortoj ŝlosiloj uzitaj kiel buoj komencas per punkto en komenco de ĉiu linio. Tiuj vortoj ŝlosiloj estas ankaŭ nomitaj makrooj. La plej gravaj makrooj estas:.TH -> enkondukita la titolo/obstinas lin de la paĝo de lernolibro .SH -> Sekcio obstinas .PP -> Nova alineo ." -> Linio de komento .TP -> Deŝovas la tekston kiu venas 2 liniojn post tiun makroon
La sintakso de .TH estas:
.TH [nomo de la programo] [numero de sekcio] [centro de la piedo de paĝio] [maldekstra sekcio de la piedo de paĝio] [centra sekcio de obstinas lin]
La sintakso de .SH estas:
.SH teksto de la titolo
La sintakso de .PP estas tre simpla. Ŝi produktas ĝuste salton de linio.
Mi trovas foje oportuna enmeti antaŭ tekston-formatita por afiŝi de la ekzemploj de kodoj de programoj. Jen kiel procedi:
.nf _via_antaŭ_teksto-formatita_ _tie ĉi_____ .fiNotas ke tio estas makrooj groff/nroff kaj sekve, ke ili ne apartenas al la specifaj makrooj al la redakto de paĝoj de lernolibro. Ŝajnus tamen ili funkcias ĝuste sur ĉiuj sistemoj Unikson.
Ĉiuj makrooj de formato de paĝio de lernolibro estas dokumentitaj en la paĝo de lernolibro nomita groff_man(7) (Klaku tie ĉi por vidi la version html de la paĝo de lernolibro de groff_man(7)). Mi ne iras klarigi tie ĉi la uzon de la makrooj, sed mi sugestas vin pli ĝuste legi la paĝon groff_man. La paĝo groff_man estas tre detala kaj enhavas ĉion kio vi bezonas scii.
La ĉapitroj
Antaŭ ol komenci skribi vian puran paĝion de lernolibro, vi devas scii ke la paĝoj de lernolibro estas normale strukturitaj en ĉapitroj. Jen la listo de la titoloj de ĉapitroj kiuj, per konvencio, vi povas uzi:NAME Sekcio koncerne la nomo de la funkcio aŭ de la komisio.
SYNOPSIS Uzo.
DESCRIPTION Ĝenerala Priskribo
OPTIONS Devas indiki la eblojn kaj parametrojn.
RETURN VALUES Alvokoj de funkcio de la sekcioj du kaj tri.
ENVIRONMENT Priskribas la variablojn de medio.
FILES Dosieroj asociitaj al la afero.
EXAMPLES Ekzemploj kaj sugestoj.
DIAGNOSTICS Normale uzita por la sekcio 4 diagnozas de la
interfacoj de periferiaj.
ERRORS Sekcioj du kaj tri mastrumado de eraro kaj de signalo.
SEE ALSO krucaj Referencoj kaj citaĵoj.
STANDARDS Konformeco al la normoj, tiel estas aplikebla.
BUGS Kaptiloj kaj avertoj.
SECURITY CONSIDERATIONS
Konsideroj ligita al
la sekureco de kiu necesas esti informita.
other De obstinas lin tajloritaj povas esti
aldonitaj, al la bontrovo de la aŭtoro.
Ekzemplo de paĝio de lernolibro
Jen malgranda ekzemplo de paĝio de lernolibro. Li invitas noti ke lin \- estas postulita por distingi la demarĝenigon de la trajtoj de unuiĝo. Kaptas ĉion kio sekvas gracon kun via eldonisto de teksto, kaj enskribas la dokumenton sub la nomo cdspeed.1..TH cdspeed 1 "September 10, 2003" "version 0.3" "USER COMMANDS" .SH NAME cdspeed \- decrease the speed of you cdrom to get faster access time .SH SYNOPSIS .B cdspeed [\-h] [\-d device] \-s speed .SH DESCRIPTION Modern cdrom drives are too fast. It can take several seconds on a 60x speed cdrom drive to spin it up and read data from the drive. The result is that these drives are just a lot slower than a 8x or 24x drive. This is especially true if you are only occasionally (e.g every 5 seconds) reading a small file. This utility limits the speed and makes the drive more responsive when accessing small files. .PP cdspeed makes the drive also less noisy and is very useful if you want to listen to music on your computer. .SH OPTIONS .TP \-h display a short help text .TP \-d use the given device instead of /dev/cdrom .TP \-s set the speed. The argument is a integer. Zero means restore maximum speed. .SH EXAMPLES .TP Set the maximum speed to 8 speed cdrom: .B cdspeed \-s 8 .PP .TP Restore maximum speed: .B cdspeed \-s 0 .PP .SH EXIT STATUS cdspeed returns a zero exist status if it succeeds to change to set the maximum speed of the cdrom drive. Non zero is returned in case of failure. .SH AUTHOR Guido Socher (guido (at) linuxfocus.org) .SH SEE ALSO eject(1)Klakas tie ĉi (cdspeed.html) por bildigi la paĝon priskribitan ĉi-supro.
Bildigi kaj formati vian paĝion de lernolibro
Dum vi skribas vian paĝion de lernolibro, vi povas, de tempo al tempo, bildigi ŝin por kontroli ke ŝi estas ĝusta. Frapas:nroff -man via_paĝio_de_lernolibro.1 | lessaŭ
groff -man -Tascii via_paĝio_de_lernolibro.1 | lessPor igi paĝon de lernolibro en antaŭ ebena teksto-formatita (por kontroli la ortografion ekzemple), uzas la komision:
nroff -man via_paĝio_de_lernolibro.1 | kolo -b > xxxx.TxtPor igi ŝin al la formato Postscript (por presi lin aŭ igi ŝin al la formato pdf), uzas la komision:
groff -man -Tps via_paĝio_de_lernolibro.1 > your_manpagefile.psPor igi la paĝon de lernolibro al la formato html, uzas la komision:
man2html via_paĝio_de_lernolibro.1
Uzi perl POD por generi de la paĝoj de lernolibro
Mi scias ke @nombreux estas tiuj kiuj trovas stranga koncipi paĝon de lernolibro kun eldonisto de teksto. Ili preferas generi la paĝon de lernolibro. La formato de dokumentado perl POD konstituas @bon elekton. Estas eble skribi la paĝon uzante la sintakson POD poste lanĉi la komisionpod2man via_paĝio_de_lernolibro.pod > via_paĝio_de_lernolibro.1La sintakso de la lingvo de dokumentado perl pod estas priskribita en paĝo de lernolibro titolita perl pod. La ekzemplo de paĝio de lernolibro ĉi-supre similus al tio kio sekvas en la formato pod. Necesas noti ke POD estas sentema al la spacoj kaj ke la malplenaj linioj ĉirkaŭ "=head" estas same necesaj.
=head1 NAME
cdspeed - decrease the speed of you cdrom to get faster access time
=head1 SYNOPSIS
cdspeed [-h] [-d device] -s speed
=head1 DESCRIPTION
Modern cdrom drives are too fast. It can take several seconds on a 60x
speed cdrom drive to spin it up and read data from the drive. The result
is that these drives are just a lot slower than a 8x or 24x drive.
This is especially true if you are only occasionally (e.g every 5 seconds)
reading a small file. This utility limits the speed and makes the drive
more responsive when accessing small files.
cdspeed makes the drive also less noisy and is very useful
if you want to listen to music on your computer.
=head1 OPTIONS
B<-h> display a short help text
B<-d> use the given device instead of /dev/cdrom
B<-s> set the speed. The argument is a integer. Zero
means restore maximum speed.
=head1 EXAMPLES
Set the maximum speed to 8 speed cdrom:
cdspeed -s 8
Restore maximum speed:
cdspeed -s 0
=head1 EXIT STATUS
cdspeed returns a zero exist status if it succeeds to
change to set the maximum speed of the cdrom drive. Non
zero is returned in case of failure.
=head1 AUTHOR
Guido Socher
=head1 SEE ALSO
eject(1)
Referencoj
Diskutado sur tiu artikolo
Ĉiu artikolo posedas lian paĝon de diskutado. Vi povas submeti tie komenton aŭ legi tiujn de aliaj legantoj:
|
<--, Reveno al la enhavtabelo de tiu numero
|
Loko Retejo tenita de la teamo de eldono LinuxFocus
© Guido Socher, FDL LinuxFocus.org |
Translacio informo:
|
2003-11-09, generated by lfparser version 2.42