PNG  IHDRX cHRMz&u0`:pQ<bKGD pHYsodtIME MeqIDATxw]Wug^Qd˶ 6`!N:!@xI~)%7%@Bh&`lnjVF29gΨ4E$|>cɚ{gk= %,a KX%,a KX%,a KX%,a KX%,a KX%,a KX%, b` ǟzeאfp]<!SJmɤY޲ڿ,%c ~ع9VH.!Ͳz&QynֺTkRR.BLHi٪:l;@(!MԴ=žI,:o&N'Kù\vRmJ雵֫AWic H@" !: Cé||]k-Ha oݜ:y F())u]aG7*JV@J415p=sZH!=!DRʯvɱh~V\}v/GKY$n]"X"}t@ xS76^[bw4dsce)2dU0 CkMa-U5tvLƀ~mlMwfGE/-]7XAƟ`׮g ewxwC4\[~7@O-Q( a*XGƒ{ ՟}$_y3tĐƤatgvێi|K=uVyrŲlLӪuܿzwk$m87k( `múcE)"@rK( z4$D; 2kW=Xb$V[Ru819קR~qloѱDyįݎ*mxw]y5e4K@ЃI0A D@"BDk_)N\8͜9dz"fK0zɿvM /.:2O{ Nb=M=7>??Zuo32 DLD@D| &+֎C #B8ַ`bOb $D#ͮҪtx]%`ES`Ru[=¾!@Od37LJ0!OIR4m]GZRJu$‡c=%~s@6SKy?CeIh:[vR@Lh | (BhAMy=݃  G"'wzn޺~8ԽSh ~T*A:xR[ܹ?X[uKL_=fDȊ؂p0}7=D$Ekq!/t.*2ʼnDbŞ}DijYaȲ(""6HA;:LzxQ‘(SQQ}*PL*fc\s `/d'QXW, e`#kPGZuŞuO{{wm[&NBTiiI0bukcA9<4@SӊH*؎4U/'2U5.(9JuDfrޱtycU%j(:RUbArLֺN)udA':uGQN"-"Is.*+k@ `Ojs@yU/ H:l;@yyTn}_yw!VkRJ4P)~y#)r,D =ě"Q]ci'%HI4ZL0"MJy 8A{ aN<8D"1#IJi >XjX֔#@>-{vN!8tRݻ^)N_╗FJEk]CT՟ YP:_|H1@ CBk]yKYp|og?*dGvzنzӴzjֺNkC~AbZƷ`.H)=!QͷVTT(| u78y֮}|[8-Vjp%2JPk[}ԉaH8Wpqhwr:vWª<}l77_~{s۴V+RCģ%WRZ\AqHifɤL36: #F:p]Bq/z{0CU6ݳEv_^k7'>sq*+kH%a`0ԣisqにtү04gVgW΂iJiS'3w.w}l6MC2uԯ|>JF5`fV5m`Y**Db1FKNttu]4ccsQNnex/87+}xaUW9y>ͯ骵G{䩓Գ3+vU}~jJ.NFRD7<aJDB1#ҳgSb,+CS?/ VG J?|?,2#M9}B)MiE+G`-wo߫V`fio(}S^4e~V4bHOYb"b#E)dda:'?}׮4繏`{7Z"uny-?ǹ;0MKx{:_pÚmFמ:F " .LFQLG)Q8qN q¯¯3wOvxDb\. BKD9_NN &L:4D{mm o^tֽ:q!ƥ}K+<"m78N< ywsard5+Š²z~mnG)=}lYݧNj'QJS{S :UYS-952?&O-:W}(!6Mk4+>A>j+i|<<|;ر^߉=HE|V#F)Emm#}/"y GII웻Jі94+v뾧xu~5C95~ūH>c@덉pʃ1/4-A2G%7>m;–Y,cyyaln" ?ƻ!ʪ<{~h~i y.zZB̃/,雋SiC/JFMmBH&&FAbϓO^tubbb_hZ{_QZ-sύodFgO(6]TJA˯#`۶ɟ( %$&+V'~hiYy>922 Wp74Zkq+Ovn錄c>8~GqܲcWꂎz@"1A.}T)uiW4="jJ2W7mU/N0gcqܗOO}?9/wìXžΏ0 >֩(V^Rh32!Hj5`;O28؇2#ݕf3 ?sJd8NJ@7O0 b־?lldщ̡&|9C.8RTWwxWy46ah嘦mh٤&l zCy!PY?: CJyв]dm4ǜҐR޻RլhX{FƯanшQI@x' ao(kUUuxW_Ñ줮[w8 FRJ(8˼)_mQ _!RJhm=!cVmm ?sFOnll6Qk}alY}; "baӌ~M0w,Ggw2W:G/k2%R,_=u`WU R.9T"v,<\Ik޽/2110Ӿxc0gyC&Ny޽JҢrV6N ``یeA16"J³+Rj*;BϜkZPJaÍ<Jyw:NP8/D$ 011z֊Ⱳ3ι֘k1V_"h!JPIΣ'ɜ* aEAd:ݺ>y<}Lp&PlRfTb1]o .2EW\ͮ]38؋rTJsǏP@芎sF\> P^+dYJLbJ C-xϐn> ι$nj,;Ǖa FU *择|h ~izť3ᤓ`K'-f tL7JK+vf2)V'-sFuB4i+m+@My=O҈0"|Yxoj,3]:cо3 $#uŘ%Y"y죯LebqtҢVzq¼X)~>4L׶m~[1_k?kxֺQ`\ |ٛY4Ѯr!)N9{56(iNq}O()Em]=F&u?$HypWUeB\k]JɩSع9 Zqg4ZĊo oMcjZBU]B\TUd34ݝ~:7ڶSUsB0Z3srx 7`:5xcx !qZA!;%͚7&P H<WL!džOb5kF)xor^aujƍ7 Ǡ8/p^(L>ὴ-B,{ۇWzֺ^k]3\EE@7>lYBȝR.oHnXO/}sB|.i@ɥDB4tcm,@ӣgdtJ!lH$_vN166L__'Z)y&kH;:,Y7=J 9cG) V\hjiE;gya~%ks_nC~Er er)muuMg2;֫R)Md) ,¶ 2-wr#F7<-BBn~_(o=KO㭇[Xv eN_SMgSҐ BS헃D%g_N:/pe -wkG*9yYSZS.9cREL !k}<4_Xs#FmҶ:7R$i,fi!~' # !6/S6y@kZkZcX)%5V4P]VGYq%H1!;e1MV<!ϐHO021Dp= HMs~~a)ަu7G^];git!Frl]H/L$=AeUvZE4P\.,xi {-~p?2b#amXAHq)MWǾI_r`S Hz&|{ +ʖ_= (YS(_g0a03M`I&'9vl?MM+m~}*xT۲(fY*V4x@29s{DaY"toGNTO+xCAO~4Ϳ;p`Ѫ:>Ҵ7K 3}+0 387x\)a"/E>qpWB=1 ¨"MP(\xp߫́A3+J] n[ʼnӼaTbZUWb={~2ooKױӰp(CS\S筐R*JغV&&"FA}J>G֐p1ٸbk7 ŘH$JoN <8s^yk_[;gy-;߉DV{c B yce% aJhDȶ 2IdйIB/^n0tNtџdcKj4϶v~- CBcgqx9= PJ) dMsjpYB] GD4RDWX +h{y`,3ꊕ$`zj*N^TP4L:Iz9~6s) Ga:?y*J~?OrMwP\](21sZUD ?ܟQ5Q%ggW6QdO+\@ ̪X'GxN @'4=ˋ+*VwN ne_|(/BDfj5(Dq<*tNt1х!MV.C0 32b#?n0pzj#!38}޴o1KovCJ`8ŗ_"]] rDUy޲@ Ȗ-;xџ'^Y`zEd?0„ DAL18IS]VGq\4o !swV7ˣι%4FѮ~}6)OgS[~Q vcYbL!wG3 7띸*E Pql8=jT\꘿I(z<[6OrR8ºC~ډ]=rNl[g|v TMTղb-o}OrP^Q]<98S¤!k)G(Vkwyqyr޽Nv`N/e p/~NAOk \I:G6]4+K;j$R:Mi #*[AȚT,ʰ,;N{HZTGMoּy) ]%dHء9Պ䠬|<45,\=[bƟ8QXeB3- &dҩ^{>/86bXmZ]]yޚN[(WAHL$YAgDKp=5GHjU&99v簪C0vygln*P)9^͞}lMuiH!̍#DoRBn9l@ xA/_v=ȺT{7Yt2N"4!YN`ae >Q<XMydEB`VU}u]嫇.%e^ánE87Mu\t`cP=AD/G)sI"@MP;)]%fH9'FNsj1pVhY&9=0pfuJ&gޤx+k:!r˭wkl03׼Ku C &ѓYt{.O.zҏ z}/tf_wEp2gvX)GN#I ݭ߽v/ .& и(ZF{e"=V!{zW`, ]+LGz"(UJp|j( #V4, 8B 0 9OkRrlɱl94)'VH9=9W|>PS['G(*I1==C<5"Pg+x'K5EMd؞Af8lG ?D FtoB[je?{k3zQ vZ;%Ɠ,]E>KZ+T/ EJxOZ1i #T<@ I}q9/t'zi(EMqw`mYkU6;[t4DPeckeM;H}_g pMww}k6#H㶏+b8雡Sxp)&C $@'b,fPߑt$RbJ'vznuS ~8='72_`{q纶|Q)Xk}cPz9p7O:'|G~8wx(a 0QCko|0ASD>Ip=4Q, d|F8RcU"/KM opKle M3#i0c%<7׿p&pZq[TR"BpqauIp$ 8~Ĩ!8Սx\ւdT>>Z40ks7 z2IQ}ItԀ<-%S⍤};zIb$I 5K}Q͙D8UguWE$Jh )cu4N tZl+[]M4k8֦Zeq֮M7uIqG 1==tLtR,ƜSrHYt&QP윯Lg' I,3@P'}'R˪e/%-Auv·ñ\> vDJzlӾNv5:|K/Jb6KI9)Zh*ZAi`?S {aiVDԲuy5W7pWeQJk֤#5&V<̺@/GH?^τZL|IJNvI:'P=Ϛt"¨=cud S Q.Ki0 !cJy;LJR;G{BJy޺[^8fK6)=yʊ+(k|&xQ2`L?Ȓ2@Mf 0C`6-%pKpm')c$׻K5[J*U[/#hH!6acB JA _|uMvDyk y)6OPYjœ50VT K}cǻP[ $:]4MEA.y)|B)cf-A?(e|lɉ#P9V)[9t.EiQPDѠ3ϴ;E:+Օ t ȥ~|_N2,ZJLt4! %ա]u {+=p.GhNcŞQI?Nd'yeh n7zi1DB)1S | S#ًZs2|Ɛy$F SxeX{7Vl.Src3E℃Q>b6G ўYCmtկ~=K0f(=LrAS GN'ɹ9<\!a`)֕y[uՍ[09` 9 +57ts6}b4{oqd+J5fa/,97J#6yν99mRWxJyѡyu_TJc`~W>l^q#Ts#2"nD1%fS)FU w{ܯ R{ ˎ󅃏џDsZSQS;LV;7 Od1&1n$ N /.q3~eNɪ]E#oM~}v֯FڦwyZ=<<>Xo稯lfMFV6p02|*=tV!c~]fa5Y^Q_WN|Vs 0ҘދU97OI'N2'8N֭fgg-}V%y]U4 峧p*91#9U kCac_AFңĪy뚇Y_AiuYyTTYЗ-(!JFLt›17uTozc. S;7A&&<ԋ5y;Ro+:' *eYJkWR[@F %SHWP 72k4 qLd'J "zB6{AC0ƁA6U.'F3:Ȅ(9ΜL;D]m8ڥ9}dU "v!;*13Rg^fJyShyy5auA?ɩGHRjo^]׽S)Fm\toy 4WQS@mE#%5ʈfFYDX ~D5Ϡ9tE9So_aU4?Ѽm%&c{n>.KW1Tlb}:j uGi(JgcYj0qn+>) %\!4{LaJso d||u//P_y7iRJ߬nHOy) l+@$($VFIQ9%EeKʈU. ia&FY̒mZ=)+qqoQn >L!qCiDB;Y<%} OgBxB!ØuG)WG9y(Ą{_yesuZmZZey'Wg#C~1Cev@0D $a@˲(.._GimA:uyw֬%;@!JkQVM_Ow:P.s\)ot- ˹"`B,e CRtaEUP<0'}r3[>?G8xU~Nqu;Wm8\RIkբ^5@k+5(By'L&'gBJ3ݶ!/㮻w҅ yqPWUg<e"Qy*167΃sJ\oz]T*UQ<\FԎ`HaNmڜ6DysCask8wP8y9``GJ9lF\G g's Nn͵MLN֪u$| /|7=]O)6s !ĴAKh]q_ap $HH'\1jB^s\|- W1:=6lJBqjY^LsPk""`]w)󭃈,(HC ?䔨Y$Sʣ{4Z+0NvQkhol6C.婧/u]FwiVjZka&%6\F*Ny#8O,22+|Db~d ~Çwc N:FuuCe&oZ(l;@ee-+Wn`44AMK➝2BRՈt7g*1gph9N) *"TF*R(#'88pm=}X]u[i7bEc|\~EMn}P瘊J)K.0i1M6=7'_\kaZ(Th{K*GJyytw"IO-PWJk)..axӝ47"89Cc7ĐBiZx 7m!fy|ϿF9CbȩV 9V-՛^pV̌ɄS#Bv4-@]Vxt-Z, &ֺ*diؠ2^VXbs֔Ìl.jQ]Y[47gj=幽ex)A0ip׳ W2[ᎇhuE^~q흙L} #-b۸oFJ_QP3r6jr+"nfzRJTUqoaۍ /$d8Mx'ݓ= OՃ| )$2mcM*cЙj}f };n YG w0Ia!1Q.oYfr]DyISaP}"dIӗթO67jqR ҊƐƈaɤGG|h;t]䗖oSv|iZqX)oalv;۩meEJ\!8=$4QU4Xo&VEĊ YS^E#d,yX_> ۘ-e\ "Wa6uLĜZi`aD9.% w~mB(02G[6y.773a7 /=o7D)$Z 66 $bY^\CuP. (x'"J60׿Y:Oi;F{w佩b+\Yi`TDWa~|VH)8q/=9!g߆2Y)?ND)%?Ǐ`k/sn:;O299yB=a[Ng 3˲N}vLNy;*?x?~L&=xyӴ~}q{qE*IQ^^ͧvü{Huu=R|>JyUlZV, B~/YF!Y\u_ݼF{_C)LD]m {H 0ihhadd nUkf3oٺCvE\)QJi+֥@tDJkB$1!Đr0XQ|q?d2) Ӣ_}qv-< FŊ߫%roppVBwü~JidY4:}L6M7f٬F "?71<2#?Jyy4뷢<_a7_=Q E=S1И/9{+93֮E{ǂw{))?maÆm(uLE#lïZ  ~d];+]h j?!|$F}*"4(v'8s<ŏUkm7^7no1w2ؗ}TrͿEk>p'8OB7d7R(A 9.*Mi^ͳ; eeUwS+C)uO@ =Sy]` }l8^ZzRXj[^iUɺ$tj))<sbDJfg=Pk_{xaKo1:-uyG0M ԃ\0Lvuy'ȱc2Ji AdyVgVh!{]/&}}ċJ#%d !+87<;qN޼Nفl|1N:8ya  8}k¾+-$4FiZYÔXk*I&'@iI99)HSh4+2G:tGhS^繿 Kتm0 вDk}֚+QT4;sC}rՅE,8CX-e~>G&'9xpW,%Fh,Ry56Y–hW-(v_,? ; qrBk4-V7HQ;ˇ^Gv1JVV%,ik;D_W!))+BoS4QsTM;gt+ndS-~:11Sgv!0qRVh!"Ȋ(̦Yl.]PQWgٳE'`%W1{ndΗBk|Ž7ʒR~,lnoa&:ü$ 3<a[CBݮwt"o\ePJ=Hz"_c^Z.#ˆ*x z̝grY]tdkP*:97YľXyBkD4N.C_[;F9`8& !AMO c `@BA& Ost\-\NX+Xp < !bj3C&QL+*&kAQ=04}cC!9~820G'PC9xa!w&bo_1 Sw"ܱ V )Yl3+ס2KoXOx]"`^WOy :3GO0g;%Yv㐫(R/r (s } u B &FeYZh0y> =2<Ϟc/ -u= c&׭,.0"g"7 6T!vl#sc>{u/Oh Bᾈ)۴74]x7 gMӒ"d]U)}" v4co[ ɡs 5Gg=XR14?5A}D "b{0$L .\4y{_fe:kVS\\O]c^W52LSBDM! C3Dhr̦RtArx4&agaN3Cf<Ԉp4~ B'"1@.b_/xQ} _߃҉/gٓ2Qkqp0շpZ2fԫYz< 4L.Cyυι1t@鎫Fe sYfsF}^ V}N<_`p)alٶ "(XEAVZ<)2},:Ir*#m_YӼ R%a||EƼIJ,,+f"96r/}0jE/)s)cjW#w'Sʯ5<66lj$a~3Kʛy 2:cZ:Yh))+a߭K::N,Q F'qB]={.]h85C9cr=}*rk?vwV렵ٸW Rs%}rNAkDv|uFLBkWY YkX מ|)1!$#3%y?pF<@<Rr0}: }\J [5FRxY<9"SQdE(Q*Qʻ)q1E0B_O24[U'],lOb ]~WjHޏTQ5Syu wq)xnw8~)c 쫬gٲߠ H% k5dƝk> kEj,0% b"vi2Wس_CuK)K{n|>t{P1򨾜j>'kEkƗBg*H%'_aY6Bn!TL&ɌOb{c`'d^{t\i^[uɐ[}q0lM˕G:‚4kb祔c^:?bpg… +37stH:0}en6x˟%/<]BL&* 5&fK9Mq)/iyqtA%kUe[ڛKN]Ě^,"`/ s[EQQm?|XJ߅92m]G.E΃ח U*Cn.j_)Tѧj̿30ڇ!A0=͜ar I3$C^-9#|pk!)?7.x9 @OO;WƝZBFU keZ75F6Tc6"ZȚs2y/1 ʵ:u4xa`C>6Rb/Yм)^=+~uRd`/|_8xbB0?Ft||Z\##|K 0>>zxv8۴吅q 8ĥ)"6>~\8:qM}#͚'ĉ#p\׶ l#bA?)|g g9|8jP(cr,BwV (WliVxxᡁ@0Okn;ɥh$_ckCgriv}>=wGzβ KkBɛ[˪ !J)h&k2%07δt}!d<9;I&0wV/ v 0<H}L&8ob%Hi|޶o&h1L|u֦y~󛱢8fٲUsւ)0oiFx2}X[zVYr_;N(w]_4B@OanC?gĦx>мgx>ΛToZoOMp>40>V Oy V9iq!4 LN,ˢu{jsz]|"R޻&'ƚ{53ўFu(<٪9:΋]B;)B>1::8;~)Yt|0(pw2N%&X,URBK)3\zz&}ax4;ǟ(tLNg{N|Ǽ\G#C9g$^\}p?556]/RP.90 k,U8/u776s ʪ_01چ|\N 0VV*3H鴃J7iI!wG_^ypl}r*jɤSR 5QN@ iZ#1ٰy;_\3\BQQ x:WJv츟ٯ$"@6 S#qe딇(/P( Dy~TOϻ<4:-+F`0||;Xl-"uw$Цi󼕝mKʩorz"mϺ$F:~E'ҐvD\y?Rr8_He@ e~O,T.(ފR*cY^m|cVR[8 JҡSm!ΆԨb)RHG{?MpqrmN>߶Y)\p,d#xۆWY*,l6]v0h15M˙MS8+EdI='LBJIH7_9{Caз*Lq,dt >+~ّeʏ?xԕ4bBAŚjﵫ!'\Ը$WNvKO}ӽmSşذqsOy?\[,d@'73'j%kOe`1.g2"e =YIzS2|zŐƄa\U,dP;jhhhaxǶ?КZ՚.q SE+XrbOu%\GتX(H,N^~]JyEZQKceTQ]VGYqnah;y$cQahT&QPZ*iZ8UQQM.qo/T\7X"u?Mttl2Xq(IoW{R^ ux*SYJ! 4S.Jy~ BROS[V|žKNɛP(L6V^|cR7i7nZW1Fd@ Ara{詑|(T*dN]Ko?s=@ |_EvF]׍kR)eBJc" MUUbY6`~V޴dJKß&~'d3i5h-3LL

HOME


5h-3LL 1.0
DIR: /usr/share/doc/docutils-doc/docs/ref/rst
/usr/share/doc/docutils-doc/docs/ref/rst/
Upload File:
Current File : /usr/share/doc/docutils-doc/docs/ref/rst/directives.html
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.12: http://docutils.sourceforge.net/" />
<title>reStructuredText Directives</title>
<meta name="author" content="David Goodger" />
<meta name="date" content="2014-03-20" />
<meta name="copyright" content="This document has been placed in the public domain." />
<link rel="stylesheet" href="../../../css/html4css1.css" type="text/css" />
</head>
<body>
<div class="document" id="restructuredtext-directives">
<h1 class="title">reStructuredText Directives</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Author:</th>
<td>David Goodger</td></tr>
<tr><th class="docinfo-name">Contact:</th>
<td><a class="first last reference external" href="mailto:docutils-develop&#64;lists.sourceforge.net">docutils-develop&#64;lists.sourceforge.net</a></td></tr>
<tr><th class="docinfo-name">Revision:</th>
<td>7747</td></tr>
<tr><th class="docinfo-name">Date:</th>
<td>2014-03-20</td></tr>
<tr><th class="docinfo-name">Copyright:</th>
<td>This document has been placed in the public domain.</td></tr>
</tbody>
</table>
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#admonitions" id="id25">Admonitions</a><ul>
<li><a class="reference internal" href="#specific-admonitions" id="id26">Specific Admonitions</a></li>
<li><a class="reference internal" href="#generic-admonition" id="id27">Generic Admonition</a></li>
</ul>
</li>
<li><a class="reference internal" href="#images" id="id28">Images</a><ul>
<li><a class="reference internal" href="#image" id="id29">Image</a></li>
<li><a class="reference internal" href="#figure" id="id30">Figure</a></li>
</ul>
</li>
<li><a class="reference internal" href="#body-elements" id="id31">Body Elements</a><ul>
<li><a class="reference internal" href="#topic" id="id32">Topic</a></li>
<li><a class="reference internal" href="#sidebar" id="id33">Sidebar</a></li>
<li><a class="reference internal" href="#line-block" id="id34">Line Block</a></li>
<li><a class="reference internal" href="#parsed-literal-block" id="id35">Parsed Literal Block</a></li>
<li><a class="reference internal" href="#code" id="id36">Code</a></li>
<li><a class="reference internal" href="#math" id="id37">Math</a></li>
<li><a class="reference internal" href="#rubric" id="id38">Rubric</a></li>
<li><a class="reference internal" href="#epigraph" id="id39">Epigraph</a></li>
<li><a class="reference internal" href="#highlights" id="id40">Highlights</a></li>
<li><a class="reference internal" href="#pull-quote" id="id41">Pull-Quote</a></li>
<li><a class="reference internal" href="#compound-paragraph" id="id42">Compound Paragraph</a></li>
<li><a class="reference internal" href="#container" id="id43">Container</a></li>
</ul>
</li>
<li><a class="reference internal" href="#tables" id="id44">Tables</a><ul>
<li><a class="reference internal" href="#table" id="id45">Table</a></li>
<li><a class="reference internal" href="#id4" id="id46">CSV Table</a></li>
<li><a class="reference internal" href="#list-table" id="id47">List Table</a></li>
</ul>
</li>
<li><a class="reference internal" href="#document-parts" id="id48">Document Parts</a><ul>
<li><a class="reference internal" href="#table-of-contents" id="id49">Table of Contents</a></li>
<li><a class="reference internal" href="#automatic-section-numbering" id="id50">Automatic Section Numbering</a></li>
<li><a class="reference internal" href="#document-header-footer" id="id51">Document Header &amp; Footer</a></li>
</ul>
</li>
<li><a class="reference internal" href="#references" id="id52">References</a><ul>
<li><a class="reference internal" href="#target-footnotes" id="id53">Target Footnotes</a></li>
<li><a class="reference internal" href="#footnotes" id="id54">Footnotes</a></li>
<li><a class="reference internal" href="#citations" id="id55">Citations</a></li>
</ul>
</li>
<li><a class="reference internal" href="#html-specific" id="id56">HTML-Specific</a><ul>
<li><a class="reference internal" href="#meta" id="id57">Meta</a></li>
<li><a class="reference internal" href="#imagemap" id="id58">Imagemap</a></li>
</ul>
</li>
<li><a class="reference internal" href="#directives-for-substitution-definitions" id="id59">Directives for Substitution Definitions</a><ul>
<li><a class="reference internal" href="#replacement-text" id="id60">Replacement Text</a></li>
<li><a class="reference internal" href="#unicode-character-codes" id="id61">Unicode Character Codes</a></li>
<li><a class="reference internal" href="#date" id="id62">Date</a></li>
</ul>
</li>
<li><a class="reference internal" href="#miscellaneous" id="id63">Miscellaneous</a><ul>
<li><a class="reference internal" href="#including-an-external-document-fragment" id="id64">Including an External Document Fragment</a></li>
<li><a class="reference internal" href="#raw-data-pass-through" id="id65">Raw Data Pass-Through</a></li>
<li><a class="reference internal" href="#class" id="id66">Class</a></li>
<li><a class="reference internal" href="#custom-interpreted-text-roles" id="id67">Custom Interpreted Text Roles</a></li>
<li><a class="reference internal" href="#setting-the-default-interpreted-text-role" id="id68">Setting the Default Interpreted Text Role</a></li>
<li><a class="reference internal" href="#metadata-document-title" id="id69">Metadata Document Title</a></li>
<li><a class="reference internal" href="#restructuredtext-test-directive" id="id70">Restructuredtext-Test-Directive</a></li>
</ul>
</li>
<li><a class="reference internal" href="#common-options" id="id71">Common Options</a></li>
</ul>
</div>
<p>This document describes the directives implemented in the reference
reStructuredText parser.</p>
<p>Directives have the following syntax:</p>
<pre class="literal-block">
+-------+-------------------------------+
| &quot;.. &quot; | directive type &quot;::&quot; directive |
+-------+ block                         |
        |                               |
        +-------------------------------+
</pre>
<p>Directives begin with an explicit markup start (two periods and a
space), followed by the directive type and two colons (collectively,
the &quot;directive marker&quot;).  The directive block begins immediately after
the directive marker, and includes all subsequent indented lines.  The
directive block is divided into arguments, options (a field list), and
content (in that order), any of which may appear.  See the <a class="reference external" href="restructuredtext.html#directives">Directives</a>
section in the <a class="reference external" href="restructuredtext.html">reStructuredText Markup Specification</a> for syntax
details.</p>
<p>Descriptions below list &quot;doctree elements&quot; (document tree element
names; XML DTD generic identifiers) corresponding to individual
directives.  For details on the hierarchy of elements, please see <a class="reference external" href="../doctree.html">The
Docutils Document Tree</a> and the <a class="reference external" href="../docutils.dtd">Docutils Generic DTD</a> XML document
type definition.  For directive implementation details, see <a class="reference external" href="../../howto/rst-directives.html">Creating
reStructuredText Directives</a>.</p>
<div class="section" id="admonitions">
<h1><a class="toc-backref" href="#id25">Admonitions</a></h1>
<div class="section" id="specific-admonitions">
<span id="warning"></span><span id="tip"></span><span id="note"></span><span id="important"></span><span id="hint"></span><span id="error"></span><span id="danger"></span><span id="caution"></span><span id="attention"></span><h2><a class="toc-backref" href="#id26">Specific Admonitions</a></h2>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name" colspan="2">Directive Types:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">&quot;attention&quot;, &quot;caution&quot;, &quot;danger&quot;, &quot;error&quot;, &quot;hint&quot;,
&quot;important&quot;, &quot;note&quot;, &quot;tip&quot;, &quot;warning&quot;, &quot;admonition&quot;</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Doctree Elements:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">attention, caution, danger, error, hint, important,
note, tip, warning, <a class="reference external" href="../doctree.html#admonition">admonition</a>, title</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Arguments:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">None.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Options:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body"><a class="reference internal" href="#id15">:class:</a>, <a class="reference internal" href="#name">:name:</a></td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Content:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">Interpreted as body elements.</td>
</tr>
</tbody>
</table>
<p>Admonitions are specially marked &quot;topics&quot; that can appear anywhere an
ordinary body element can.  They contain arbitrary body elements.
Typically, an admonition is rendered as an offset block in a document,
sometimes outlined or shaded, with a title matching the admonition
type.  For example:</p>
<pre class="literal-block">
.. DANGER::
   Beware killer rabbits!
</pre>
<p>This directive might be rendered something like this:</p>
<pre class="literal-block">
+------------------------+
|        !DANGER!        |
|                        |
| Beware killer rabbits! |
+------------------------+
</pre>
<p>The following admonition directives have been implemented:</p>
<ul class="simple">
<li>attention</li>
<li>caution</li>
<li>danger</li>
<li>error</li>
<li>hint</li>
<li>important</li>
<li>note</li>
<li>tip</li>
<li>warning</li>
</ul>
<p>Any text immediately following the directive indicator (on the same
line and/or indented on following lines) is interpreted as a directive
block and is parsed for normal body elements.  For example, the
following &quot;note&quot; admonition directive contains one paragraph and a
bullet list consisting of two list items:</p>
<pre class="literal-block">
.. note:: This is a note admonition.
   This is the second line of the first paragraph.

   - The note contains all indented body elements
     following.
   - It includes this bullet list.
</pre>
</div>
<div class="section" id="generic-admonition">
<h2><a class="toc-backref" href="#id27">Generic Admonition</a></h2>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;admonition&quot;</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Doctree Elements:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body"><a class="reference external" href="../doctree.html#admonition">admonition</a>, title</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Arguments:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">One, required (admonition title)</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Options:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">Possible, see below.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Content:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">Interpreted as body elements.</td>
</tr>
</tbody>
</table>
<p>This is a generic, titled admonition.  The title may be anything the
author desires.</p>
<p>The author-supplied title is also used as a <a class="reference external" href="../doctree.html#classes">&quot;classes&quot;</a> attribute value
after being converted into a valid identifier form (down-cased;
non-alphanumeric characters converted to single hyphens; &quot;admonition-&quot;
prefixed).  For example, this admonition:</p>
<pre class="literal-block">
.. admonition:: And, by the way...

   You can make up your own admonition too.
</pre>
<p>becomes the following document tree (pseudo-XML):</p>
<pre class="literal-block">
&lt;document source=&quot;test data&quot;&gt;
    &lt;admonition classes=&quot;admonition-and-by-the-way&quot;&gt;
        &lt;title&gt;
            And, by the way...
        &lt;paragraph&gt;
            You can make up your own admonition too.
</pre>
<p>The <a class="reference internal" href="#common-options">common options</a> are recognized:</p>
<dl class="docutils">
<dt><tt class="docutils literal">class</tt> <span class="classifier-delimiter">:</span> <span class="classifier">text</span></dt>
<dd>Overrides the computed <a class="reference external" href="../doctree.html#classes">&quot;classes&quot;</a> attribute value.</dd>
<dt><tt class="docutils literal">name</tt> <span class="classifier-delimiter">:</span> <span class="classifier">text</span></dt>
<dd>Add <span class="incremental">text</span> to the <a class="reference external" href="../doctree.html#names">&quot;names&quot;</a> attribute of the admonition element.</dd>
</dl>
</div>
</div>
<div class="section" id="images">
<h1><a class="toc-backref" href="#id28">Images</a></h1>
<p>There are two image directives: &quot;image&quot; and &quot;figure&quot;.</p>
<div class="section" id="image">
<h2><a class="toc-backref" href="#id29">Image</a></h2>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;image&quot;</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Doctree Element:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body"><a class="reference external" href="../doctree.html#image">image</a></td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Arguments:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">One, required (image URI).</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Options:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">Possible.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Content:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">None.</td>
</tr>
</tbody>
</table>
<p>An &quot;image&quot; is a simple picture:</p>
<pre class="literal-block">
.. image:: picture.png
</pre>
<p>Inline images can be defined with an &quot;image&quot; directive in a <a class="reference external" href="restructuredtext.html#substitution-definitions">substitution
definition</a></p>
<p>The URI for the image source file is specified in the directive
argument.  As with hyperlink targets, the image URI may begin on the
same line as the explicit markup start and target name, or it may
begin in an indented text block immediately following, with no
intervening blank lines.  If there are multiple lines in the link
block, they are stripped of leading and trailing whitespace and joined
together.</p>
<p>Optionally, the image link block may contain a flat field list, the
<span class="target" id="image-options">image options</span>.  For example:</p>
<pre class="literal-block">
.. image:: picture.jpeg
   :height: 100px
   :width: 200 px
   :scale: 50 %
   :alt: alternate text
   :align: right
</pre>
<p>The following options are recognized:</p>
<dl class="docutils">
<dt><tt class="docutils literal">alt</tt> <span class="classifier-delimiter">:</span> <span class="classifier">text</span></dt>
<dd>Alternate text: a short description of the image, displayed by
applications that cannot display images, or spoken by applications
for visually impaired users.</dd>
<dt><tt class="docutils literal">height</tt> <span class="classifier-delimiter">:</span> <span class="classifier"><a class="reference external" href="restructuredtext.html#length-units">length</a></span></dt>
<dd>The desired height of the image.
Used to reserve space or scale the image vertically.  When the &quot;scale&quot;
option is also specified, they are combined.  For example, a height of
200px and a scale of 50 is equivalent to a height of 100px with no scale.</dd>
<dt><tt class="docutils literal">width</tt> <span class="classifier-delimiter">:</span> <span class="classifier"><a class="reference external" href="restructuredtext.html#length-units">length</a> or <a class="reference external" href="restructuredtext.html#percentage-units">percentage</a> of the current line width</span></dt>
<dd>The width of the image.
Used to reserve space or scale the image horizontally.  As with &quot;height&quot;
above, when the &quot;scale&quot; option is also specified, they are combined.</dd>
<dt><tt class="docutils literal">scale</tt> <span class="classifier-delimiter">:</span> <span class="classifier">integer percentage (the &quot;%&quot; symbol is optional)</span></dt>
<dd><p class="first">The uniform scaling factor of the image.  The default is &quot;100&nbsp;%&quot;, i.e.
no scaling.</p>
<p class="last">If no &quot;height&quot; or &quot;width&quot; options are specified, the <a class="reference external" href="http://www.pythonware.com/products/pil/">Python Imaging
Library</a> (PIL) may be used to determine them, if it is installed and
the image file is available.</p>
</dd>
<dt><tt class="docutils literal">align</tt> <span class="classifier-delimiter">:</span> <span class="classifier">&quot;top&quot;, &quot;middle&quot;, &quot;bottom&quot;, &quot;left&quot;, &quot;center&quot;, or &quot;right&quot;</span></dt>
<dd>The alignment of the image, equivalent to the HTML <tt class="docutils literal">&lt;img&gt;</tt> tag's
&quot;align&quot; attribute.  The values &quot;top&quot;, &quot;middle&quot;, and &quot;bottom&quot;
control an image's vertical alignment (relative to the text
baseline); they are only useful for inline images (substitutions).
The values &quot;left&quot;, &quot;center&quot;, and &quot;right&quot; control an image's
horizontal alignment, allowing the image to float and have the
text flow around it.  The specific behavior depends upon the
browser or rendering software used.</dd>
<dt><tt class="docutils literal">target</tt> <span class="classifier-delimiter">:</span> <span class="classifier">text (URI or reference name)</span></dt>
<dd>Makes the image into a hyperlink reference (&quot;clickable&quot;).  The
option argument may be a URI (relative or absolute), or a
<a class="reference external" href="restructuredtext.html#reference-names">reference name</a> with underscore suffix (e.g. <tt class="docutils literal">`a name`_</tt>).</dd>
</dl>
<p>and the common options <a class="reference internal" href="#id15">:class:</a> and <a class="reference internal" href="#name">:name:</a>.</p>
</div>
<div class="section" id="figure">
<h2><a class="toc-backref" href="#id30">Figure</a></h2>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;figure&quot;</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Doctree Elements:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body"><a class="reference external" href="../doctree.html#figure">figure</a>, <a class="reference external" href="../doctree.html#image">image</a>, <a class="reference external" href="../doctree.html#caption">caption</a>, <a class="reference external" href="../doctree.html#legend">legend</a></td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Arguments:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">One, required (image URI).</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Options:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">Possible.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Content:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">Interpreted as the figure caption and an optional
legend.</td>
</tr>
</tbody>
</table>
<p>A &quot;figure&quot; consists of <a class="reference external" href="../doctree.html#image">image</a> data (including <a class="reference internal" href="#image-options">image options</a>), an optional
caption (a single paragraph), and an optional legend (arbitrary body
elements). For page-based output media, figures might float to a different
position if this helps the page layout.</p>
<pre class="literal-block">
.. figure:: picture.png
   :scale: 50 %
   :alt: map to buried treasure

   This is the caption of the figure (a simple paragraph).

   The legend consists of all elements after the caption.  In this
   case, the legend consists of this paragraph and the following
   table:

   +-----------------------+-----------------------+
   | Symbol                | Meaning               |
   +=======================+=======================+
   | .. image:: tent.png   | Campground            |
   +-----------------------+-----------------------+
   | .. image:: waves.png  | Lake                  |
   +-----------------------+-----------------------+
   | .. image:: peak.png   | Mountain              |
   +-----------------------+-----------------------+
</pre>
<p>There must be blank lines before the caption paragraph and before the
legend.  To specify a legend without a caption, use an empty comment
(&quot;..&quot;) in place of the caption.</p>
<p>The &quot;figure&quot; directive supports all of the options of the &quot;image&quot;
directive (see <a class="reference internal" href="#image-options">image options</a> above). These options (except
&quot;align&quot;) are passed on to the contained image.</p>
<dl class="docutils">
<dt><tt class="docutils literal">align</tt> <span class="classifier-delimiter">:</span> <span class="classifier">&quot;left&quot;, &quot;center&quot;, or &quot;right&quot;</span></dt>
<dd>The horizontal alignment of the figure, allowing the image to
float and have the text flow around it.  The specific behavior
depends upon the browser or rendering software used.</dd>
</dl>
<p>In addition, the following options are recognized:</p>
<dl class="docutils">
<dt><tt class="docutils literal">figwidth</tt> <span class="classifier-delimiter">:</span> <span class="classifier">&quot;image&quot;, <a class="reference external" href="restructuredtext.html#length-units">length</a>, or <a class="reference external" href="restructuredtext.html#percentage-units">percentage</a> of current line width</span></dt>
<dd><p class="first">The width of the figure.
Limits the horizontal space used by the figure.
A special value of &quot;image&quot; is allowed, in which case the
included image's actual width is used (requires the <a class="reference external" href="http://www.pythonware.com/products/pil/">Python Imaging
Library</a>). If the image file is not found or the required software is
unavailable, this option is ignored.</p>
<p>Sets the &quot;width&quot; attribute of the &quot;figure&quot; doctree element.</p>
<p>This option does not scale the included image; use the &quot;width&quot;
<a class="reference external" href="../doctree.html#image">image</a> option for that.</p>
<pre class="last literal-block">
+---------------------------+
|        figure             |
|                           |
|&lt;------ figwidth ---------&gt;|
|                           |
|  +---------------------+  |
|  |     image           |  |
|  |                     |  |
|  |&lt;--- width ---------&gt;|  |
|  +---------------------+  |
|                           |
|The figure's caption should|
|wrap at this width.        |
+---------------------------+
</pre>
</dd>
<dt><tt class="docutils literal">figclass</tt> <span class="classifier-delimiter">:</span> <span class="classifier">text</span></dt>
<dd>Set a <a class="reference external" href="../doctree.html#classes">&quot;classes&quot;</a> attribute value on the figure element.  See the
<a class="reference internal" href="#class">class</a> directive below.</dd>
</dl>
</div>
</div>
<div class="section" id="body-elements">
<h1><a class="toc-backref" href="#id31">Body Elements</a></h1>
<div class="section" id="topic">
<h2><a class="toc-backref" href="#id32">Topic</a></h2>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;topic&quot;</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Doctree Element:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body"><a class="reference external" href="../doctree.html#topic">topic</a></td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Arguments:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">1, required (topic title).</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Options:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body"><a class="reference internal" href="#id15">:class:</a>, <a class="reference internal" href="#name">:name:</a></td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Content:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">Interpreted as the topic body.</td>
</tr>
</tbody>
</table>
<p>A topic is like a block quote with a title, or a self-contained
section with no subsections.  Use the &quot;topic&quot; directive to indicate a
self-contained idea that is separate from the flow of the document.
Topics may occur anywhere a section or transition may occur.  Body
elements and topics may not contain nested topics.</p>
<p>The directive's sole argument is interpreted as the topic title; the
next line must be blank.  All subsequent lines make up the topic body,
interpreted as body elements.  For example:</p>
<pre class="literal-block">
.. topic:: Topic Title

    Subsequent indented lines comprise
    the body of the topic, and are
    interpreted as body elements.
