Provided by:
manpages-cs_0.17.20080113-1_all 
JMÉNO
man - makra pro formátování manuálových stránek.
SYNTAXE
groff -Tascii -man file ...
groff -Tps -man file ...
man [sekce] nzev
POPIS
Tato manuálová stránka popisuje makro balík groff an.tmac (často
nazývaný jako makro balík man). Tento balík maker by měli používat
vývojáři při psaní nebo přenosu manuálových stránek pro Linux. Je
celkem kompatibilní s ostatními verzemi tohoto makro balíku, a proto by
přenos manuálových stránek z jiných systémů neměl být problémem
(výjimkou je NET-2 BSD, který používá úplně jiný makro balík zvaný
mdoc; viz mdoc(7)).
NET-2 BSD manuálové stránky mohou být používány programem groff
jednoduše, pokud použijeme volbu -mdoc místo standardní volby -man.
Doporučujeme ale používat volbu -mandoc, protože ta automaticky
rozezná, který makro balík má použít.
PREAMBULE
Konvence, které by měly být použity při psaní manuálových stránek v
balíku man-pages, jsou uvedeny v man-pages(7).
Titulní řádka
První příkaz manuálové stránky (po komentářích, tj. řádcích
začínajících na .\") by měl být
.TH titulek sekce datum zdroj manul
Více informací o parametrech, které mohou být předány příkazu TH, je
uvedeno v man-pages(7).
Pozor, BSD manuálové stránky formátované mdoc začínají příkazem Dd,
nikoliv příkazem TH.
Sekce
Sekce začínají příkazem .SH následovaným názvem dané sekce. Jediná
povinná sekce je JMÉNO, měla by být první a za ní by měl následovat
jednořádkový popis programu:
.SH JMÉNO
Je velmi důležité dodržet tento formát, zejména uvádění zpětného
lomítka před pomlčkou, za níž je uvedeno jméno příkazu, protože tato
syntaxe je použita programem makewhatis(8) k vytvoření databáze
zkrácených popisů příkazů pro příkazy whatis(1) a apropos(1).
Seznam dalších sekcí, které se mohou v manuálové stránce vyskytnout, je
uveden v man-pages(7).
Fonty
Příkazy pro nastavení řezu písma:
.B Tučné
.BI Tučné střídající se s kurzívou (zvláště užitečné pro specifikace
funkcí)
.BR Tučné střídající se s normálním (zvláště užitečné pro odkazy na
ostatní manuálové stránky)
.I Kurzíva
.IB Italika střídající se s tučným
.IR Italika střídající se s normálním
.RB Normální střídající se s tučným
.RI Normální střídající se s kurzívou
.SB Malé střídající se s tučným
.SM Malé (užitečné pro zkratky)
Tradicí bylo, že každý příkaz mohl mít až šest argumentů, ale GNU verze
odstranila toto omezení. Argumenty jsou odděleny mezerami. Uvozovky
použijeme chceme-li specifikovat argument, který obsahuje mezery.
Všechny argumenty budou vytištěny bez mezer hned za sebe, a proto může
být příkaz .BR použit pro vytištění tučného slova následovaného
interpunkční značkou v normálním písmu. Pokud není uveden žádný
argument, aplikuje se příkaz na následující řádek textu.
Další makra a řetězce
Níže jsou uvedena další související makra a předdefinované řetězce.
Pokud není uvedeno jinak, všechna makra způsobují zlom (konec aktuální
rádky textu). Mnoho z těchto maker nastavuje nebo užívá "obecné
odsazení". Hodnota "obecné odsazení" je nastavena makrem s parametrem
i níže; makro může i vypustit, v tom případě bude užito aktuální obecné
odsazení. Výsledkem je, že po sobě jdoucí odsazené odstavce mohou
používat stejné odsazení bez nutnosti jeho hodnotu opakovaně
nastavovat. Obyčejný (neodsazený) odstavec obnoví hodnotu obecného
odsazení na výchozí hodnotu (0.5 palce) Jako výchozí jednotka odsazení
je použito en; jako jednotky používejte nejlépe en nebo em, protože se
automaticky přizpůsobují změně velikosti fontu. Další základní makra
jsou:
Normální odstavce
.LP Stejné jako .PP (začni odstavec).
.P Stejné jako .PP (začni odstavec).
.PP Začni odstavec a obnov obecné odsazení.
Relativní hranice odsazení
.RS i Začátek relativní hranice odsazení: posune levý okraj i
doprava (pokud je i vynecháno, použije se hodnota obecného
odsazení). Nové obecné odsazení je nastaveno na 0.5 palce.
Výsledkem je, že všechny následující odstavce budou odsazeny
až do odpovídajícího .RE.
.RE Ukončí relativní hranici odsazení a obnoví předchozí hodnotu
obecného odsazení.
Makra pro odsazené odstavce
.HP i Začne odstavec s visícím odsazením (první řádek začíná vlevo
stejně jako normální odstavce, ostatní řádky jsou odsazeny).
.IP x i Odsazený odstavec s volitelnou visící značkou. Pokud je
značka x vynechána, je celý následující odstavec odsazen o i.
Pokud je značka x přítomna, je pověšena na levém okraji před
následujícím odsazeným odstavcem (je to stejné jako .TP,
akorát je značka uvedena s příkazem, místo aby byla na
následující řádce). Pokud je značka příliš dlouhá, je text,
který po ní následuje, posunut dolů na další řádku (text
nezmizí ani se nezkomolí). Pro seznamy s odrážkami se toto
makro používá se značkami \(bu (bullet) nebo \(em (em dash),
pro číslované seznamy je pak značkou číslo nebo písmeno
následované tečkou; to zjednodušuje převod do jiných formátů.
.TP i Začne odstavec s visící značkou. Značka je uvedena na
následující řádce, ale výsledek je stejný jako u příkazu .IP.
Makra hypertextových odkazů
(Vlastnost podporovaná pouze programem groff.) Aby bylo možné používat
makra hypertextových odkazů, je nutné nahrát balíček maker www.tmac.
Použijte k tomu volání .mso www.tmac
.URL url odkaz trailer
Vloží hypertextový odkaz na URI (URL) url, s odkazem jako
textem odkazu. Bezprostředně za ním bude vytištěn trailer.
Při tvorbě HTML by se to mělo přeložit do HTML příkazu <A
HREF="url">odkaz</A>trailer.
Toto a další makra jsou nové a mnoho nástrojů je neumí použít,
ale protože nedefinovaná makra většinou ignorují (nebo je
přinejhorším vloží jako text), je možné jej bezpečně použít.
Může být užitečné definovat vlastní makro URL v manuálových
stránkách pro blaho těch, kde je prohlížejí jiným prohlížečem
roff, než je groff. Tak budou URL, text odkazu a text
traileru (pokud je) stále viditelné.
Příklad:
.de URL
\\$2 \(laURL: \\$1 \(ra\\$3
..
.if \n[.g] .mso www.tmac
.TH ...
(later in the page)
This software comes from the
.URL "http://www.gnu.org/" "GNU Project" " of the"
.URL "http://www.fsf.org/" "Free Software Foundation" .
V uvedeném příkladu, pokud je použit groff, nahradí definice
makra URL z balíčku www.tmac definici definovanou lokálně.
K dispozici jsou i další makra pro odkazy. Viz groff_www(7) pro další
podrobnosti.
Různá makra
.DT Obnoví původní hodnoty tabulátorů (0.5 palce); nepůsobí zlom.
.PD d Nastaví vertikální vzdálenost mezi odstavci na d (pokud je
vynecháno, pak d=0.4v); nepůsobí zlom.
.SS t Podkapitola t (jako .SH, ale užívá se pro podsekci uvnitř
sekce).
Předdefinované řetězce
Balíček man obsahuje následující předdefinované řetězce:
\*R Symbol registrace: (R)
\*S Změna výchozí velikosti fontu
\*(Tm Ochranná známka: tm
\*(lq Dvojité uvozovky směřující vlevo: "
\*(rq Dvojité uvozovky směřující vpravo: "
Bezpečná sada
Ačkoliv technicky je man makro balíčkem programu troff, ve skutečnosti
zpracovává manuálové stránky velké množství dalších nástrojů, které
neimplementují všechny možnosti programu troff. Proto je nejlepší
vyhýbat se některým exotičtějším možnostem, aby mohly tyto nástroje
pracovat správně. Vyhněte se použití různých preprocesorů troffu
(pokud ale musíte, klidně použijte tbl(1), ale pro dvousloupcové
tabulky zkuste raději příkazy IP a TP). Vyhnětě se výpočtům; většina
ostatních nástrojů je neumí zpracovat. Používejte jednoduché příkazy,
které se snadno převádějí do jiných formátů. Následující makra jsou
obecně považována za bezpečná (i když v mnoha případech budou
překladači ignorována): \", ., ad, bp, br, ce, de, ds, el, ie, if, fi,
ft, hy, ig, in, na, ne, nf, nh, ps, so, sp, ti, tr.
také můžete používat mnohé escape sekvence troffu (začínající na \).
Pokud potřebujete uvést v textu zpětné lomítko, použijte \e. Další
sekvence, které je možné použít zahrnují (x je jakýkoliv znak a N je
jakákoliv číslice): \', \`, \-, \., \", \%, \*x, \*(xx, \(xx, \$N, \nx,
\n(xx, \fx, and \f(xx. Vyhněte se escape sekvencím pro kreslení.
Nepoužívejte volitelný parametr pro bp (break page). Používejte pouze
kladné hodnoty pro sp (vertical space). Nedefinujte makro (de) se
stejným jménem jako makro v tomto balíčku nebo v balíčku mdoc s jiným
významem; je pravděpodobné, že takové redefinování bude ignorováno.
Každé kladné odszení (in) by mělo mít odpovídající záporné odsazení
(ačkoliv by měla být raději používána makra RS a RE). Testy (if,ie) by
měly mít jako podmínku jen 't' nebo 'n'. Měly by být použity pouze
překlady (tr) které je možné ignorovat. Změny fontů (ft a escape
sekvence \f ) by měly mít pouze hodnoty 1, 2, 3, 4, R, I, B, P nebo CW
(příkaz ft nemusí mít žádný parametr).
Pokud využíváte pokročilejší možnosti, pečlivě vyzkoušejte výsledek s
několika nástroji. Jestliže zjistíte, že tato pokročilejší možnost je
bezpečná, dejte vědět udržovateli tohoto dokumentu, aby ji mohl přidat
do seznamu.
SOUBORY
/usr/share/groff/[*/]tmac/an.tmac
/usr/man/whatis
POZNÁMKY
Vždy uvádějte celé URL (nebo URI); některé nástroje, jako třeba
man2html(1) je mohou automaticky převézt na hypertextové odkazy. Také
je možné použítnové makro URL k označení odkazů na související
informace. Pokud uvádíte URL, použijte jejich úplný tvar (např.
<http://www.kernelnotes.org>), aby mohly být nalezeny automaticky.
Nástroje zpracovávající tyto soubory by měly otevřít soubor a
prozkoumat první znam, který není prázdným místem. Tečka (.) nebo
jednoduchá uvozovka(') na začátku řádku označují soubor troffu (jako
man nebo mdoc). levá ostrá závorka (<) označuje soubor SGML/XML (jako
HTML nebo Docbook). Cokoliv jiného je prostý ASCII text (např.
"catman").
Mnoho manuálových stránek začíná s '\" následovaným mezerou a řadou
znaků, které určují, jak má být stránka zpracována. Pro zachování
přenositelnosti doporučujeme vyhnout se všemu, s výjimkou tbl(1), který
Linux umí detekovat automaticky. Nicméně můžete tuto informaci uvést,
takže méně schopné systémy mohou vaši manuálovou stránku zpracovat.
Následují definice preprocesorů volaných těmito znaky:
e eqn(1)
g grap(1)
p pic(1)
r refer(1)
t tbl(1)
v vgrind(1)
CHYBY
Většina maker popisuje formátování (např. druh fontu a rozteč) namísto
značení sémantického obsahu (např. tento text je odkazem na jinou
stránku), na rozdíl od formátů jako mdoc a DocBook (i HTML má
sémantičtější značení). Proto není jednoduché převést formát man na
jiná média, udržet jeho konzistentnost a automaticky vkládat křížové
odkazy. Pokud se budete držet výše uvedené bezpečné sady, měl by být v
budoucnu automatický převod do jiného formátu jednodušší.
Makro TX Sunu není implementováno.
DALŠÍ INFORMACE
apropos(1), groff(1), man(1), man2html(1), whatis(1), groff_man(7),
groff_www(7), man-pages(7), mdoc(7), mdoc.samples(7)
TIRÁŽ
Tato stránka je součástí projektu Linux man-pages. Popis projektu a
informace o hlášení chyb najdete na http://www.kernel.org/doc/man-
pages/.