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

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:

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)

[přibližně] 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:

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: ®

\*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.