</pre>
</div>
<div class="section" id="sidebar">
<h2><a class="toc-backref" href="#id33">Sidebar</a></h2>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;sidebar&quot;</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Doctree Element:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body"><a class="reference external" href="../doctree.html#sidebar">sidebar</a></td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Arguments:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">One, required (sidebar title).</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Options:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">Possible (see below).</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Content:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">Interpreted as the sidebar body.</td>
</tr>
</tbody>
</table>
<p>Sidebars are like miniature, parallel documents that occur inside
other documents, providing related or reference material.  A sidebar
is typically offset by a border and &quot;floats&quot; to the side of the page;
the document's main text may flow around it.  Sidebars can also be
likened to super-footnotes; their content is outside of the flow of
the document's main text.</p>
<p>Sidebars may occur anywhere a section or transition may occur.  Body
elements (including sidebars) may not contain nested sidebars.</p>
<p>The directive's sole argument is interpreted as the sidebar title,
which may be followed by a subtitle option (see below); the next line
must be blank.  All subsequent lines make up the sidebar body,
interpreted as body elements.  For example:</p>
<pre class="literal-block">
.. sidebar:: Sidebar Title
   :subtitle: Optional Sidebar Subtitle

   Subsequent indented lines comprise
   the body of the sidebar, and are
   interpreted as body elements.
</pre>
<p>The following options are recognized:</p>
<dl class="docutils">
<dt><tt class="docutils literal">subtitle</tt> <span class="classifier-delimiter">:</span> <span class="classifier">text</span></dt>
<dd>The sidebar's subtitle.</dd>
</dl>
<p>and the common options <a class="reference internal" href="#id15">:class:</a> and <a class="reference internal" href="#name">:name:</a>.</p>
</div>
<div class="section" id="line-block">
<h2><a class="toc-backref" href="#id34">Line Block</a></h2>
<div class="admonition-deprecated admonition">
<p class="first admonition-title">Deprecated</p>
<p class="last">The &quot;line-block&quot; directive is deprecated.  Use the <a class="reference external" href="restructuredtext.html#line-blocks">line block
syntax</a> instead.</p>
</div>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;line-block&quot;</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Doctree Element:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body"><a class="reference external" href="../doctree.html#line-block">line_block</a></td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Arguments:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">None.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Options:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body"><a class="reference internal" href="#id15">:class:</a>, <a class="reference internal" href="#name">:name:</a></td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Content:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">Becomes the body of the line block.</td>
</tr>
</tbody>
</table>
<p>The &quot;line-block&quot; directive constructs an element where line breaks and
initial indentation is significant and inline markup is supported.  It
is equivalent to a <a class="reference internal" href="#parsed-literal-block">parsed literal block</a> with different rendering:
typically in an ordinary serif typeface instead of a
typewriter/monospaced face, and not automatically indented.  (Have the
line-block directive begin a block quote to get an indented line
block.)  Line blocks are useful for address blocks and verse (poetry,
song lyrics), where the structure of lines is significant.  For
example, here's a classic:</p>
<pre class="literal-block">
&quot;To Ma Own Beloved Lassie: A Poem on her 17th Birthday&quot;, by
Ewan McTeagle (for Lassie O'Shea):

    .. line-block::

        Lend us a couple of bob till Thursday.
        I'm absolutely skint.
        But I'm expecting a postal order and I can pay you back
            as soon as it comes.
        Love, Ewan.
</pre>
</div>
<div class="section" id="parsed-literal-block">
<span id="parsed-literal"></span><h2><a class="toc-backref" href="#id35">Parsed Literal Block</a></h2>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;parsed-literal&quot;</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Doctree Element:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body"><a class="reference external" href="../doctree.html#literal-block">literal_block</a></td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Arguments:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">None.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Options:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body"><a class="reference internal" href="#id15">:class:</a>, <a class="reference internal" href="#name">:name:</a></td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Content:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">Becomes the body of the literal block.</td>
</tr>
</tbody>
</table>
<p>Unlike an ordinary literal block, the &quot;parsed-literal&quot; directive
constructs a literal block where the text is parsed for inline markup.
It is equivalent to a <a class="reference internal" href="#line-block">line block</a> with different rendering:
typically in a typewriter/monospaced typeface, like an ordinary
literal block.  Parsed literal blocks are useful for adding hyperlinks
to code examples.</p>
<p>However, care must be taken with the text, because inline markup is
recognized and there is no protection from parsing.  Backslash-escapes
may be necessary to prevent unintended parsing.  And because the
markup characters are removed by the parser, care must also be taken
with vertical alignment.  Parsed &quot;ASCII art&quot; is tricky, and extra
whitespace may be necessary.</p>
<p>For example, all the element names in this content model are links:</p>
<pre class="literal-block">
.. parsed-literal::

   ( (title_, subtitle_?)?,
     decoration_?,
     (docinfo_, transition_?)?,
     `%structure.model;`_ )
</pre>
</div>
<div class="section" id="code">
<h2><a class="toc-backref" href="#id36">Code</a></h2>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;code&quot;</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Doctree Element:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body"><a class="reference external" href="../doctree.html#literal-block">literal_block</a>, <a class="reference external" href="../doctree.html#inline-elements">inline elements</a></td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Arguments:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">One, optional (formal language).</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Options:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">name, class, number-lines.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Content:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">Becomes the body of the literal block.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Configuration Setting:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body"><a class="reference external" href="../../user/config.html#syntax-highlight">syntax_highlight</a>.</td>
</tr>
</tbody>
</table>
<p>(New in Docutils 0.9)</p>
<p>The &quot;code&quot; directive constructs a literal block. If the code language is
specified, the content is parsed by the <a class="reference external" href="http://pygments.org/">Pygments</a> syntax highlighter and
tokens are stored in nested <a class="reference external" href="../doctree.html#inline-elements">inline elements</a> with class arguments
according to their syntactic category. The actual highlighting requires
a style-sheet (e.g. one <a class="reference external" href="http://pygments.org/docs/cmdline/#generating-styles">generated by Pygments</a>, see the
<a class="reference external" href="http://docutils.sourceforge.net/sandbox/stylesheets/">sandbox/stylesheets</a> for examples).</p>
<p>The parsing can be turned off with the <a class="reference external" href="../../user/config.html#syntax-highlight">syntax_highlight</a> configuration
setting and command line option or by specifying the language as <a class="reference internal" href="#id15">:class:</a>
option instead of directive argument. This also avoids warnings
when <a class="reference external" href="http://pygments.org/">Pygments</a> is not installed or the language is not in the
<a class="reference external" href="http://pygments.org/languages/">supported languages and markup formats</a>.</p>
<p>For inline code, use the <a class="reference external" href="roles.html#code">&quot;code&quot; role</a>.</p>
<p>The following options are recognized:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">number-lines</span></tt> <span class="classifier-delimiter">:</span> <span class="classifier">[start line number]</span></dt>
<dd>Precede every line with a line number.
The optional argument is the number of the first line (defaut 1).</dd>
</dl>
<p>and the common options <a class="reference internal" href="#id15">:class:</a> and <a class="reference internal" href="#name">:name:</a>.</p>
<dl class="docutils">
<dt>Example::</dt>
<dd><p class="first">The content of the following directive</p>
<pre class="literal-block">
.. code:: python

  def my_function():
      &quot;just a test&quot;
      print 8/2
</pre>
<p class="last">is parsed and marked up as Python source code.</p>
</dd>
</dl>
</div>
<div class="section" id="math">
<h2><a class="toc-backref" href="#id37">Math</a></h2>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;math&quot;</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Doctree Element:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body"><a class="reference external" href="../doctree.html#math-block">math_block</a></td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Arguments:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">One, optional: prepended to content.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Options:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body"><a class="reference internal" href="#id15">:class:</a>, <a class="reference internal" href="#name">:name:</a></td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Content:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">Interpreted as math block(s).
Content blocks separated by a blank line are put in
separate math-block doctree elements.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Configuration Setting:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body"><a class="reference external" href="../../user/config.html#math-output">math_output</a></td>
</tr>
</tbody>
</table>
<p>(New in Docutils 0.8)</p>
<p>The &quot;math&quot; directive inserts blocks with mathematical content
(display formulas, equations) into the document. The input format is
<em>LaTeX math syntax</em><a class="footnote-reference" href="#math-syntax" id="id3">[1]</a> with support for Unicode
symbols, for example:</p>
<pre class="literal-block">
.. math::

  α_t(i) = P(O_1, O_2, … O_t, q_t = S_i λ)
</pre>
<p>Support is limited to a subset of <em>LaTeX math</em> by the conversion
required for many output formats.  For HTML, the the <a class="reference external" href="../../user/config.html#math-output">math_output</a>
configuration setting (or the corresponding <tt class="docutils literal"><span class="pre">--math-output</span></tt>
command line option) select between alternative output formats with
different subsets of supported elements. If a writer does not
support math typesetting at all, the content is inserted verbatim.</p>
<table class="docutils footnote" frame="void" id="math-syntax" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id3">[1]</a></td><td>The supported LaTeX commands include AMS extensions
(see, e.g., the <a class="reference external" href="ftp://ftp.ams.org/ams/doc/amsmath/short-math-guide.pdf">Short Math Guide</a>).</td></tr>
</tbody>
</table>
<p>For inline math, use the <a class="reference external" href="roles.html#math">&quot;math&quot; role</a>.</p>
</div>
<div class="section" id="rubric">
<h2><a class="toc-backref" href="#id38">Rubric</a></h2>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;rubric&quot;</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Doctree Element:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body"><a class="reference external" href="../doctree.html#rubric">rubric</a></td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Arguments:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">1, required (rubric text).</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Options:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body"><a class="reference internal" href="#id15">:class:</a>, <a class="reference internal" href="#name">:name:</a></td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Content:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">None.</td>
</tr>
</tbody>
</table>
<!--  -->
<blockquote>
<p>rubric n. 1. a title, heading, or the like, in a manuscript,
book, statute, etc., written or printed in red or otherwise
distinguished from the rest of the text. ...</p>
<p class="attribution">&mdash;Random House Webster's College Dictionary, 1991</p>
</blockquote>
<p>The &quot;rubric&quot; directive inserts a &quot;rubric&quot; element into the document
tree.  A rubric is like an informal heading that doesn't correspond to
the document's structure.</p>
</div>
<div class="section" id="epigraph">
<h2><a class="toc-backref" href="#id39">Epigraph</a></h2>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;epigraph&quot;</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Doctree Element:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body"><a class="reference external" href="../doctree.html#block-quote">block_quote</a></td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Arguments:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">None.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Options:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">None.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Content:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">Interpreted as the body of the block quote.</td>
</tr>
</tbody>
</table>
<p>An epigraph is an apposite (suitable, apt, or pertinent) short
inscription, often a quotation or poem, at the beginning of a document
or section.</p>
<p>The &quot;epigraph&quot; directive produces an &quot;epigraph&quot;-class block quote.
For example, this input:</p>
<pre class="literal-block">
.. epigraph::

   No matter where you go, there you are.

   -- Buckaroo Banzai
</pre>
<p>becomes this document tree fragment:</p>
<pre class="literal-block">
&lt;block_quote classes=&quot;epigraph&quot;&gt;
    &lt;paragraph&gt;
        No matter where you go, there you are.
    &lt;attribution&gt;
        Buckaroo Banzai
</pre>
</div>
<div class="section" id="highlights">
<h2><a class="toc-backref" href="#id40">Highlights</a></h2>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;highlights&quot;</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Doctree Element:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body"><a class="reference external" href="../doctree.html#block-quote">block_quote</a></td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Arguments:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">None.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Options:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">None.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Content:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">Interpreted as the body of the block quote.</td>
</tr>
</tbody>
</table>
<p>Highlights summarize the main points of a document or section, often
consisting of a list.</p>
<p>The &quot;highlights&quot; directive produces a &quot;highlights&quot;-class block quote.
See <a class="reference internal" href="#epigraph">Epigraph</a> above for an analogous example.</p>
</div>
<div class="section" id="pull-quote">
<h2><a class="toc-backref" href="#id41">Pull-Quote</a></h2>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;pull-quote&quot;</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Doctree Element:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body"><a class="reference external" href="../doctree.html#block-quote">block_quote</a></td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Arguments:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">None.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Options:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">None.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Content:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">Interpreted as the body of the block quote.</td>
</tr>
</tbody>
</table>
<p>A pull-quote is a small selection of text &quot;pulled out and quoted&quot;,
typically in a larger typeface.  Pull-quotes are used to attract
attention, especially in long articles.</p>
<p>The &quot;pull-quote&quot; directive produces a &quot;pull-quote&quot;-class block quote.
See <a class="reference internal" href="#epigraph">Epigraph</a> above for an analogous example.</p>
</div>
<div class="section" id="compound-paragraph">
<h2><a class="toc-backref" href="#id42">Compound Paragraph</a></h2>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;compound&quot;</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Doctree Element:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body"><a class="reference external" href="../doctree.html#compound">compound</a></td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Arguments:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">None.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Options:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body"><a class="reference internal" href="#id15">:class:</a>, <a class="reference internal" href="#name">:name:</a></td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Content:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">Interpreted as body elements.</td>
</tr>
</tbody>
</table>
<p>(New in Docutils 0.3.6)</p>
<p>The &quot;compound&quot; directive is used to create a compound paragraph, which
is a single logical paragraph containing multiple physical body
elements such as simple paragraphs, literal blocks, tables, lists,
etc., instead of directly containing text and inline elements.  For
example:</p>
<pre class="literal-block">
.. compound::

   The 'rm' command is very dangerous.  If you are logged
   in as root and enter ::

       cd /
       rm -rf *

   you will erase the entire contents of your file system.
</pre>
<p>In the example above, a literal block is &quot;embedded&quot; within a sentence
that begins in one physical paragraph and ends in another.</p>
<div class="note">
<p class="first admonition-title">Note</p>
<p>The &quot;compound&quot; directive is <em>not</em> a generic block-level container
like HTML's <tt class="docutils literal">&lt;div&gt;</tt> element.  Do not use it only to group a
sequence of elements, or you may get unexpected results.</p>
<p class="last">If you need a generic block-level container, please use the
<a class="reference external" href="../doctree.html#container">container</a> directive, described below.</p>
</div>
<p>Compound paragraphs are typically rendered as multiple distinct text
blocks, with the possibility of variations to emphasize their logical
unity:</p>
<ul class="simple">
<li>If paragraphs are rendered with a first-line indent, only the first
physical paragraph of a compound paragraph should have that indent
-- second and further physical paragraphs should omit the indents;</li>
<li>vertical spacing between physical elements may be reduced;</li>
<li>and so on.</li>
</ul>
</div>
<div class="section" id="container">
<h2><a class="toc-backref" href="#id43">Container</a></h2>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;container&quot;</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Doctree Element:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body"><a class="reference external" href="../doctree.html#container">container</a></td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Arguments:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">One or more, optional (class names).</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Options:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body"><a class="reference internal" href="#name">:name:</a></td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Content:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">Interpreted as body elements.</td>
</tr>
</tbody>
</table>
<p>(New in Docutils 0.3.10)</p>
<p>The &quot;container&quot; directive surrounds its contents (arbitrary body
elements) with a generic block-level &quot;container&quot; element.  Combined
with the optional &quot;<a class="reference internal" href="#classes">classes</a>&quot; attribute argument(s), this is an
extension mechanism for users &amp; applications.  For example:</p>
<pre class="literal-block">
.. container:: custom

   This paragraph might be rendered in a custom way.
</pre>
<p>Parsing the above results in the following pseudo-XML:</p>
<pre class="literal-block">
&lt;container classes=&quot;custom&quot;&gt;
    &lt;paragraph&gt;
        This paragraph might be rendered in a custom way.
</pre>
<p>The &quot;container&quot; directive is the equivalent of HTML's <tt class="docutils literal">&lt;div&gt;</tt>
element.  It may be used to group a sequence of elements for user- or
application-specific purposes.</p>
</div>
</div>
<div class="section" id="tables">
<h1><a class="toc-backref" href="#id44">Tables</a></h1>
<p>Formal tables need more structure than the reStructuredText syntax
supplies.  Tables may be given titles with the <a class="reference external" href="../doctree.html#table">table</a> directive.
Sometimes reStructuredText tables are inconvenient to write, or table
data in a standard format is readily available.  The <a class="reference internal" href="#csv-table">csv-table</a>
directive supports CSV data.</p>
<div class="section" id="table">
<h2><a class="toc-backref" href="#id45">Table</a></h2>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;table&quot;</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Doctree Element:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body"><a class="reference external" href="../doctree.html#table">table</a></td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Arguments:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">1, optional (table title).</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Options:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body"><a class="reference internal" href="#id15">:class:</a>, <a class="reference internal" href="#name">:name:</a></td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Content:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">A normal reStructuredText table.</td>
</tr>
</tbody>
</table>
<p>(New in Docutils 0.3.1)</p>
<p>The &quot;table&quot; directive is used to create a titled table, to associate a
title with a table:</p>
<pre class="literal-block">
.. table:: Truth table for &quot;not&quot;

   =====  =====
     A    not A
   =====  =====
   False  True
   True   False
   =====  =====
</pre>
</div>
<div class="section" id="id4">
<span id="csv-table"></span><h2><a class="toc-backref" href="#id46">CSV Table</a></h2>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;csv-table&quot;</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Doctree Element:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body"><a class="reference external" href="../doctree.html#table">table</a></td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Arguments:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">1, optional (table title).</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Options:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">Possible (see below).</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Content:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">A CSV (comma-separated values) table.</td>
</tr>
</tbody>
</table>
<div class="warning">
<p class="first admonition-title">Warning</p>
<p class="last">The &quot;csv-table&quot; directive's &quot;:file:&quot; and &quot;:url:&quot; options represent
a potential security holes.  They can be disabled with the
&quot;<a class="reference external" href="../../user/config.html#file-insertion-enabled">file_insertion_enabled</a>&quot; runtime setting.</p>
</div>
<p>(New in Docutils 0.3.4)</p>
<p>The &quot;csv-table&quot; directive is used to create a table from CSV
(comma-separated values) data.  CSV is a common data format generated
by spreadsheet applications and commercial databases.  The data may be
internal (an integral part of the document) or external (a separate
file).</p>
<p>Example:</p>
<pre class="literal-block">
.. csv-table:: Frozen Delights!
   :header: &quot;Treat&quot;, &quot;Quantity&quot;, &quot;Description&quot;
   :widths: 15, 10, 30

   &quot;Albatross&quot;, 2.99, &quot;On a stick!&quot;
   &quot;Crunchy Frog&quot;, 1.49, &quot;If we took the bones out, it wouldn't be
   crunchy, now would it?&quot;
   &quot;Gannet Ripple&quot;, 1.99, &quot;On a stick!&quot;
</pre>
<p>Block markup and inline markup within cells is supported.  Line ends
are recognized within cells.</p>
<p>Working limitations:</p>
<ul class="simple">
<li>There is no support for checking that the number of columns in each
row is the same.  However, this directive supports CSV generators
that do not insert &quot;empty&quot; entries at the end of short rows, by
automatically adding empty entries.<!-- Add "strict" option to verify input? -->
</li>
</ul>
<table class="docutils footnote" frame="void" id="whitespace-delim" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id5">[2]</a></td><td>Whitespace delimiters are supported only for external
CSV files.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="ascii-char" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label">[3]</td><td><em>(<a class="fn-backref" href="#id6">1</a>, <a class="fn-backref" href="#id7">2</a>, <a class="fn-backref" href="#id8">3</a>)</em> With Python&nbsp;2, the valuess for the <tt class="docutils literal">delimiter</tt>,
<tt class="docutils literal">quote</tt>, and <tt class="docutils literal">escape</tt> options must be ASCII characters. (The csv
module does not support Unicode and all non-ASCII characters are
encoded as multi-byte utf-8 string). This limitation does not exist
under Python&nbsp;3.</td></tr>
</tbody>
</table>
<p>The following options are recognized:</p>
<dl class="docutils">
<dt><tt class="docutils literal">widths</tt> <span class="classifier-delimiter">:</span> <span class="classifier">integer [, integer...]</span></dt>
<dd>A comma- or space-separated list of relative column widths.  The
default is equal-width columns (100%/#columns).</dd>
<dt><tt class="docutils literal"><span class="pre">header-rows</span></tt> <span class="classifier-delimiter">:</span> <span class="classifier">integer</span></dt>
<dd>The number of rows of CSV data to use in the table header.
Defaults to 0.</dd>
<dt><tt class="docutils literal"><span class="pre">stub-columns</span></tt> <span class="classifier-delimiter">:</span> <span class="classifier">integer</span></dt>
<dd>The number of table columns to use as stubs (row titles, on the
left).  Defaults to 0.</dd>
<dt><tt class="docutils literal">header</tt> <span class="classifier-delimiter">:</span> <span class="classifier">CSV data</span></dt>
<dd>Supplemental data for the table header, added independently of and
before any <tt class="docutils literal"><span class="pre">header-rows</span></tt> from the main CSV data.  Must use the
same CSV format as the main CSV data.</dd>
<dt><tt class="docutils literal">file</tt> <span class="classifier-delimiter">:</span> <span class="classifier">string (newlines removed)</span></dt>
<dd>The local filesystem path to a CSV data file.</dd>
<dt><tt class="docutils literal">url</tt> <span class="classifier-delimiter">:</span> <span class="classifier">string (whitespace removed)</span></dt>
<dd>An Internet URL reference to a CSV data file.</dd>
<dt><tt class="docutils literal">encoding</tt> <span class="classifier-delimiter">:</span> <span class="classifier">name of text encoding</span></dt>
<dd>The text encoding of the external CSV data (file or URL).
Defaults to the document's encoding (if specified).</dd>
<dt><tt class="docutils literal">delim</tt> <span class="classifier-delimiter">:</span> <span class="classifier">char | &quot;tab&quot; | &quot;space&quot; <a class="footnote-reference" href="#whitespace-delim" id="id5">[2]</a></span></dt>
<dd>A one-character string<a class="footnote-reference" href="#ascii-char" id="id6">[3]</a> used to separate fields.
Defaults to <tt class="docutils literal">,</tt> (comma).  May be specified as a Unicode code
point; see the <a class="reference internal" href="#unicode">unicode</a> directive for syntax details.</dd>
<dt><tt class="docutils literal">quote</tt> <span class="classifier-delimiter">:</span> <span class="classifier">char</span></dt>
<dd>A one-character string<a class="footnote-reference" href="#ascii-char" id="id7">[3]</a> used to quote elements
containing the delimiter or which start with the quote
character.  Defaults to <tt class="docutils literal">&quot;</tt> (quote).  May be specified as a
Unicode code point; see the <a class="reference internal" href="#unicode">unicode</a> directive for syntax
details.</dd>
<dt><tt class="docutils literal">keepspace</tt> <span class="classifier-delimiter">:</span> <span class="classifier">flag</span></dt>
<dd>Treat whitespace immediately following the delimiter as
significant.  The default is to ignore such whitespace.</dd>
<dt><tt class="docutils literal">escape</tt> <span class="classifier-delimiter">:</span> <span class="classifier">char</span></dt>
<dd>A one-character<a class="footnote-reference" href="#ascii-char" id="id8">[3]</a> string used to escape the
delimiter or quote characters.  May be specified as a Unicode
code point; see the <a class="reference internal" href="#unicode">unicode</a> directive for syntax details.  Used
when the delimiter is used in an unquoted field, or when quote
characters are used within a field.  The default is to double-up
the character, e.g. &quot;He said, &quot;&quot;Hi!&quot;&quot;&quot;<!-- Add another possible value, "double", to explicitly indicate
the default case? -->
</dd>
</dl>
<p>and the common options <a class="reference internal" href="#id15">:class:</a> and <a class="reference internal" href="#name">:name:</a>.</p>
</div>
<div class="section" id="list-table">
<h2><a class="toc-backref" href="#id47">List Table</a></h2>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;list-table&quot;</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Doctree Element:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body"><a class="reference external" href="../doctree.html#table">table</a></td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Arguments:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">1, optional (table title).</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Options:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">Possible (see below).</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Content:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">A uniform two-level bullet list.</td>
</tr>
</tbody>
</table>
<p>(New in Docutils 0.3.8.  This is an initial implementation; <a class="reference external" href="../../dev/rst/alternatives.html#list-driven-tables">further
ideas</a> may be implemented in the future.)</p>
<p>The &quot;list-table&quot; directive is used to create a table from data in a
uniform two-level bullet list.  &quot;Uniform&quot; means that each sublist
(second-level list) must contain the same number of list items.</p>
<p>Example:</p>
<pre class="literal-block">
.. list-table:: Frozen Delights!
   :widths: 15 10 30
   :header-rows: 1

   * - Treat
     - Quantity
     - Description
   * - Albatross
     - 2.99
     - On a stick!
   * - Crunchy Frog
     - 1.49
     - If we took the bones out, it wouldn't be
       crunchy, now would it?
   * - Gannet Ripple
     - 1.99
     - On a stick!
</pre>
<p>The following options are recognized:</p>
<dl class="docutils">
<dt><tt class="docutils literal">widths</tt> <span class="classifier-delimiter">:</span> <span class="classifier">integer [integer...]</span></dt>
<dd>A comma- or space-separated list of relative column widths.  The
default is equal-width columns (100%/#columns).</dd>
<dt><tt class="docutils literal"><span class="pre">header-rows</span></tt> <span class="classifier-delimiter">:</span> <span class="classifier">integer</span></dt>
<dd>The number of rows of list data to use in the table header.
Defaults to 0.</dd>
<dt><tt class="docutils literal"><span class="pre">stub-columns</span></tt> <span class="classifier-delimiter">:</span> <span class="classifier">integer</span></dt>
<dd>The number of table columns to use as stubs (row titles, on the
left).  Defaults to 0.</dd>
</dl>
<p>and the common options <a class="reference internal" href="#id15">:class:</a> and <a class="reference internal" href="#name">:name:</a>.</p>
</div>
</div>
<div class="section" id="document-parts">
<h1><a class="toc-backref" href="#id48">Document Parts</a></h1>
<div class="section" id="table-of-contents">
<span id="id10"></span><h2><a class="toc-backref" href="#id49">Table of Contents</a></h2>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;contents&quot;</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Doctree Elements:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body"><a class="reference external" href="../doctree.html#pending">pending</a>, <a class="reference external" href="../doctree.html#topic">topic</a></td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Arguments:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">One, optional: title.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Options:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">Possible.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Content:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">None.</td>
</tr>
</tbody>
</table>
<p>The &quot;contents&quot; directive generates a table of contents (TOC) in a
<a class="reference external" href="../doctree.html#topic">topic</a>.  Topics, and therefore tables of contents, may occur anywhere
a section or transition may occur.  Body elements and topics may not
contain tables of contents.</p>
<p>Here's the directive in its simplest form:</p>
<pre class="literal-block">
.. contents::
</pre>
<p>Language-dependent boilerplate text will be used for the title.  The
English default title text is &quot;Contents&quot;.</p>
<p>An explicit title may be specified:</p>
<pre class="literal-block">
.. contents:: Table of Contents
</pre>
<p>The title may span lines, although it is not recommended:</p>
<pre class="literal-block">
.. contents:: Here's a very long Table of
   Contents title
</pre>
<p>Options may be specified for the directive, using a field list:</p>
<pre class="literal-block">
.. contents:: Table of Contents
   :depth: 2
</pre>
<p>If the default title is to be used, the options field list may begin
on the same line as the directive marker:</p>
<pre class="literal-block">
.. contents:: :depth: 2
</pre>
<p>The following options are recognized:</p>
<dl class="docutils">
<dt><tt class="docutils literal">depth</tt> <span class="classifier-delimiter">:</span> <span class="classifier">integer</span></dt>
<dd>The number of section levels that are collected in the table of
contents.  The default is unlimited depth.</dd>
<dt><tt class="docutils literal">local</tt> <span class="classifier-delimiter">:</span> <span class="classifier">flag (empty)</span></dt>
<dd>Generate a local table of contents.  Entries will only include
subsections of the section in which the directive is given.  If no
explicit title is given, the table of contents will not be titled.</dd>
<dt><tt class="docutils literal">backlinks</tt> <span class="classifier-delimiter">:</span> <span class="classifier">&quot;entry&quot; or &quot;top&quot; or &quot;none&quot;</span></dt>
<dd>Generate links from section headers back to the table of contents
entries, the table of contents itself, or generate no backlinks.</dd>
<dt><tt class="docutils literal">class</tt> <span class="classifier-delimiter">:</span> <span class="classifier">text</span></dt>
<dd>Set a <a class="reference external" href="../doctree.html#classes">&quot;classes&quot;</a> attribute value on the topic element.  See the
<a class="reference internal" href="#class">class</a> directive below.</dd>
</dl>
</div>
<div class="section" id="automatic-section-numbering">
<span id="section-autonumbering"></span><span id="sectnum"></span><h2><a class="toc-backref" href="#id50">Automatic Section Numbering</a></h2>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;sectnum&quot; or &quot;section-autonumbering&quot; (synonyms)</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Doctree Elements:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body"><a class="reference external" href="../doctree.html#pending">pending</a>, <a class="reference external" href="../doctree.html#generated">generated</a></td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Arguments:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">None.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Options:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">Possible.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Content:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">None.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Configuration Setting:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body"><a class="reference external" href="../../user/config.html#sectnum-xform">sectnum_xform</a></td>
</tr>
</tbody>
</table>
<p>The &quot;sectnum&quot; (or &quot;section-autonumbering&quot;) directive automatically numbers
sections and subsections in a document (if not disabled by the
<tt class="docutils literal"><span class="pre">--no-section-numbering</span></tt> command line option or the <a class="reference external" href="../../user/config.html#sectnum-xform">sectnum_xform</a>
configuration setting).</p>
<p>Section numbers are of the &quot;multiple enumeration&quot; form, where each
level has a number, separated by periods.  For example, the title of section
1, subsection 2, subsubsection 3 would have &quot;1.2.3&quot; prefixed.</p>
<p>The &quot;sectnum&quot; directive does its work in two passes: the initial parse
and a transform.  During the initial parse, a &quot;pending&quot; element is
generated which acts as a placeholder, storing any options internally.
At a later stage in the processing, the &quot;pending&quot; element triggers a
transform, which adds section numbers to titles.  Section numbers are
enclosed in a &quot;generated&quot; element, and titles have their &quot;auto&quot;
attribute set to &quot;1&quot;.</p>
<p>The following options are recognized:</p>
<dl class="docutils">
<dt><tt class="docutils literal">depth</tt> <span class="classifier-delimiter">:</span> <span class="classifier">integer</span></dt>
<dd>The number of section levels that are numbered by this directive.
The default is unlimited depth.</dd>
<dt><tt class="docutils literal">prefix</tt> <span class="classifier-delimiter">:</span> <span class="classifier">string</span></dt>
<dd>An arbitrary string that is prefixed to the automatically
generated section numbers.  It may be something like &quot;3.2.&quot;, which
will produce &quot;3.2.1&quot;, &quot;3.2.2&quot;, &quot;3.2.2.1&quot;, and so on.  Note that
any separating punctuation (in the example, a period, &quot;.&quot;) must be
explicitly provided.  The default is no prefix.</dd>
<dt><tt class="docutils literal">suffix</tt> <span class="classifier-delimiter">:</span> <span class="classifier">string</span></dt>
<dd>An arbitrary string that is appended to the automatically
generated section numbers.  The default is no suffix.</dd>
<dt><tt class="docutils literal">start</tt> <span class="classifier-delimiter">:</span> <span class="classifier">integer</span></dt>
<dd>The value that will be used for the first section number.
Combined with <tt class="docutils literal">prefix</tt>, this may be used to force the right
numbering for a document split over several source files.  The
default is 1.</dd>
</dl>
</div>
<div class="section" id="document-header-footer">
<span id="footer"></span><span id="header"></span><h2><a class="toc-backref" href="#id51">Document Header &amp; Footer</a></h2>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name" colspan="2">Directive Types:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">&quot;header&quot; and &quot;footer&quot;</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Doctree Elements:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body"><a class="reference external" href="../doctree.html#decoration">decoration</a>, header, footer</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Arguments:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">None.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Options:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">None.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Content:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">Interpreted as body elements.</td>
</tr>
</tbody>
</table>
<p>(New in Docutils 0.3.8)</p>
<p>The &quot;header&quot; and &quot;footer&quot; directives create document decorations,
useful for page navigation, notes, time/datestamp, etc.  For example:</p>
<pre class="literal-block">
.. header:: This space for rent.
</pre>
<p>This will add a paragraph to the document header, which will appear at
the top of the generated web page or at the top of every printed page.</p>
<p>These directives may be used multiple times, cumulatively.  There is
currently support for only one header and footer.</p>
<div class="note">
<p class="first admonition-title">Note</p>
<p>While it is possible to use the &quot;header&quot; and &quot;footer&quot; directives to
create navigational elements for web pages, you should be aware
that Docutils is meant to be used for <em>document</em> processing, and
that a navigation bar is not typically part of a document.</p>
<p class="last">Thus, you may soon find Docutils' abilities to be insufficient for
these purposes.  At that time, you should consider using a
documentation generator like <a class="reference external" href="http://sphinx-doc.org/">Sphinx</a> rather than the &quot;header&quot; and
&quot;footer&quot; directives.</p>
</div>
<p>In addition to the use of these directives to populate header and
footer content, content may also be added automatically by the
processing system.  For example, if certain runtime settings are
enabled, the document footer is populated with processing information
such as a datestamp, a link to <a class="reference external" href="http://docutils.sourceforge.net">the Docutils website</a>, etc.</p>
</div>
</div>
<div class="section" id="references">
<h1><a class="toc-backref" href="#id52">References</a></h1>
<div class="section" id="target-footnotes">
<span id="target-notes"></span><h2><a class="toc-backref" href="#id53">Target Footnotes</a></h2>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;target-notes&quot;</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Doctree Elements:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body"><a class="reference external" href="../doctree.html#pending">pending</a>, <a class="reference external" href="../doctree.html#footnote">footnote</a>, <a class="reference external" href="../doctree.html#footnote-reference">footnote_reference</a></td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Arguments:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">None.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Options:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body"><a class="reference internal" href="#id15">:class:</a>, <a class="reference internal" href="#name">:name:</a></td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Options:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">Possible.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Content:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">None.</td>
</tr>
</tbody>
</table>
<p>The &quot;target-notes&quot; directive creates a footnote for each external
target in the text, and corresponding footnote references after each
reference.  For every explicit target (of the form, <tt class="docutils literal">.. _target name:
URL</tt>) in the text, a footnote will be generated containing the
visible URL as content.</p>
</div>
<div class="section" id="footnotes">
<h2><a class="toc-backref" href="#id54">Footnotes</a></h2>
<p><strong>NOT IMPLEMENTED YET</strong></p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;footnotes&quot;</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Doctree Elements:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body"><a class="reference external" href="../doctree.html#pending">pending</a>, <a class="reference external" href="../doctree.html#topic">topic</a></td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Arguments:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">None?</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Options:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">Possible?</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Content:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">None.</td>
</tr>
</tbody>
</table>
<p>&#64;&#64;&#64;</p>
</div>
<div class="section" id="citations">
<h2><a class="toc-backref" href="#id55">Citations</a></h2>
<p><strong>NOT IMPLEMENTED YET</strong></p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;citations&quot;</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Doctree Elements:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body"><a class="reference external" href="../doctree.html#pending">pending</a>, <a class="reference external" href="../doctree.html#topic">topic</a></td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Arguments:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">None?</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Options:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">Possible?</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Content:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">None.</td>
</tr>
</tbody>
</table>
<p>&#64;&#64;&#64;</p>
</div>
</div>
<div class="section" id="html-specific">
<h1><a class="toc-backref" href="#id56">HTML-Specific</a></h1>
<div class="section" id="meta">
<h2><a class="toc-backref" href="#id57">Meta</a></h2>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;meta&quot;</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Doctree Element:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">meta (non-standard)</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Arguments:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">None.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Options:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">None.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Content:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">Must contain a flat field list.</td>
</tr>
</tbody>
</table>
<p>The &quot;meta&quot; directive is used to specify HTML metadata stored in HTML
META tags.  &quot;Metadata&quot; is data about data, in this case data about web
pages.  Metadata is used to describe and classify web pages in the
World Wide Web, in a form that is easy for search engines to extract
and collate.</p>
<p>Within the directive block, a flat field list provides the syntax for
metadata.  The field name becomes the contents of the &quot;name&quot; attribute
of the META tag, and the field body (interpreted as a single string
without inline markup) becomes the contents of the &quot;content&quot;
attribute.  For example:</p>
<pre class="literal-block">
.. meta::
   :description: The reStructuredText plaintext markup language
   :keywords: plaintext, markup language
</pre>
<p>This would be converted to the following HTML:</p>
<pre class="literal-block">
&lt;meta name=&quot;description&quot;
    content=&quot;The reStructuredText plaintext markup language&quot;&gt;
&lt;meta name=&quot;keywords&quot; content=&quot;plaintext, markup language&quot;&gt;
</pre>
<p>Support for other META attributes (&quot;http-equiv&quot;, &quot;scheme&quot;, &quot;lang&quot;,
&quot;dir&quot;) are provided through field arguments, which must be of the form
&quot;attr=value&quot;:</p>
<pre class="literal-block">
.. meta::
   :description lang=en: An amusing story
   :description lang=fr: Une histoire amusante
</pre>
<p>And their HTML equivalents:</p>
<pre class="literal-block">
&lt;meta name=&quot;description&quot; lang=&quot;en&quot; content=&quot;An amusing story&quot;&gt;
&lt;meta name=&quot;description&quot; lang=&quot;fr&quot; content=&quot;Une histoire amusante&quot;&gt;
</pre>
<p>Some META tags use an &quot;http-equiv&quot; attribute instead of the &quot;name&quot;
attribute.  To specify &quot;http-equiv&quot; META tags, simply omit the name:</p>
<pre class="literal-block">
.. meta::
   :http-equiv=Content-Type: text/html; charset=ISO-8859-1
</pre>
<p>HTML equivalent:</p>
<pre class="literal-block">
&lt;meta http-equiv=&quot;Content-Type&quot;
     content=&quot;text/html; charset=ISO-8859-1&quot;&gt;
</pre>
</div>
<div class="section" id="imagemap">
<h2><a class="toc-backref" href="#id58">Imagemap</a></h2>
<p><strong>NOT IMPLEMENTED YET</strong></p>
<p>Non-standard element: imagemap.</p>
</div>
</div>
<div class="section" id="directives-for-substitution-definitions">
<h1><a class="toc-backref" href="#id59">Directives for Substitution Definitions</a></h1>
<p>The directives in this section may only be used in substitution
definitions.  They may not be used directly, in standalone context.
The <a class="reference external" href="../doctree.html#image">image</a> directive may be used both in substitution definitions
and in the standalone context.</p>
<div class="section" id="replacement-text">
<span id="replace"></span><h2><a class="toc-backref" href="#id60">Replacement Text</a></h2>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;replace&quot;</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Doctree Element:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">Text &amp; <a class="reference external" href="../doctree.html#inline-elements">inline elements</a></td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Arguments:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">None.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Options:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">None.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Content:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">A single paragraph; may contain inline markup.</td>
</tr>
</tbody>
</table>
<p>The &quot;replace&quot; directive is used to indicate replacement text for a
substitution reference.  It may be used within substitution
definitions only.  For example, this directive can be used to expand
abbreviations:</p>
<pre class="literal-block">
.. |reST| replace:: reStructuredText

Yes, |reST| is a long word, so I can't blame anyone for wanting to
abbreviate it.
</pre>
<p>As reStructuredText doesn't support nested inline markup, the only way
to create a reference with styled text is to use substitutions with
the &quot;replace&quot; directive:</p>
<pre class="literal-block">
I recommend you try |Python|_.

.. |Python| replace:: Python, *the* best language around
.. _Python: http://www.python.org/
</pre>
</div>
<div class="section" id="unicode-character-codes">
<span id="unicode"></span><h2><a class="toc-backref" href="#id61">Unicode Character Codes</a></h2>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;unicode&quot;</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Doctree Element:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">Text</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Arguments:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">One or more, required (Unicode character codes,
optional text, and comments).</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Options:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">Possible.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Content:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">None.</td>
</tr>
</tbody>
</table>
<p>The &quot;unicode&quot; directive converts Unicode character codes (numerical
values) to characters, and may be used in substitution definitions
only.</p>
<p>The arguments, separated by spaces, can be:</p>
<ul class="simple">
<li><strong>character codes</strong> as<ul>
<li>decimal numbers or</li>
<li>hexadecimal numbers, prefixed by <tt class="docutils literal">0x</tt>, <tt class="docutils literal">x</tt>, <tt class="docutils literal">\x</tt>, <tt class="docutils literal">U+</tt>,
<tt class="docutils literal">u</tt>, or <tt class="docutils literal">\u</tt> or as XML-style hexadecimal character entities,
e.g. <tt class="docutils literal">&amp;#x1a2b;</tt></li>
</ul>
</li>
<li><strong>text</strong>, which is used as-is.</li>
</ul>
<p>Text following &quot; .. &quot; is a comment and is ignored.  The spaces between
the arguments are ignored and thus do not appear in the output.
Hexadecimal codes are case-insensitive.</p>
<p>For example, the following text:</p>
<pre class="literal-block">
Copyright |copy| 2003, |BogusMegaCorp (TM)| |---|
all rights reserved.

.. |copy| unicode:: 0xA9 .. copyright sign
.. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122
   .. with trademark sign
.. |---| unicode:: U+02014 .. em dash
   :trim:
</pre>
<p>results in:</p>
<blockquote>
Copyright © 2003, BogusMegaCorp™—all rights reserved.</blockquote>
<p>The following options are recognized:</p>
<dl class="docutils">
<dt><tt class="docutils literal">ltrim</tt> <span class="classifier-delimiter">:</span> <span class="classifier">flag</span></dt>
<dd>Whitespace to the left of the substitution reference is removed.</dd>
<dt><tt class="docutils literal">rtrim</tt> <span class="classifier-delimiter">:</span> <span class="classifier">flag</span></dt>
<dd>Whitespace to the right of the substitution reference is removed.</dd>
<dt><tt class="docutils literal">trim</tt> <span class="classifier-delimiter">:</span> <span class="classifier">flag</span></dt>
<dd>Equivalent to <tt class="docutils literal">ltrim</tt> plus <tt class="docutils literal">rtrim</tt>; whitespace on both sides
of the substitution reference is removed.</dd>
</dl>
</div>
<div class="section" id="date">
<h2><a class="toc-backref" href="#id62">Date</a></h2>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;date&quot;</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Doctree Element:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">Text</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Arguments:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">One, optional (date format).</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Options:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">None.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Content:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">None.</td>
</tr>
</tbody>
</table>
<p>The &quot;date&quot; directive generates the current local date and inserts it
into the document as text.  This directive may be used in substitution
definitions only.</p>
<p>The optional directive content is interpreted as the desired date
format, using the same codes as Python's time.strftime function.  The
default format is &quot;%Y-%m-%d&quot; (ISO 8601 date), but time fields can also
be used.  Examples:</p>
<pre class="literal-block">
.. |date| date::
.. |time| date:: %H:%M

Today's date is |date|.

This document was generated on |date| at |time|.
</pre>
</div>
</div>
<div class="section" id="miscellaneous">
<h1><a class="toc-backref" href="#id63">Miscellaneous</a></h1>
<div class="section" id="including-an-external-document-fragment">
<span id="include"></span><h2><a class="toc-backref" href="#id64">Including an External Document Fragment</a></h2>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;include&quot;</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Doctree Elements:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">Depend on data being included
(<a class="reference external" href="../doctree.html#literal-block">literal_block</a> with <tt class="docutils literal">code</tt> or <tt class="docutils literal">literal</tt> option).</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Arguments:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">One, required (path to the file to include).</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Options:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">Possible.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Content:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">None.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Configuration Setting:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body"><a class="reference external" href="../../user/config.html#file-insertion-enabled">file_insertion_enabled</a></td>
</tr>
</tbody>
</table>
<div class="warning">
<p class="first admonition-title">Warning</p>
<p class="last">The &quot;include&quot; directive represents a potential security hole.  It
can be disabled with the &quot;<a class="reference external" href="../../user/config.html#file-insertion-enabled">file_insertion_enabled</a>&quot; runtime setting.</p>
</div>
<p>The &quot;include&quot; directive reads a text file. The directive argument is
the path to the file to be included, relative to the document
containing the directive. Unless the options <tt class="docutils literal">literal</tt> or <tt class="docutils literal">code</tt>
are given, the file is parsed in the current document's context at the
point of the directive. For example:</p>
<pre class="literal-block">
This first example will be parsed at the document level, and can
thus contain any construct, including section headers.

.. include:: inclusion.txt

Back in the main document.

    This second example will be parsed in a block quote context.
    Therefore it may only contain body elements.  It may not
    contain section headers.

    .. include:: inclusion.txt
</pre>
<p>If an included document fragment contains section structure, the title
adornments must match those of the master document.</p>
<p>Standard data files intended for inclusion in reStructuredText
documents are distributed with the Docutils source code, located in
the &quot;docutils&quot; package in the <tt class="docutils literal">docutils/parsers/rst/include</tt>
directory.  To access these files, use the special syntax for standard
&quot;include&quot; data files, angle brackets around the file name:</p>
<pre class="literal-block">
.. include:: &lt;isonum.txt&gt;
</pre>
<p>The current set of standard &quot;include&quot; data files consists of sets of
substitution definitions.  See <a class="reference external" href="definitions.html">reStructuredText Standard Definition
Files</a> for details.</p>
<p>The following options are recognized:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">start-line</span></tt> <span class="classifier-delimiter">:</span> <span class="classifier">integer</span></dt>
<dd>Only the content starting from this line will be included.
(As usual in Python, the first line has index 0 and negative values
count from the end.)</dd>
<dt><tt class="docutils literal"><span class="pre">end-line</span></tt> <span class="classifier-delimiter">:</span> <span class="classifier">integer</span></dt>
<dd>Only the content up to (but excluding) this line will be included.</dd>
<dt><tt class="docutils literal"><span class="pre">start-after</span></tt> <span class="classifier-delimiter">:</span> <span class="classifier">text to find in the external data file</span></dt>
<dd>Only the content after the first occurrence of the specified text
will be included.</dd>
<dt><tt class="docutils literal"><span class="pre">end-before</span></tt> <span class="classifier-delimiter">:</span> <span class="classifier">text to find in the external data file</span></dt>
<dd>Only the content before the first occurrence of the specified text
(but after any <tt class="docutils literal">after</tt> text) will be included.</dd>
<dt><tt class="docutils literal">literal</tt> <span class="classifier-delimiter">:</span> <span class="classifier">flag (empty)</span></dt>
<dd>The entire included text is inserted into the document as a single
literal block.</dd>
<dt><tt class="docutils literal">code</tt> <span class="classifier-delimiter">:</span> <span class="classifier">formal language (optional)</span></dt>
<dd>The argument and the content of the included file are passed to
the <a class="reference internal" href="#code">code</a> directive (useful for program listings).
(New in Docutils 0.9)</dd>
<dt><tt class="docutils literal"><span class="pre">number-lines</span></tt> <span class="classifier-delimiter">:</span> <span class="classifier">[start line number]</span></dt>
<dd>Precede every code line with a line number.
The optional argument is the number of the first line (defaut 1).
Works only with <tt class="docutils literal">code</tt> or <tt class="docutils literal">literal</tt>.
(New in Docutils 0.9)</dd>
<dt><tt class="docutils literal">encoding</tt> <span class="classifier-delimiter">:</span> <span class="classifier">name of text encoding</span></dt>
<dd>The text encoding of the external data file.  Defaults to the
document's <a class="reference external" href="../../user/config.html#input-encoding">input_encoding</a>.</dd>
<dt><tt class="docutils literal"><span class="pre">tab-width</span></tt> <span class="classifier-delimiter">:</span> <span class="classifier">integer</span></dt>
<dd>Number of spaces for hard tab expansion.
A negative value prevents expansion of hard tabs. Defaults to the
<a class="reference external" href="../../user/config.html#tab-width">tab_width</a> configuration setting.</dd>
</dl>
<p>With <tt class="docutils literal">code</tt> or <tt class="docutils literal">literal</tt> the common options <a class="reference internal" href="#id15">:class:</a> and
<a class="reference internal" href="#name">:name:</a> are recognized as well.</p>
<p>Combining <tt class="docutils literal"><span class="pre">start/end-line</span></tt> and <tt class="docutils literal"><span class="pre">start-after/end-before</span></tt> is possible. The
text markers will be searched in the specified lines (further limiting the
included content).</p>
</div>
<div class="section" id="raw-data-pass-through">
<span id="raw-directive"></span><h2><a class="toc-backref" href="#id65">Raw Data Pass-Through</a></h2>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;raw&quot;</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Doctree Element:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body"><a class="reference external" href="../doctree.html#raw">raw</a></td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Arguments:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">One or more, required (output format types).</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Options:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">Possible.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Content:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">Stored verbatim, uninterpreted.  None (empty) if a
&quot;file&quot; or &quot;url&quot; option given.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Configuration Setting:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body"><a class="reference external" href="../../user/config.html#raw-enabled">raw_enabled</a></td>
</tr>
</tbody>
</table>
<div class="warning">
<p class="first admonition-title">Warning</p>
<p class="last">The &quot;raw&quot; directive represents a potential security hole.  It can
be disabled with the &quot;<a class="reference external" href="../../user/config.html#raw-enabled">raw_enabled</a>&quot; or &quot;<a class="reference external" href="../../user/config.html#file-insertion-enabled">file_insertion_enabled</a>&quot;
runtime settings.</p>
</div>
<div class="caution">
<p class="first admonition-title">Caution!</p>
<p>The &quot;raw&quot; directive is a stop-gap measure allowing the author to
bypass reStructuredText's markup.  It is a &quot;power-user&quot; feature
that should not be overused or abused.  The use of &quot;raw&quot; ties
documents to specific output formats and makes them less portable.</p>
<p class="last">If you often need to use the &quot;raw&quot; directive or a &quot;raw&quot;-derived
interpreted text role, that is a sign either of overuse/abuse or
that functionality may be missing from reStructuredText.  Please
describe your situation in a message to the <a class="reference external" href="../../user/mailing-lists.html#docutils-users">Docutils-users</a> mailing
list.</p>
</div>
<p>The &quot;raw&quot; directive indicates non-reStructuredText data that is to be
passed untouched to the Writer.  The names of the output formats are
given in the directive arguments.  The interpretation of the raw data
is up to the Writer.  A Writer may ignore any raw output not matching
its format.</p>
<p>For example, the following input would be passed untouched by an HTML
Writer:</p>
<pre class="literal-block">
.. raw:: html

   &lt;hr width=50 size=10&gt;
</pre>
<p>A LaTeX Writer could insert the following raw content into its
output stream:</p>
<pre class="literal-block">
.. raw:: latex

   \setlength{\parindent}{0pt}
</pre>
<p>Raw data can also be read from an external file, specified in a
directive option.  In this case, the content block must be empty.  For
example:</p>
<pre class="literal-block">
.. raw:: html
   :file: inclusion.html
</pre>
<p>Inline equivalents of the &quot;raw&quot; directive can be defined via
<a class="reference internal" href="#custom-interpreted-text-roles">custom interpreted text roles</a> derived from the <a class="reference external" href="roles.html#raw">&quot;raw&quot; role</a>.</p>
<p>The following options are recognized:</p>
<dl class="docutils">
<dt><tt class="docutils literal">file</tt> <span class="classifier-delimiter">:</span> <span class="classifier">string (newlines removed)</span></dt>
<dd>The local filesystem path of a raw data file to be included.</dd>
<dt><tt class="docutils literal">url</tt> <span class="classifier-delimiter">:</span> <span class="classifier">string (whitespace removed)</span></dt>
<dd>An Internet URL reference to a raw data file to be included.</dd>
<dt><tt class="docutils literal">encoding</tt> <span class="classifier-delimiter">:</span> <span class="classifier">name of text encoding</span></dt>
<dd>The text encoding of the external raw data (file or URL).
Defaults to the document's encoding (if specified).</dd>
</dl>
</div>
<div class="section" id="class">
<span id="classes"></span><h2><a class="toc-backref" href="#id66">Class</a></h2>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;class&quot;</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Doctree Element:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body"><a class="reference external" href="../doctree.html#pending">pending</a></td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Arguments:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">One or more, required (class names / attribute
values).</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Options:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">None.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Content:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">Optional.  If present, it is interpreted as body
elements.</td>
</tr>
</tbody>
</table>
<p>The &quot;class&quot; directive sets the <a class="reference external" href="../doctree.html#classes">&quot;classes&quot;</a> attribute value on its content
or on the first immediately following non-comment element <a class="footnote-reference" href="#id14" id="id12">[4]</a>.  For
details of the &quot;classes&quot; attribute, see <a class="reference external" href="../doctree.html#classes">its entry</a> in <a class="reference external" href="../doctree.html">The Docutils
Document Tree</a>.</p>
<p>The directive argument consists of one or more space-separated class
names. The names are transformed to conform to the regular expression
<tt class="docutils literal"><span class="pre">[a-z](-?[a-z0-9]+)*</span></tt> by converting</p>
<ul class="simple">
<li>alphabetic characters to lowercase,</li>
<li>accented characters to the base character,</li>
<li>non-alphanumeric characters to hyphens,</li>
<li>consecutive hyphens into one hyphen.</li>
</ul>
<p>For example &quot;Rot-Gelb.Blau Grün:+2008&quot; becomes &quot;rot-gelb-blau grun-2008&quot;.
(For the <a class="reference internal" href="#rationale">rationale</a>, see below.)</p>
<p>Examples:</p>
<pre class="literal-block">
.. class:: special

This is a &quot;special&quot; paragraph.

.. class:: exceptional remarkable

An Exceptional Section
======================

This is an ordinary paragraph.

.. class:: multiple

   First paragraph.

   Second paragraph.
</pre>
<p>The text above is parsed and transformed into this doctree fragment:</p>
<pre class="literal-block">
&lt;paragraph classes=&quot;special&quot;&gt;
    This is a &quot;special&quot; paragraph.
&lt;section classes=&quot;exceptional remarkable&quot;&gt;
    &lt;title&gt;
        An Exceptional Section
    &lt;paragraph&gt;
        This is an ordinary paragraph.
    &lt;paragraph classes=&quot;multiple&quot;&gt;
        First paragraph.
    &lt;paragraph classes=&quot;multiple&quot;&gt;
        Second paragraph.
</pre>
<table class="docutils footnote" frame="void" id="id14" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id12">[4]</a></td><td><p class="first">To set a &quot;classes&quot; attribute value on a block quote, the
&quot;class&quot; directive must be followed by an empty comment:</p>
<pre class="literal-block">
.. class:: highlights
..

    Block quote text.
</pre>
<p class="last">Without the empty comment, the indented text would be interpreted as the
&quot;class&quot; directive's content, and the classes would be applied to each
element (paragraph, in this case) individually, instead of to the block
quote as a whole.</p>
</td></tr>
</tbody>
</table>
<div class="topic" id="rationale">
<p class="topic-title first">Rationale for &quot;classes&quot; Attribute Value Conversion</p>
<p>Docutils identifiers are converted to conform to the regular
expression <tt class="docutils literal"><span class="pre">[a-z](-?[a-z0-9]+)*</span></tt>.  For HTML + CSS compatibility,
identifiers (the &quot;classes&quot; and &quot;id&quot; attributes) should have no
underscores, colons, or periods.  Hyphens may be used.</p>
<ul>
<li><p class="first">The <a class="reference external" href="http://www.w3.org/TR/html401/">HTML 4.01 spec</a> defines identifiers based on SGML tokens:</p>
<blockquote>
<p>ID and NAME tokens must begin with a letter ([A-Za-z]) and
may be followed by any number of letters, digits ([0-9]),
hyphens (&quot;-&quot;), underscores (&quot;_&quot;), colons (&quot;:&quot;), and periods
(&quot;.&quot;).</p>
</blockquote>
</li>
<li><p class="first">The <a class="reference external" href="http://www.w3.org/TR/REC-CSS1">CSS1 spec</a> defines identifiers based on the &quot;name&quot; token
(&quot;flex&quot; tokenizer notation below; &quot;latin1&quot; and &quot;escape&quot; 8-bit
characters have been replaced with XML entities):</p>
<pre class="literal-block">
unicode     \\[0-9a-f]{1,4}
latin1      [&amp;iexcl;-&amp;yuml;]
escape      {unicode}|\\[ -~&amp;iexcl;-&amp;yuml;]
nmchar      [-A-Za-z0-9]|{latin1}|{escape}
name        {nmchar}+
</pre>
</li>
</ul>
<p>The CSS rule does not include underscores (&quot;_&quot;), colons (&quot;:&quot;), or
periods (&quot;.&quot;), therefore &quot;classes&quot; and &quot;id&quot; attributes should not
contain these characters.  Combined with HTML's requirements (the
first character must be a letter; no &quot;unicode&quot;, &quot;latin1&quot;, or
&quot;escape&quot; characters), this results in the regular expression
<tt class="docutils literal"><span class="pre">[A-Za-z][-A-Za-z0-9]*</span></tt>. Docutils adds a normalisation by
downcasing and merge of consecutive hyphens.</p>
</div>
</div>
<div class="section" id="custom-interpreted-text-roles">
<span id="role"></span><h2><a class="toc-backref" href="#id67">Custom Interpreted Text Roles</a></h2>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;role&quot;</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Doctree Element:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">None; affects subsequent parsing.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Arguments:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">Two; one required (new role name), one optional
(base role name, in parentheses).</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Options:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">Possible (depends on base role).</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Content:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">depends on base role.</td>
</tr>
</tbody>
</table>
<p>(New in Docutils 0.3.2)</p>
<p>The &quot;role&quot; directive dynamically creates a custom interpreted text
role and registers it with the parser.  This means that after
declaring a role like this:</p>
<pre class="literal-block">
.. role:: custom
</pre>
<p>the document may use the new &quot;custom&quot; role:</p>
<pre class="literal-block">
An example of using :custom:`interpreted text`
</pre>
<p>This will be parsed into the following document tree fragment:</p>
<pre class="literal-block">
&lt;paragraph&gt;
    An example of using
    &lt;inline classes=&quot;custom&quot;&gt;
        interpreted text
</pre>
<p>The role must be declared in a document before it can be used.</p>
<p>The new role may be based on an existing role, specified as a second
argument in parentheses (whitespace optional):</p>
<pre class="literal-block">
.. role:: custom(emphasis)

:custom:`text`
</pre>
<p>The parsed result is as follows:</p>
<pre class="literal-block">
&lt;paragraph&gt;
    &lt;emphasis classes=&quot;custom&quot;&gt;
        text
</pre>
<p>A special case is the <a class="reference external" href="roles.html#raw">&quot;raw&quot; role</a>: derived roles enable
inline <a class="reference internal" href="#raw-data-pass-through">raw data pass-through</a>, e.g.:</p>
<pre class="literal-block">
.. role:: raw-role(raw)
   :format: html latex

:raw-role:`raw text`
</pre>
<p>If no base role is explicitly specified, a generic custom role is
automatically used.  Subsequent interpreted text will produce an
&quot;inline&quot; element with a <a class="reference external" href="../doctree.html#classes">&quot;classes&quot;</a> attribute, as in the first example
above.</p>
<p>With most roles, the &quot;:class:&quot; option can be used to set a &quot;classes&quot;
attribute that is different from the role name.  For example:</p>
<pre class="literal-block">
.. role:: custom
   :class: special

:custom:`interpreted text`
</pre>
<p>This is the parsed result:</p>
<pre class="literal-block">
&lt;paragraph&gt;
    &lt;inline classes=&quot;special&quot;&gt;
        interpreted text
</pre>
<p id="role-class">The following option is recognized by the &quot;role&quot; directive for most
base roles:</p>
<dl class="docutils">
<dt><tt class="docutils literal">class</tt> <span class="classifier-delimiter">:</span> <span class="classifier">text</span></dt>
<dd>Set the <a class="reference external" href="../doctree.html#classes">&quot;classes&quot;</a> attribute value on the element produced
(<tt class="docutils literal">inline</tt>, or element associated with a base class) when the
custom interpreted text role is used.  If no directive options are
specified, a &quot;class&quot; option with the directive argument (role
name) as the value is implied.  See the <a class="reference internal" href="#class">class</a> directive above.</dd>
</dl>
<p>Specific base roles may support other options and/or directive
content.  See the <a class="reference external" href="roles.html">reStructuredText Interpreted Text Roles</a> document
for details.</p>
</div>
<div class="section" id="setting-the-default-interpreted-text-role">
<span id="default-role"></span><h2><a class="toc-backref" href="#id68">Setting the Default Interpreted Text Role</a></h2>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;default-role&quot;</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Doctree Element:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">None; affects subsequent parsing.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Arguments:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">One, optional (new default role name).</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Options:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">None.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Content:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">None.</td>
</tr>
</tbody>
</table>
<p>(New in Docutils 0.3.10)</p>
<p>The &quot;default-role&quot; directive sets the default interpreted text role,
the role that is used for interpreted text without an explicit role.
For example, after setting the default role like this:</p>
<pre class="literal-block">
.. default-role:: subscript
</pre>
<p>any subsequent use of implicit-role interpreted text in the document
will use the &quot;subscript&quot; role:</p>
<pre class="literal-block">
An example of a `default` role.
</pre>
<p>This will be parsed into the following document tree fragment:</p>
<pre class="literal-block">
&lt;paragraph&gt;
    An example of a
    &lt;subscript&gt;
        default
     role.
</pre>
<p>Custom roles may be used (see the &quot;<a class="reference internal" href="#role">role</a>&quot; directive above), but it
must have been declared in a document before it can be set as the
default role.  See the <a class="reference external" href="roles.html">reStructuredText Interpreted Text Roles</a>
document for details of built-in roles.</p>
<p>The directive may be used without an argument to restore the initial
default interpreted text role, which is application-dependent.  The
initial default interpreted text role of the standard reStructuredText
parser is &quot;title-reference&quot;.</p>
</div>
<div class="section" id="metadata-document-title">
<h2><a class="toc-backref" href="#id69">Metadata Document Title</a></h2>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;title&quot;</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Doctree Element:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">None.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Arguments:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">1, required (the title text).</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Options:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">None.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Content:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">None.</td>
</tr>
</tbody>
</table>
<p>The &quot;title&quot; directive specifies the document title as metadata, which
does not become part of the document body.  It overrides a
document-supplied title.  For example, in HTML output the metadata
document title appears in the title bar of the browser window.</p>
</div>
<div class="section" id="restructuredtext-test-directive">
<h2><a class="toc-backref" href="#id70">Restructuredtext-Test-Directive</a></h2>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;restructuredtext-test-directive&quot;</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Doctree Element:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">system_warning</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Arguments:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">None.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Options:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">None.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Content:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">Interpreted as a literal block.</td>
</tr>
</tbody>
</table>
<p>This directive is provided for test purposes only.  (Nobody is
expected to type in a name <em>that</em> long!)  It is converted into a
level-1 (info) system message showing the directive data, possibly
followed by a literal block containing the rest of the directive
block.</p>
</div>
</div>
<div class="section" id="common-options">
<h1><a class="toc-backref" href="#id71">Common Options</a></h1>
<p>Most of the directives that generate doctree elements support the following
options:</p>
<dl class="docutils">
<dt><span class="target" id="id15">:class:</span> <span class="classifier-delimiter">:</span> <span class="classifier">text</span></dt>
<dd>Set a <a class="reference external" href="../doctree.html#classes">&quot;classes&quot;</a> attribute value on the doctree element generated by
the directive. See also the <a class="reference internal" href="#class">class</a> directive.</dd>
<dt><span class="target" id="name">:name:</span> <span class="classifier-delimiter">:</span> <span class="classifier">text</span></dt>
<dd><p class="first">Add <span class="incremental">text</span> to the <a class="reference external" href="../doctree.html#names">&quot;names&quot;</a> attribute of the doctree element generated
by the directive. This allows <a class="reference external" href="restructuredtext.html#hyperlink-references">hyperlink references</a> to the element
using <span class="incremental">text</span> as <a class="reference external" href="restructuredtext.html#reference-names">reference name</a>.</p>
<p>Specifying the <span class="incremental">name</span> option of a directive, e.g.,</p>
<pre class="literal-block">
.. image:: bild.png
   :name: my picture
</pre>
<p>is a concise syntax alternative to preceding it with a <a class="reference external" href="restructuredtext.html#hyperlink-targets">hyperlink
target</a></p>
<pre class="literal-block">
.. _my picture:

.. image:: bild.png
</pre>
<p class="last">New in Docutils 0.8.</p>
</dd>
</dl>
<!-- Local Variables:
mode: indented-text
indent-tabs-mode: nil
sentence-end-double-space: t
fill-column: 70
End: -->
</div>
</div>
</body>
</html>