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/user
/usr/share/doc/docutils-doc/docs/user/
Upload File:
Current File : /usr/share/doc/docutils-doc/docs/user/latex.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>Generating LaTeX with Docutils</title>
<meta name="author" content="Engelbert Gruber, Guenter Milde" />
<meta name="date" content="2013-06-03" />
<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="generating-latex-with-docutils">
<h1 class="title">Generating LaTeX with Docutils</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>Engelbert Gruber, Guenter Milde</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>7667</td></tr>
<tr><th class="docinfo-name">Date:</th>
<td>2013-06-03</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="auto-toc simple">
<li><a class="reference internal" href="#introduction" id="id36">1&nbsp;&nbsp;&nbsp;Introduction</a></li>
<li><a class="reference internal" href="#latex" id="id37">2&nbsp;&nbsp;&nbsp;LaTeX</a><ul class="auto-toc">
<li><a class="reference internal" href="#latex-packages" id="id38">2.1&nbsp;&nbsp;&nbsp;LaTeX packages</a></li>
<li><a class="reference internal" href="#docutils-special-latex-macros" id="id39">2.2&nbsp;&nbsp;&nbsp;Docutils special LaTeX macros</a></li>
<li><a class="reference internal" href="#length-units" id="id40">2.3&nbsp;&nbsp;&nbsp;Length units</a></li>
</ul>
</li>
<li><a class="reference internal" href="#pdf-generation" id="id41">3&nbsp;&nbsp;&nbsp;PDF generation</a></li>
<li><a class="reference internal" href="#configuration" id="id42">4&nbsp;&nbsp;&nbsp;Configuration</a><ul class="auto-toc">
<li><a class="reference internal" href="#options" id="id43">4.1&nbsp;&nbsp;&nbsp;Options</a></li>
<li><a class="reference internal" href="#latex-code" id="id44">4.2&nbsp;&nbsp;&nbsp;LaTeX code</a><ul class="auto-toc">
<li><a class="reference internal" href="#style-sheets" id="id45">4.2.1&nbsp;&nbsp;&nbsp;Style sheets</a></li>
<li><a class="reference internal" href="#latex-preamble" id="id46">4.2.2&nbsp;&nbsp;&nbsp;LaTeX preamble</a></li>
<li><a class="reference internal" href="#templates" id="id47">4.2.3&nbsp;&nbsp;&nbsp;Templates</a></li>
<li><a class="reference internal" href="#raw-latex" id="id48">4.2.4&nbsp;&nbsp;&nbsp;Raw LaTeX</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#how-to-configure-the" id="id49">5&nbsp;&nbsp;&nbsp;How to configure the ...</a><ul class="auto-toc">
<li><a class="reference internal" href="#admonitions" id="id50">5.1&nbsp;&nbsp;&nbsp;admonitions</a></li>
<li><a class="reference internal" href="#custom-interpreted-text-roles" id="id51">5.2&nbsp;&nbsp;&nbsp;custom interpreted text roles</a></li>
<li><a class="reference internal" href="#definition-lists" id="id52">5.3&nbsp;&nbsp;&nbsp;definition lists</a></li>
<li><a class="reference internal" href="#document-class" id="id53">5.4&nbsp;&nbsp;&nbsp;document class</a></li>
<li><a class="reference internal" href="#document-info" id="id54">5.5&nbsp;&nbsp;&nbsp;document info</a></li>
<li><a class="reference internal" href="#document-title" id="id55">5.6&nbsp;&nbsp;&nbsp;document title</a></li>
<li><a class="reference internal" href="#field-lists" id="id56">5.7&nbsp;&nbsp;&nbsp;field lists</a></li>
<li><a class="reference internal" href="#figure-and-table-captions" id="id57">5.8&nbsp;&nbsp;&nbsp;figure and table captions</a></li>
<li><a class="reference internal" href="#figure-placement" id="id58">5.9&nbsp;&nbsp;&nbsp;figure placement</a></li>
<li><a class="reference internal" href="#font" id="id59">5.10&nbsp;&nbsp;&nbsp;font</a><ul class="auto-toc">
<li><a class="reference internal" href="#choice-of-suitable-fonts" id="id60">5.10.1&nbsp;&nbsp;&nbsp;choice of suitable fonts</a></li>
</ul>
</li>
<li><a class="reference internal" href="#font-encoding" id="id61">5.11&nbsp;&nbsp;&nbsp;font encoding</a></li>
<li><a class="reference internal" href="#font-size" id="id62">5.12&nbsp;&nbsp;&nbsp;font size</a></li>
<li><a class="reference internal" href="#footnotes" id="id63">5.13&nbsp;&nbsp;&nbsp;footnotes</a></li>
<li><a class="reference internal" href="#hyphenation" id="id64">5.14&nbsp;&nbsp;&nbsp;hyphenation</a></li>
<li><a class="reference internal" href="#hyperlinks" id="id65">5.15&nbsp;&nbsp;&nbsp;hyperlinks</a><ul class="auto-toc">
<li><a class="reference internal" href="#disable-hyperlinks" id="id66">5.15.1&nbsp;&nbsp;&nbsp;disable hyperlinks</a></li>
</ul>
</li>
<li><a class="reference internal" href="#line-blocks" id="id67">5.16&nbsp;&nbsp;&nbsp;line blocks</a></li>
<li><a class="reference internal" href="#line-spacing" id="id68">5.17&nbsp;&nbsp;&nbsp;line spacing</a></li>
<li><a class="reference internal" href="#literal-blocks" id="id69">5.18&nbsp;&nbsp;&nbsp;literal blocks</a></li>
<li><a class="reference internal" href="#list-of-figures-tables" id="id70">5.19&nbsp;&nbsp;&nbsp;list of figures/tables</a></li>
<li><a class="reference internal" href="#option-list" id="id71">5.20&nbsp;&nbsp;&nbsp;option list</a></li>
<li><a class="reference internal" href="#page-breaks" id="id72">5.21&nbsp;&nbsp;&nbsp;page breaks</a></li>
<li><a class="reference internal" href="#page-layout" id="id73">5.22&nbsp;&nbsp;&nbsp;page layout</a></li>
<li><a class="reference internal" href="#page-headers-and-footers" id="id74">5.23&nbsp;&nbsp;&nbsp;page headers and footers</a></li>
<li><a class="reference internal" href="#page-numbering" id="id75">5.24&nbsp;&nbsp;&nbsp;page numbering</a></li>
<li><a class="reference internal" href="#paper-size" id="id76">5.25&nbsp;&nbsp;&nbsp;paper size</a></li>
<li><a class="reference internal" href="#paragraph-indent" id="id77">5.26&nbsp;&nbsp;&nbsp;paragraph indent</a></li>
<li><a class="reference internal" href="#rubric" id="id78">5.27&nbsp;&nbsp;&nbsp;rubric</a></li>
<li><a class="reference internal" href="#section-numbering" id="id79">5.28&nbsp;&nbsp;&nbsp;section numbering</a></li>
<li><a class="reference internal" href="#sidebar" id="id80">5.29&nbsp;&nbsp;&nbsp;sidebar</a></li>
<li><a class="reference internal" href="#size-of-a-pixel" id="id81">5.30&nbsp;&nbsp;&nbsp;size of a pixel</a></li>
<li><a class="reference internal" href="#topic-element" id="id82">5.31&nbsp;&nbsp;&nbsp;topic element</a></li>
<li><a class="reference internal" href="#topic-title" id="id83">5.32&nbsp;&nbsp;&nbsp;topic title</a></li>
<li><a class="reference internal" href="#table-of-contents" id="id84">5.33&nbsp;&nbsp;&nbsp;table of contents</a></li>
<li><a class="reference internal" href="#title-reference-role" id="id85">5.34&nbsp;&nbsp;&nbsp;title reference role</a></li>
<li><a class="reference internal" href="#text-encoding" id="id86">5.35&nbsp;&nbsp;&nbsp;text encoding</a></li>
<li><a class="reference internal" href="#transition-element" id="id87">5.36&nbsp;&nbsp;&nbsp;transition element</a></li>
</ul>
</li>
<li><a class="reference internal" href="#changes" id="id88">6&nbsp;&nbsp;&nbsp;Changes</a></li>
<li><a class="reference internal" href="#problems" id="id89">7&nbsp;&nbsp;&nbsp;Problems</a><ul class="auto-toc">
<li><a class="reference internal" href="#troubleshooting" id="id90">7.1&nbsp;&nbsp;&nbsp;Troubleshooting</a><ul class="auto-toc">
<li><a class="reference internal" href="#bad-looking-pdf-output" id="id91">7.1.1&nbsp;&nbsp;&nbsp;Bad looking PDF output</a></li>
<li><a class="reference internal" href="#footnote-mark-and-text-at-different-pages" id="id92">7.1.2&nbsp;&nbsp;&nbsp;footnote mark and text at different pages</a></li>
<li><a class="reference internal" href="#non-breaking-hyperlinks" id="id93">7.1.3&nbsp;&nbsp;&nbsp;non-breaking hyperlinks</a></li>
<li><a class="reference internal" href="#glyph-not-defined-in-pd1-encoding" id="id94">7.1.4&nbsp;&nbsp;&nbsp;Glyph not defined in PD1 encoding</a></li>
<li><a class="reference internal" href="#image-inclusion" id="id95">7.1.5&nbsp;&nbsp;&nbsp;image inclusion</a></li>
<li><a class="reference internal" href="#why-are-my-images-too-big" id="id96">7.1.6&nbsp;&nbsp;&nbsp;Why are my images too big?</a></li>
<li><a class="reference internal" href="#error-illegal-unit-px" id="id97">7.1.7&nbsp;&nbsp;&nbsp;Error <tt class="docutils literal">illegal unit px</tt></a></li>
<li><a class="reference internal" href="#error-symbol-textcurrency-not-provided" id="id98">7.1.8&nbsp;&nbsp;&nbsp;Error <tt class="docutils literal">Symbol \textcurrency not provided</tt> ...</a></li>
<li><a class="reference internal" href="#search-and-text-extraction" id="id99">7.1.9&nbsp;&nbsp;&nbsp;Search and text extraction</a></li>
<li><a class="reference internal" href="#unicode-box-drawing-and-block-characters" id="id100">7.1.10&nbsp;&nbsp;&nbsp;Unicode box drawing and block characters</a></li>
</ul>
</li>
<li><a class="reference internal" href="#bugs-and-open-issues" id="id101">7.2&nbsp;&nbsp;&nbsp;Bugs and open issues</a><ul class="auto-toc">
<li><a class="reference internal" href="#footnotes-and-citations" id="id102">7.2.1&nbsp;&nbsp;&nbsp;Footnotes and citations</a></li>
<li><a class="reference internal" href="#tables" id="id103">7.2.2&nbsp;&nbsp;&nbsp;Tables</a></li>
<li><a class="reference internal" href="#id35" id="id104">7.2.3&nbsp;&nbsp;&nbsp;Figures</a></li>
<li><a class="reference internal" href="#miscellaneous" id="id105">7.2.4&nbsp;&nbsp;&nbsp;Miscellaneous</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
<div class="section" id="introduction">
<h1><a class="toc-backref" href="#id36">1&nbsp;&nbsp;&nbsp;Introduction</a></h1>
<p>This document covers topics specific to Docutils' <a class="reference external" href="http://www.latex-project.org/">LaTeX</a> export.  For
an introduction to LaTeX see, e.g., <a class="reference external" href="http://www.latex-project.org/guides/usrguide.pdf">LaTeX2e for authors</a>. There exists
a wide selecton of <a class="reference external" href="http://www.latex-project.org/guides/">LaTeX Documentation on the net</a> and
<a class="reference external" href="http://www.latex-project.org/guides/books.html">books on LaTeX and related topics</a>.</p>
<p>There are two approaches to typeset documents from reStructuredText
sources via LaTeX:</p>
<ol class="arabic">
<li><p class="first">treat LaTeX as a document format (like HTML):</p>
<p>Transform the internal markup into corresponding LaTeX markup.
For example, a section title would be written with the LaTeX section
command: <tt class="docutils literal">\section{this section title}</tt>.</p>
<p>This keeps the document structure and semantic markup produing a readable
LaTeX file, but may require hacking around Docutils — LaTeX
incompatibilities.</p>
<p>As with HTML, styling is mostly done via style sheets or
<a class="reference internal" href="#latex-packages">LaTeX packages</a>.</p>
<p>If you prefer this approach, try the <span class="incremental">latex2e</span> or the <span class="incremental">xetex</span>
writer.</p>
</li>
<li><p class="first">treat LaTeX as a page description format (like Postscript):</p>
<p>Use LaTeX as a typesetting system to produce the desired output
without representing document structure in the LaTeX source. This
will work around Docutils-incompatible features in LaTeX but
produces a hard to read LaTeX file. Styling is done via options to
the latex writer.</p>
<p>The (orphaned) <span class="incremental">newlatex</span> writer (<tt class="docutils literal">rst2newlatex.py</tt>) uses LaTeX as
a typesetter without caring about producing readable/stylable LaTeX
files.</p>
</li>
</ol>
<p>This documents describes the first approach used by the <span class="incremental">latex2e</span>
and <span class="incremental">xetex</span> writers.</p>
</div>
<div class="section" id="latex">
<h1><a class="toc-backref" href="#id37">2&nbsp;&nbsp;&nbsp;LaTeX</a></h1>
<p>Unlike HTML/CSS, LaTeX provides one common language for markup and
style definitions. Separation of content and style is realized by
collecting style definitions in the <a class="reference external" href="config.html#documentclass">documentclass</a>, <a class="reference internal" href="#latex-packages">LaTeX packages</a>,
or the document preamble.</p>
<div class="section" id="latex-packages">
<h2><a class="toc-backref" href="#id38">2.1&nbsp;&nbsp;&nbsp;LaTeX packages</a></h2>
<p>LaTeX packages (similar to Python modules or C libraries) provide
means to extend or modify the LaTeX language by redefining macros or
providing new ones. There is a <em>huge</em> selection of packages (standard
as well as user contributed) coming with your TeX distribution or
available at <a class="reference external" href="http://www.ctan.org">CTAN</a> (see the <a class="reference external" href="http://texcatalogue.sarovar.org/">TeX Catalogue</a>).</p>
</div>
<div class="section" id="docutils-special-latex-macros">
<h2><a class="toc-backref" href="#id39">2.2&nbsp;&nbsp;&nbsp;Docutils special LaTeX macros</a></h2>
<p>Some Docutils objects have no LaTeX counterpart, they will be typeset
using a Docutils specific LaTeX <em>macro</em> (command, environment, or
length) to allow customization. By convention, special macros use the
prefix <tt class="docutils literal">\DU</tt><a class="footnote-reference" href="#id3" id="id2">[1]</a>.</p>
<p>The generated LaTeX documents should be kept processable by a standard LaTeX
installation. Therefore fallback definitions are included after the <a class="reference internal" href="#custom-style-sheets">custom
style sheets</a>, if a macro is required in the document.</p>
<ul class="simple">
<li>Custom <a class="reference internal" href="#style-sheets">style sheets</a> can define alternative implementations with
<tt class="docutils literal">\newcommand</tt>, <tt class="docutils literal">\newenvironment</tt>, and <tt class="docutils literal">\newlength</tt> followed by
<tt class="docutils literal">\setlength</tt>.</li>
<li>Definitions with <a class="reference internal" href="#raw-latex">raw LaTeX</a> are part of the document body. Use
<tt class="docutils literal">\def</tt>, <tt class="docutils literal">\renewcommand</tt> or <tt class="docutils literal">\renewenvironment</tt>, and <tt class="docutils literal">\setlength</tt>.</li>
</ul>
<p>See the test output <a class="reference external" href="../../test/functional/expected/standalone_rst_latex.tex">standalone_rst_latex.tex</a> for an example of the fallback
definitions and their use in the document.</p>
<table class="docutils footnote" frame="void" id="id3" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id2">[1]</a></td><td>DU for Documentation Utilities = Docutils</td></tr>
</tbody>
</table>
</div>
<div class="section" id="length-units">
<h2><a class="toc-backref" href="#id40">2.3&nbsp;&nbsp;&nbsp;Length units</a></h2>
<p>LaTeX supports all <a class="reference external" href="../ref/rst/restructuredtext.html#length-units">length units</a> defined for Docutils plus the
following less common units:</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">pt:</th><td class="field-body">typewriter's (or LaTeX) point (1 pt = 1/72.27 in)</td>
</tr>
<tr class="field"><th class="field-name">dd:</th><td class="field-body">didôt (1 dd = 1238/1157 pt)</td>
</tr>
<tr class="field"><th class="field-name">cc:</th><td class="field-body">cîcero (1 cc = 12 dd)</td>
</tr>
<tr class="field"><th class="field-name">sp:</th><td class="field-body">scaled point (1sp = 1/65536pt)</td>
</tr>
</tbody>
</table>
<div class="attention">
<p class="first admonition-title">Attention!</p>
<p>Different definitions of the unit &quot;pt&quot;!</p>
<ul>
<li><p class="first">In Docutils (as well as CSS) the unit symbol &quot;pt&quot; denotes the
<span class="incremental">Postscript point</span> or <span class="incremental">DTP point</span>.</p>
</li>
<li><p class="first">LaTeX uses &quot;pt&quot; for the <span class="incremental">LaTeX point</span>, which is unknown to Docutils and
0.3&nbsp;% smaller.</p>
</li>
<li><p class="first">The <span class="incremental">DTP point</span> is available in LaTeX as &quot;bp&quot; (big point):</p>
<blockquote>
<p>1 pt = 1/72.25 in &lt; 1 bp  = 1/72 in</p>
</blockquote>
</li>
</ul>
<p>Lengths specified in the document with unit &quot;pt&quot; will be given the
unit &quot;bp&quot; in the LaTeX source.</p>
<p class="last">In <a class="reference internal" href="#raw-latex">raw LaTeX</a> and <a class="reference internal" href="#custom-style-sheets">custom style sheets</a>, the <span class="incremental">DTP point</span> must be
specified as &quot;bp&quot;, while &quot;pt&quot; is interpreted as <span class="incremental">LaTeX point</span>.</p>
</div>
<p>The default length unit (added by Docutils to length specifications
without unit) is the &quot;DTP point&quot;.</p>
<p>For more on lengths in LaTeX, see e.g. <a class="reference external" href="http://www.giss.nasa.gov/tools/latex/ltx-86.html.">Hypertext Help with LaTeX: Lengths</a></p>
</div>
</div>
<div class="section" id="pdf-generation">
<h1><a class="toc-backref" href="#id41">3&nbsp;&nbsp;&nbsp;PDF generation</a></h1>
<p>In most cases, LaTeX code is not the desired end-format of the document.
LaTeX offers many ways to generate PDF documents from the LaTeX
source, including:</p>
<dl class="docutils">
<dt><span class="target" id="pdflatex">pdflatex</span></dt>
<dd>Generates a PDF document directly from the LaTeX file.</dd>
<dt><span class="target" id="latex-dvipdfmx">latex + dvipdfmx</span></dt>
<dd>Use <tt class="docutils literal">latex</tt> to generate a DVI file and <tt class="docutils literal">dvipdfmx</tt> to produce a PDF
file. If you take this approach, add <tt class="docutils literal">dvipdfmx</tt> to the
_documentoptions.</dd>
<dt><span class="target" id="id6">latex</span> + dvips + ps2pdf</dt>
<dd>Produce a DVI file with <tt class="docutils literal">latex</tt>, postscript with <tt class="docutils literal">dvips</tt> and PDF with
<tt class="docutils literal">ps2pdf</tt>.</dd>
<dt><span class="target" id="xelatex">xelatex</span></dt>
<dd>The <a class="reference external" href="http://tug.org/xetex/">XeTeX</a> engine works with input files in UTF-8 encoding and system
fonts. Export your document with the <span class="incremental">xetex</span> writer (<tt class="docutils literal">rst2xetex</tt>),
if you want to go this route.</dd>
</dl>
<p>You need to call latex (or pdflatex/xelatex) twice (or even three times) to
get internal references correct.</p>
<dl class="docutils">
<dt><span class="target" id="rubber">rubber</span></dt>
<dd>The <a class="reference external" href="http://iml.univ-mrs.fr/~beffara/soft/rubber/">Rubber</a> wrapper for LaTeX and friends can be used to automatically
run all programs the required number of times and delete &quot;spurious&quot; files.
This includes processing bibliographic references or indices, as well as
compilation or conversion of figures.</dd>
</dl>
</div>
<div class="section" id="configuration">
<h1><a class="toc-backref" href="#id42">4&nbsp;&nbsp;&nbsp;Configuration</a></h1>
<p>The LaTeX code generation can be configured via</p>
<ul class="simple">
<li>configuration <a class="reference internal" href="#options">options</a> to the Docutils writer,</li>
<li><a class="reference internal" href="#latex-packages">LaTeX packages</a>,</li>
<li>custom <a class="reference internal" href="#latex-code">LaTeX code</a> in
+ <a class="reference internal" href="#style-sheets">style sheets</a>,
+ the <a class="reference internal" href="#latex-preamble">LaTeX preamble</a>,
+ the document body (<a class="reference internal" href="#raw-latex">raw LaTeX</a>), or
+ custom <a class="reference internal" href="#templates">templates</a>.</li>
</ul>
<div class="section" id="options">
<span id="option"></span><h2><a class="toc-backref" href="#id43">4.1&nbsp;&nbsp;&nbsp;Options</a></h2>
<p>Options can be specified as</p>
<ul class="simple">
<li>command-line options (run <tt class="docutils literal">rst2latex.py <span class="pre">--help</span></tt> to get a list of
available options), or</li>
<li>configuration settings (see <a class="reference external" href="config.html">Docutils Configuration</a> for details).</li>
</ul>
</div>
<div class="section" id="latex-code">
<h2><a class="toc-backref" href="#id44">4.2&nbsp;&nbsp;&nbsp;LaTeX code</a></h2>
<dl class="docutils">
<dt>Custom LaTeX code can be placed in <a class="reference internal" href="#style-sheets">style sheets</a>, the <a href="#id9"><span class="problematic" id="id10">`</span></a>LaTeX</dt>
<dd><div class="first system-message" id="id9">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">docs/user/latex.txt</tt>, line 230); <em><a href="#id10">backlink</a></em></p>
Inline interpreted text or phrase reference start-string without end-string.</div>
<p class="last">preamble`_, the document body (<a class="reference internal" href="#raw-latex">raw LaTeX</a>), or custom <a class="reference internal" href="#templates">templates</a>.</p>
</dd>
</dl>
<div class="section" id="style-sheets">
<span id="custom-style-sheets"></span><span id="style-sheet"></span><h3><a class="toc-backref" href="#id45">4.2.1&nbsp;&nbsp;&nbsp;Style sheets</a></h3>
<p>A common way of LaTeX customization is the preparation of custom style
sheets, either as simple files with LaTeX code snippets or as home-made
<a class="reference internal" href="#latex-packages">LaTeX packages</a> (see the <a class="reference external" href="http://mirror.ctan.org/macros/latex/doc/clsguide.pdf">clsguide</a> for an introduction on LaTeX
package writing).</p>
<dl class="docutils">
<dt>Options:</dt>
<dd><p class="first"><a class="reference external" href="config.html#stylesheet-latex2e-writer">stylesheet</a></p>
<p class="last">It is possible to specify multiple style sheets and mix <a class="reference internal" href="#latex-packages">LaTeX
packages</a> with <a class="reference internal" href="#custom-style-sheets">custom style sheets</a>.</p>
</dd>
</dl>
<p>You cannot specify package options with the <a class="reference external" href="config.html#stylesheet-latex2e-writer">stylesheet</a> setting. If
you need to pass options to the package, use the <tt class="docutils literal">\usepackage</tt>
command in the <a class="reference internal" href="#latex-preamble">LaTeX preamble</a> or a custom style sheet.</p>
<dl class="docutils">
<dt>Example 1:</dt>
<dd><p class="first">Select Latin Modern fonts with the <span class="incremental">lmodern</span> package:</p>
<pre class="last literal-block">
--stylesheet=lmodern
</pre>
</dd>
<dt>Example 2:</dt>
<dd><p class="first">Use the <span class="incremental">preamble.tex</span> home-made custom style sheet together with
the package <span class="incremental">kerkis</span> (Bookman fonts):</p>
<pre class="last literal-block">
--stylesheet=kerkis,preamble.tex
</pre>
</dd>
<dt>Example 3:</dt>
<dd><p class="first">Select Palatino fonts with old-style numbers and true small-caps
with the LaTeX command</p>
<pre class="literal-block">
\usepackage[osf,sc]{mathpazo}
</pre>
<p class="last">in the <a class="reference internal" href="#latex-preamble">LaTeX preamble</a> or <a class="reference internal" href="#custom-style-sheets">custom style sheets</a>.</p>
</dd>
<dt>Stylesheet Repository</dt>
<dd>There is a <a class="reference external" href="../../../sandbox/stylesheets/">repository of user-contributed style sheets</a> in the
Docutils <a class="reference external" href="../../../sandbox/">Sandbox</a>.</dd>
</dl>
</div>
<div class="section" id="latex-preamble">
<h3><a class="toc-backref" href="#id46">4.2.2&nbsp;&nbsp;&nbsp;LaTeX preamble</a></h3>
<p>Configuration by LaTeX code in the document preamble is also possible
without a separate stylesheet. This way, packages can be loaded with
options or commands re-defined without the need to create a separate
file (new in Docutils 0.7).</p>
<dl class="docutils">
<dt>Option:</dt>
<dd><a class="reference external" href="config.html#latex-preamble">latex-preamble</a></dd>
<dt>Default:</dt>
<dd>used for <a class="reference internal" href="#font-setup">font setup</a></dd>
<dt>Example:</dt>
<dd><p class="first">To use the better looking <tt class="docutils literal">txtt</tt> font for monospaced text define the
<a class="reference external" href="config.html#latex-preamble">latex-preamble</a> setting in a configuration file:</p>
<pre class="last literal-block">
latex-preamble: \renewcommand{\ttdefault}{txtt}
                \usepackage{mathptmx}          % Times
                \usepackage[scaled=.92]{helvet}  % Helvetica
</pre>
</dd>
</dl>
</div>
<div class="section" id="templates">
<h3><a class="toc-backref" href="#id47">4.2.3&nbsp;&nbsp;&nbsp;Templates</a></h3>
<p>Some customizations require commands at places other than the insertion
point of stylesheets or depend on the deletion/replacement of parts of the
document. This can be done via a custom template. See the <a class="reference external" href="../api/publisher.html">publisher
documentation</a> for a description of the document parts available in a
template file.</p>
<dl class="docutils">
<dt>Option:</dt>
<dd><a class="reference external" href="config.html#template-latex2e-writer">template</a></dd>
</dl>
<p>In addition to the 'default.tex' template, the latex writer directory
contains the alternative 'titlepage.tex'.</p>
<dl class="docutils">
<dt>Example:</dt>
<dd><p class="first">Print a title page including docinfo, dedication, and abstract:</p>
<pre class="last literal-block">
--template=titlepage.tex
</pre>
</dd>
</dl>
</div>
<div class="section" id="raw-latex">
<h3><a class="toc-backref" href="#id48">4.2.4&nbsp;&nbsp;&nbsp;Raw LaTeX</a></h3>
<p>By means of the <a class="reference external" href="../ref/rst/directives.html#raw">raw directive</a> or a derived <a class="reference internal" href="#custom-role">custom role</a>, one can
give commands directly to LaTeX. These can be both, styling as well as
printing commands.</p>
<dl class="docutils">
<dt>Example:</dt>
<dd><p class="first">Math formula:</p>
<pre class="literal-block">
.. raw:: latex

   \[x^3 + 3x^2a + 3xa^2 + a^3,\]
</pre>
<p class="last">(Drawback: the formula will be invisible in other output formats.)</p>
</dd>
</dl>
<p>Most LaTeX code examples also work as raw LaTeX inside the document.
An exception are commands that need to be given in the document
preamble (e.g. package loading with <tt class="docutils literal">\usepackage</tt>, which can be
achieved with the <tt class="docutils literal"><span class="pre">--style-sheet</span></tt> or <tt class="docutils literal"><span class="pre">--latex-preamble</span></tt> command
line options instead). Remember to use <em>re-defining</em> commands for
customizing <a class="reference internal" href="#docutils-special-latex-macros">Docutils special LaTeX macros</a> with raw LaTeX.</p>
<dl class="docutils">
<dt>Example:</dt>
<dd><p class="first">Define the transition command as page break:</p>
<pre class="last literal-block">
.. raw:: latex

  \renewcommand*{\DUtransition}{\pagebreak[4]}
</pre>
</dd>
<dt>See also:</dt>
<dd><ul class="first last simple">
<li>Defining a macro for a <a class="reference internal" href="#custom-role">custom role</a>.</li>
<li>Forcing <a class="reference internal" href="#page-breaks">page breaks</a>.</li>
</ul>
</dd>
</dl>
</div>
</div>
</div>
<div class="section" id="how-to-configure-the">
<h1><a class="toc-backref" href="#id49">5&nbsp;&nbsp;&nbsp;How to configure the ...</a></h1>
<div class="section" id="admonitions">
<h2><a class="toc-backref" href="#id50">5.1&nbsp;&nbsp;&nbsp;admonitions</a></h2>
<p><a class="reference external" href="../ref/rst/directives.html#admonitions">Admonitions</a> are specially marked &quot;topics&quot; that can appear anywhere an
ordinary body element can.</p>
<dl class="docutils">
<dt>Command:</dt>
<dd><tt class="docutils literal">\DUadmonition</tt></dd>
<dt>Default:</dt>
<dd>Typeset in a frame (90&nbsp;% of text width).</dd>
</dl>
<p>The admonition title is typeset with the <tt class="docutils literal">\DUtitle</tt> command which also
takes a class argument. See <a class="reference internal" href="#topic-title">topic title</a></p>
<dl class="docutils">
<dt>Example 1:</dt>
<dd><p class="first">A lighter layout without the frame:</p>
<pre class="literal-block">
\newcommand{\DUadmonition}[2][class-arg]{%
  % try \DUadmonition#1{#2}:
  \ifcsname DUadmonition#1\endcsname%
    \csname DUadmonition#1\endcsname{#2}%
  \else
    \begin{quote}
      #2
    \end{quote}
  \fi
}
</pre>
<p class="last">The first part of this definition acts as a &quot;dispatcher&quot;. This way it is
possible to define a special handling of <a class="reference external" href="../ref/rst/directives.html#specific-admonitions">specific admonitions</a> based on
the &quot;class&quot; argument.</p>
</dd>
</dl>
<dl class="docutils">
<dt>Example 2:</dt>
<dd><p class="first">Use <tt class="docutils literal">.. note::</tt> for a margin note:</p>
<pre class="literal-block">
\newcommand{\DUadmonitionnote}[1]{\marginpar{#1}}
</pre>
<p class="last">Make sure there is enough space to fit the note.
See also the <a class="reference external" href="http://mirror.ctan.org/help/Catalogue/entries/marginnote.html">marginnote</a> and <a class="reference external" href="http://mirror.ctan.org/help/Catalogue/entries/pdfcomment.html">pdfcomment</a> packages.</p>
</dd>
</dl>
</div>
<div class="section" id="custom-interpreted-text-roles">
<span id="custom-role"></span><h2><a class="toc-backref" href="#id51">5.2&nbsp;&nbsp;&nbsp;custom interpreted text roles</a></h2>
<p>The rst <a class="reference external" href="../ref/rst/directives.html#role">role directive</a> allows defining custom <a class="reference external" href="../ref/rst/roles.html">text roles</a>
that mark parts of inline text (spans) with a class argument.</p>
<ul>
<li><p class="first">Role names and class arguments are converted to conform to the regular
expression <tt class="docutils literal"><span class="pre">[a-z][-a-z0-9]*</span></tt> (see <a class="reference external" href="../ref/rst/directives.html#class">class directive</a>).</p>
</li>
<li><p class="first">Class arguments may contain numbers and hyphens, which need special
treatment in LaTeX command names. (The special command <tt class="docutils literal">\&#64;namedef</tt> can
help with the definition of corresponding commands.)</p>
</li>
<li><p class="first">Custom roles can have multiple class arguments.</p>
<p>In contrast to HTML/CSS, the order of the class arguments might matter.</p>
</li>
</ul>
<dl class="docutils">
<dt>Commands:</dt>
<dd><p class="first"><tt class="docutils literal">\DUrole</tt>: dispatcher command</p>
<p class="last"><tt class="docutils literal">\DUroleCLASSARGUMENT</tt>: optional styling command</p>
</dd>
<dt>Default:</dt>
<dd>The definition of <tt class="docutils literal"><span class="pre">\DUrole{CLASSARGUMENT}{}</span></tt> calls the macro named
<tt class="docutils literal">\DUroleCLASSARGUMENT{}</tt><a class="footnote-reference" href="#id14" id="id13">[2]</a> if it is defined (but silently ignores
this class argument if a corresponding macro is not defined).</dd>
</dl>
<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="#id13">[2]</a></td><td>For backwards compatibility, the prefix <tt class="docutils literal"><span class="pre">\docutilsrole...</span></tt> in the
styling commands also recognized.</td></tr>
</tbody>
</table>
<dl class="docutils">
<dt>Example 1:</dt>
<dd><p class="first">Typeset text in small caps:</p>
<pre class="literal-block">
.. role:: smallcaps

:smallcaps:`Fourier` transformation
</pre>
<p>This is transformed to the LaTeX code:</p>
<pre class="literal-block">
\DUrole{smallcaps}{Fourier} transformation
</pre>
<p>The definition</p>
<pre class="literal-block">
\newcommand{\DUrolesmallcaps}{\textsc}
</pre>
<p class="last">as <a class="reference internal" href="#raw-latex">raw LaTeX</a> or in the custom <a class="reference internal" href="#style-sheet">style sheet</a> will give the expected
result (if the text <a class="reference internal" href="#font">font</a> supports small caps).</p>
</dd>
<dt>Example 2:</dt>
<dd><p class="first">Subscript text in normal size and <em>italic</em> shape:</p>
<pre class="literal-block">
.. role:: sub(subscript)
</pre>
<p>As &quot;sub&quot; inherits from the standard &quot;subscript&quot; role, the LaTeX macro
only needs to set the size and shape:</p>
<pre class="last literal-block">
\newcommand{\DUrolesub}{\normalsize\itshape}
</pre>
</dd>
<dt>Example 3:</dt>
<dd><p class="first">A role with several classes and a converted class name:</p>
<pre class="literal-block">
.. role:: custom4
   :class: argI argII arg_3
</pre>
<p>is translated to the nested commands:</p>
<pre class="literal-block">
\DUrole{argi}{\DUrole{argii}{\DUrole{arg-3}{&lt;content&gt;}}}
</pre>
<p>With the definitions:</p>
<pre class="literal-block">
\newcommand{\DUroleargi}[1]{\textsc}
\newcommand{\DUroleargii}[1]{{\large #1}}
\makeatletter
\&#64;namedef{DUrolearg-3}{\textbf}
\makeatother
</pre>
<p class="last">in a <a class="reference internal" href="#style-sheet">style sheet</a><a class="footnote-reference" href="#id16" id="id15">[3]</a> or as <a class="reference internal" href="#raw-latex">raw LaTeX</a> in the document source,
text styled with <tt class="docutils literal"><span class="pre">:custom4:`large</span> bold <span class="pre">small-caps`</span></tt> will be typeset
accordingly.</p>
</dd>
</dl>
<table class="docutils footnote" frame="void" id="id16" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id15">[3]</a></td><td>Leave out the <tt class="docutils literal">\makeatletter</tt> - <tt class="docutils literal">\makeatother</tt> pair if the style
sheet is a LaTeX package (<tt class="docutils literal">*.sty</tt>).</td></tr>
</tbody>
</table>
</div>
<div class="section" id="definition-lists">
<h2><a class="toc-backref" href="#id52">5.3&nbsp;&nbsp;&nbsp;definition lists</a></h2>
<p>ReStructuredText <a class="reference external" href="../ref/rst/restructuredtext.html#definition-lists">definition lists</a> correspond to HTML <tt class="docutils literal">&lt;dl&gt;</tt> list
objects.</p>
<dl class="docutils">
<dt>Environment:</dt>
<dd><tt class="docutils literal">description</tt>: LaTeX standard environment</dd>
<dt>Command:</dt>
<dd><tt class="docutils literal">\descriptionlabel</tt>: styling macro for the description term</dd>
<dt>Default:</dt>
<dd>bold label text, hanging indent</dd>
<dt>Example:</dt>
<dd><p class="first">A non-bold label can be achieved with:</p>
<pre class="last literal-block">
\renewcommand\descriptionlabel[1]{\hspace\labelsep \normalfont #1}
</pre>
</dd>
</dl>
</div>
<div class="section" id="document-class">
<h2><a class="toc-backref" href="#id53">5.4&nbsp;&nbsp;&nbsp;document class</a></h2>
<p>There are hundreds of LaTeX document classes installed by modern
LaTeX distributions, provided by publishers, or available at <a class="reference external" href="http://www.ctan.org">CTAN</a>.
The <a class="reference external" href="http://texcatalogue.sarovar.org/">TeX Catalogue</a> lists most of them.</p>
<dl class="docutils">
<dt>Popular document classes:</dt>
<dd><ul class="first last simple">
<li>article, report, book: standard document classes</li>
<li>scrartcl, scrrprt, scrbook: <a class="reference external" href="http://mirror.ctan.org/help/Catalogue/entries/koma-script.html">KOMA-script</a> classes</li>
<li><a class="reference external" href="http://mirror.ctan.org/help/Catalogue/entries/memoir.html">memoir</a>: highly configurable class for larger documents</li>
</ul>
</dd>
<dt>Option:</dt>
<dd><a class="reference external" href="config.html#documentclass">documentclass</a></dd>
</dl>
</div>
<div class="section" id="document-info">
<h2><a class="toc-backref" href="#id54">5.5&nbsp;&nbsp;&nbsp;document info</a></h2>
<p>Content of the <a class="reference external" href="../ref/rst/restructuredtext.html#bibliographic-fields">bibliographic fields</a> at the top of a document.
By default, docinfo items are typeset as a table.</p>
<dl class="docutils">
<dt>Options:</dt>
<dd><a class="reference external" href="config.html#use-latex-docinfo">use-latex-docinfo</a>, <a class="reference external" href="config.html#use-latex-abstract">use-latex-abstract</a></dd>
<dt>Length:</dt>
<dd><tt class="docutils literal">\DUdocinfowidth</tt>: the width for the <span class="incremental">docinfo</span> table.</dd>
<dt>Default:</dt>
<dd>90&nbsp;% of text width: <tt class="docutils literal">0.9\textwidth</tt></dd>
<dt>Example:</dt>
<dd><p class="first">set to 70&nbsp;% of text width:</p>
<pre class="last literal-block">
\newlength{\DUdocinfowidth}
\setlength{\DUdocinfowidth}{0.7\textwidth}
</pre>
</dd>
</dl>
</div>
<div class="section" id="document-title">
<h2><a class="toc-backref" href="#id55">5.6&nbsp;&nbsp;&nbsp;document title</a></h2>
<p>A lone top-level section title is (usually) transformed to the document title
(see <a class="reference external" href="rst/quickref.html#section-structure">section structure</a>).</p>
<p>The format of the document title is defined by the <a class="reference internal" href="#document-class">document class</a>. The
&quot;article&quot; document class uses an in-page title and the &quot;report&quot; and &quot;book&quot;
classes write a separate title page. See the <a class="reference external" href="http://www.tex.ac.uk/faq">TeX FAQ</a> on how to customize
the <a class="reference external" href="http://www.tex.ac.uk/cgi-bin/texfaq2html?label=titlsty">style of document titles</a>.</p>
<p>The default title page shows only title and subtitle, date and author
are shown in the <a class="reference internal" href="#document-info">document info</a> table.</p>
<dl class="docutils">
<dt>Options:</dt>
<dd><p class="first"><a class="reference external" href="config.html#use-latex-docinfo">use-latex-docinfo</a></p>
<p class="last"><tt class="docutils literal"><span class="pre">--template=titlepage.tex</span></tt> Put docinfo and abstract into the title page.
A separate title page is used also with the &quot;abstract&quot; document class.</p>
</dd>
</dl>
</div>
<div class="section" id="field-lists">
<h2><a class="toc-backref" href="#id56">5.7&nbsp;&nbsp;&nbsp;field lists</a></h2>
<p><a class="reference external" href="../ref/rst/restructuredtext.html#field-lists">Field lists</a> may be used as generic two-column table constructs in
documents.</p>
<dl class="docutils">
<dt>Environment:</dt>
<dd><tt class="docutils literal">DUfieldlist</tt></dd>
<dt>Default:</dt>
<dd>Indented description list.</dd>
<dt>Example:</dt>
<dd><p class="first">Use a description list customized with <a class="reference external" href="http://mirror.ctan.org/help/Catalogue/entries/enumitem.html">enumitem</a>:</p>
<pre class="literal-block">
\usepackage{enumitem}
\newenvironment{DUfieldlist}%
  {\description[font=,style=sameline,leftmargin=8em]}
  {\enddescription}
}
</pre>
<p class="last">The <a class="reference external" href="http://mirror.ctan.org/help/Catalogue/entries/koma-script.html">KOMA-script</a> classes provide a similar environment under the name
<span class="incremental">labeling</span>.</p>
</dd>
</dl>
</div>
<div class="section" id="figure-and-table-captions">
<h2><a class="toc-backref" href="#id57">5.8&nbsp;&nbsp;&nbsp;figure and table captions</a></h2>
<p>The <a class="reference external" href="http://mirror.ctan.org/help/Catalogue/entries/caption.html">caption</a> package provides many ways to customise the captions in
floating environments like figure and table.</p>
<p>The <a class="reference external" href="http://mirror.ctan.org/help/Catalogue/entries/chngcntr.html">chngcntr</a> package helps to configure the numbering of figure and table
caption numberings.</p>
<p>Some document classes (e.g. <a class="reference external" href="http://mirror.ctan.org/help/Catalogue/entries/koma-script.html">KOMA-script</a>) provide additional configuration.
Also see the related <a class="reference external" href="http://www.tex.ac.uk/cgi-bin/texfaq2html?label=running-nos">LaTeX FAQ entry</a></p>
<dl class="docutils">
<dt>Example</dt>
<dd><pre class="first last literal-block">
\usepackage{caption}
\captionsetup{justification=raggedleft,singlelinecheck=false}
</pre>
</dd>
</dl>
</div>
<div class="section" id="figure-placement">
<h2><a class="toc-backref" href="#id58">5.9&nbsp;&nbsp;&nbsp;figure placement</a></h2>
<p><a class="reference external" href="../ref/rst/directives.html#figure">Figures</a> might be typeset at the place of definition (default) or &quot;float&quot;
to a suitable place at the top or bottom of a page. This is implemented
using the <a class="reference external" href="http://mirror.ctan.org/help/Catalogue/entries/float.html">float</a> package.</p>
<dl class="docutils">
<dt>Command:</dt>
<dd><tt class="docutils literal">\floatplacement</tt></dd>
</dl>
<p>The placement setting is valid from the point of definition until the next
<tt class="docutils literal">\floatplacement</tt> command or the end of the document. See <a class="reference external" href="http://mirror.ctan.org/macros/latex/contrib/float/float.pdf">float.pdf</a> for
details.</p>
<dl class="docutils">
<dt>Default:</dt>
<dd><tt class="docutils literal"><span class="pre">\floatplacement{figure}{H}</span></tt> (here definitely). This corresponds most
closely to the source and HTML placement (principle of least surprise).</dd>
<dt>Example 1:</dt>
<dd><p class="first">In a custom <a class="reference internal" href="#style-sheet">style sheet</a>, set the default to let LaTeX find a suitable
place for figure floats:</p>
<pre class="last literal-block">
\usepackage{float}
\floatplacement{figure}{htbp} % here, top, bottom, extra-page
</pre>
</dd>
<dt>Example 2:</dt>
<dd><p class="first">To move all following figures to the top or bottom of the page write in
the document source:</p>
<pre class="last literal-block">
.. raw:: latex

    \floatplacement{figure}{tb}
</pre>
</dd>
</dl>
</div>
<div class="section" id="font">
<span id="font-setup"></span><h2><a class="toc-backref" href="#id59">5.10&nbsp;&nbsp;&nbsp;font</a></h2>
<p>The selected text font influences the <em>look</em>, the <em>feel</em>,
and the <em>readability</em> of the document (cf.
<a class="reference external" href="http://www.csarven.ca/web-typography">http://www.csarven.ca/web-typography</a>).
Selecting a suitable font also solves the problem with <a class="reference internal" href="#bad-looking-pdf-output">bad looking
PDF output</a>.</p>
<p>Font selection is one of the main differences between LaTeX and XeTeX:</p>
<dl class="docutils">
<dt>LaTeX</dt>
<dd>cannot use the fonts of the operating system directly but needs
specially installed fonts with additional supporting files.</dd>
<dt>XeTeX</dt>
<dd>can use system fonts and provides access to the full feature set of
modern <a class="reference external" href="http://en.wikipedia.org/wiki/OpenType">OpenType</a> fonts.</dd>
</dl>
<p>The default font setup is done in the <a class="reference external" href="config.html#latex-preamble">latex-preamble</a>:</p>
<dl class="docutils">
<dt>LaTeX</dt>
<dd><a class="reference external" href="http://en.wikipedia.org/wiki/PDF#Standard_Type_1_Fonts">PDF standard fonts</a> (Times, Helvetica, Courier)</dd>
<dt>XeTeX</dt>
<dd><p class="first"><a class="reference external" href="http://www.linuxlibertine.org/index.php?id=1&amp;L=1">Linux Libertine</a>, a free, high quality alternative to Times with a
wide coverage of glyphs, styles, and OpenType features.</p>
<p class="last">Despite its name, Linux Libertine can be used on any operating
system that can handle OpenType fonts.</p>
</dd>
</dl>
<p>Alternative fonts can be selected by</p>
<dl class="docutils">
<dt>LaTeX</dt>
<dd><ol class="first loweralpha simple">
<li>specifying the corresponding LaTeX package(s) as argument to the
<a class="reference external" href="config.html#stylesheet-latex2e-writer">stylesheet</a> <a class="reference internal" href="#option">option</a> or with the <tt class="docutils literal">\usepackage</tt> LaTeX command.<ul>
<li>packages can be combined,</li>
<li>passing options to a package is only possible in a <a class="reference internal" href="#style-sheet">style sheet</a>
or the <a class="reference internal" href="#latex-preamble">LaTeX preamble</a>.</li>
</ul>
</li>
<li>changing the font-default macros <tt class="docutils literal">\rmdefault</tt>, <tt class="docutils literal">\sfdefault</tt>
and/or <tt class="docutils literal">\ttdefault</tt> in a custom <a class="reference internal" href="#style-sheet">style sheet</a>, the <a class="reference internal" href="#latex-preamble">LaTeX
preamble</a> or <a class="reference internal" href="#raw-latex">raw LaTeX</a>.</li>
</ol>
<dl class="docutils">
<dt>Example 1:</dt>
<dd><p class="first">Use <a class="reference external" href="http://mirror.ctan.org/help/Catalogue/entries/lm.html">Latin Modern</a>. <a class="reference internal" href="#latex-code">LaTeX code</a>:</p>
<pre class="literal-block">
\usepackage{lmodern}
</pre>
<p>Command line argument:</p>
<pre class="last literal-block">
--stylesheet=lmodern
</pre>
</dd>
<dt>Example 2:</dt>
<dd><p class="first">The <span class="target" id="times-helvetica-courier">Times/Helvetica/Courier</span> <a class="reference external" href="http://en.wikipedia.org/wiki/PDF#Standard_Type_1_Fonts">PDF standard fonts</a> are
selected by the LaTeX code <a class="footnote-reference" href="#id22" id="id21">[4]</a>:</p>
<pre class="literal-block">
\usepackage{mathptmx}            % Times for serif and math
\usepackage[scaled=.90]{helvet}  % downscaled Helvetica for sans serif
\usepackage{courier}             % Courier for teletype (mono-space)
</pre>
<p class="last">Since Docutils 0.7, this is the default value of the
<a class="reference external" href="config.html#latex-preamble">latex-preamble</a> option.</p>
</dd>
</dl>
<table class="docutils footnote" frame="void" id="id22" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id21">[4]</a></td><td>When generating PDF-files from LaTeX, the <a class="reference external" href="http://en.wikipedia.org/wiki/PDF#Standard_Type_1_Fonts">PDF standard
fonts</a> do not need to be embedded in the document. While this
results in smaller files, the actually used fonts on screen and in
print might differ! (For details see, e.g., the <a class="reference external" href="http://www.tex.ac.uk/tex-archive/help/Catalogue/entries/testflow.html">testflow</a> package
documentation.)</td></tr>
</tbody>
</table>
<dl class="last docutils">
<dt>Example 3:</dt>
<dd><p class="first">Use the teletype font from the <a class="reference external" href="http://mirror.ctan.org/help/Catalogue/entries/txfonts.html">txfonts</a> package. As there is no
package for this, we re-define the font macro with the <a class="reference internal" href="#latex-code">LaTeX code</a>:</p>
<pre class="last literal-block">
\renewcommand{\ttdefault}{txtt}
</pre>
</dd>
</dl>
</dd>
<dt>XeTeX</dt>
<dd><p class="first">using the macros of the <a class="reference external" href="http://mirror.ctan.org/help/Catalogue/entries/fontspec.html">fontspec</a> package. Use some font-viewer or
-manager (e.g. <a class="reference external" href="http://fontmatrix.net/">fontmatrix</a>) to find out the correct names of the
fonts on your system.</p>
<dl class="last docutils">
<dt>Example:</dt>
<dd><p class="first"><a class="reference external" href="http://dejavu-fonts.org/">DejaVu</a>, very wide coverage, screen optimized. As this font
runs wide, add <tt class="docutils literal">DIV=10</tt> to the <a class="reference external" href="config.html#documentoptions">documentoptions</a>:</p>
<pre class="last literal-block">
\setmainfont{DejaVu Serif}
\setsansfont{DejaVu Sans}
\setmonofont[HyphenChar=None]{DejaVu Sans Mono}
</pre>
</dd>
</dl>
</dd>
</dl>
<div class="section" id="choice-of-suitable-fonts">
<h3><a class="toc-backref" href="#id60">5.10.1&nbsp;&nbsp;&nbsp;choice of suitable fonts</a></h3>
<p>High quality free fonts suitable for use with XeTeX are, e.g., listed
at <a class="reference external" href="http://typophile.com/node/18207">Good Libre Fonts</a>, <a class="reference external" href="http://www.alvit.de/blog/article/20-best-license-free-official-fonts">25 Best Free Quality Fonts</a> and the update
<a class="reference external" href="http://www.smashingmagazine.com/2006/10/11/17-more-free-quality-fonts/">19 More Free Quality Fonts</a>.</p>
<p>The <a class="reference external" href="http://www.tug.dk/FontCatalogue/">LaTeX Font Catalogue</a> provides information and examples for a wide
range of fonts available for use with LaTeX. Here is just a selection:</p>
<ol class="loweralpha">
<li><p class="first">The <a class="reference external" href="http://mirror.ctan.org/help/Catalogue/entries/lm.html">Latin Modern</a> (LM) fonts are extended outline versions of the
standard TeX font Computer Modern (CM).</p>
<table class="docutils option-list" frame="void" rules="none">
<col class="option" />
<col class="description" />
<tbody valign="top">
<tr><td class="option-group">
<kbd><span class="option">+1</span></kbd></td>
<td><p class="first last">simple invocation:  <tt class="docutils literal"><span class="pre">--stylesheet=lmodern</span></tt></p>
</td></tr>
<tr><td class="option-group">
<kbd><span class="option">+1</span></kbd></td>
<td><p class="first">keeps the traditional TeX &quot;look and feel&quot;:</p>
<table class="last docutils option-list" frame="void" rules="none">
<col class="option" />
<col class="description" />
<tbody valign="top">
<tr><td class="option-group">
<kbd><span class="option">+1</span></kbd></td>
<td><p class="first last">generally accepted as high quality CM replacement,</p>
</td></tr>
<tr><td class="option-group">
<kbd><span class="option">+1</span></kbd></td>
<td><p class="first last">comprehensive math support,</p>
</td></tr>
<tr><td class="option-group">
<kbd><span class="option">+1</span></kbd></td>
<td><p class="first last">including optical sizes,</p>
</td></tr>
<tr><td class="option-group">
<kbd><span class="option">+1</span></kbd></td>
<td><p class="first last">compatible with extensions made to match CM,</p>
</td></tr>
<tr><td class="option-group">
<kbd><span class="option">-1</span></kbd></td>
<td><p class="first last">modern types are hard to read at low (screen) resolutions.</p>
</td></tr>
</tbody>
</table>
</td></tr>
<tr><td class="option-group">
<kbd><span class="option">-2</span></kbd></td>
<td><p class="first">not part of a minimal standard TeX installation</p>
<table class="last docutils option-list" frame="void" rules="none">
<col class="option" />
<col class="description" />
<tbody valign="top">
<tr><td class="option-group">
<kbd><span class="option">-1</span></kbd></td>
<td><p class="first last">might not work out-of-the-box</p>
</td></tr>
<tr><td class="option-group">
<kbd><span class="option">-1</span></kbd></td>
<td><p class="first last">large additional download (ca. 12 ... 17 MB)</p>
</td></tr>
</tbody>
</table>
</td></tr>
</tbody>
</table>
</li>
<li><p class="first"><a class="reference external" href="http://mirror.ctan.org/help/Catalogue/entries/cm-super.html">CM-Super</a> is another outline CM replacement.</p>
<table class="docutils option-list" frame="void" rules="none">
<col class="option" />
<col class="description" />
<tbody valign="top">
<tr><td class="option-group">
<kbd><span class="option">+1</span></kbd></td>
<td><p class="first last">simple invocation: modern LaTeX distributions use CM-Super
automatically instead of CM if it is installed.</p>
</td></tr>
<tr><td class="option-group">
<kbd><span class="option">-1</span></kbd></td>
<td><p class="first last">said to be of inferior quality compared to LM.</p>
</td></tr>
<tr><td class="option-group">
<kbd><span class="option">-2</span></kbd></td>
<td><p class="first last">not part of a minimal standard TeX installation,
even bigger download size than Latin Modern.</p>
</td></tr>
</tbody>
</table>
</li>
<li><p class="first"><a class="reference external" href="http://mirror.ctan.org/help/Catalogue/entries/bera.html">Bera</a> (Bitstream Vera)</p>
<table class="docutils option-list" frame="void" rules="none">
<col class="option" />
<col class="description" />
<tbody valign="top">
<tr><td class="option-group">
<kbd><span class="option">+1</span></kbd></td>
<td><p class="first last">simple invocation:  <tt class="docutils literal"><span class="pre">--stylesheet=bera</span></tt></p>
</td></tr>
<tr><td class="option-group">
<kbd><span class="option">+1</span></kbd></td>
<td><p class="first last">optimized for on-screen viewing with goot hinting</p>
</td></tr>
<tr><td class="option-group">
<kbd><span class="option">-2</span></kbd></td>
<td><p class="first last">not part of a minimal standard TeX installation</p>
</td></tr>
</tbody>
</table>
</li>
<li><p class="first"><a class="reference external" href="http://mirror.ctan.org/help/Catalogue/entries/psnfss.html">PSNFSS</a> Postscript fonts</p>
<table class="docutils option-list" frame="void" rules="none">
<col class="option" />
<col class="description" />
<tbody valign="top">
<tr><td class="option-group">
<kbd><span class="option">+1</span></kbd></td>
<td><p class="first last">part of every standard TeX installation</p>
</td></tr>
<tr><td class="option-group">
<kbd><span class="option">+1</span></kbd></td>
<td><p class="first last">smaller PDF/Postscript document size if standard fonts are not
embedded</p>
</td></tr>
<tr><td class="option-group">
<kbd><span class="option">-1</span></kbd></td>
<td><p class="first last">restricted set of glyphs in the free versions <a class="footnote-reference" href="#id25" id="id24">[5]</a></p>
</td></tr>
<tr><td class="option-group">
<kbd><span class="option">-1</span></kbd></td>
<td><p class="first last">different fonts for roman, sans-serif and typewriter fonts.</p>
</td></tr>
<tr><td class="option-group">
<kbd><span class="option">-1</span></kbd></td>
<td><p class="first last">invocation somewhat more complex, as several packages are
required for a complete font set, sometimes including package
options.</p>
</td></tr>
</tbody>
</table>
<p>Roman (serif) PSNFSS fonts:</p>
<dl class="docutils">
<dt>Bookman</dt>
<dd><p class="first last">good legibility but very wide.</p>
</dd>
<dt>Charter</dt>
<dd><p class="first last">bread-and-butter type optimized for printing on low-resolution
printers</p>
</dd>
<dt>New Century Schoolbook</dt>
<dd><p class="first last">good legibility but very wide.</p>
</dd>
<dt>Palatino</dt>
<dd><table class="first last docutils option-list" frame="void" rules="none">
<col class="option" />
<col class="description" />
<tbody valign="top">
<tr><td class="option-group">
<kbd><span class="option">+1</span></kbd></td>
<td><p class="first last">recommended by font experts</p>
</td></tr>
<tr><td class="option-group">
<kbd><span class="option">+1</span></kbd></td>
<td><p class="first last">good LaTeX support including matching math fonts, small caps,
old-style figures</p>
</td></tr>
<tr><td class="option-group">
<kbd><span class="option">-1</span></kbd></td>
<td><p class="first last">bad rendering in xpdf viewer (auto-hinting leads to different
x-hight for different characters at some magnifications)
(this is fixed in recent versions).</p>
</td></tr>
</tbody>
</table>
</dd>
<dt>Times</dt>
<dd><table class="first last docutils option-list" frame="void" rules="none">
<col class="option" />
<col class="description" />
<tbody valign="top">
<tr><td class="option-group">
<kbd><span class="option">+1</span></kbd></td>
<td><p class="first last">the serif <a class="reference external" href="http://en.wikipedia.org/wiki/PDF#Standard_Type_1_Fonts">PDF Standard Font</a>,</p>
</td></tr>
<tr><td class="option-group">
<kbd><span class="option">-1</span></kbd></td>
<td><p class="first last">overused and quite narrow (devised for multi-column layouts).</p>
</td></tr>
</tbody>
</table>
</dd>
<dt>Utopia</dt>
<dd><p class="first last">recommended by font experts</p>
</dd>
</dl>
<table border="1" class="docutils">
<caption>Font packages for standard Postscript fonts
         (cf. <a class="reference external" href="http://mirror.ctan.org/macros/latex/required/psnfss/psnfss2e.pdf">Using common Postscript fonts with LaTeX</a>)</caption>
<colgroup>
<col width="16%" />
<col width="21%" />
<col width="23%" />
<col width="23%" />
<col width="16%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Package</th>
<th class="head">Roman</th>
<th class="head">Sans Serif</th>
<th class="head">Typewriter</th>
<th class="head">Math</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>(none)</td>
<td>CM Roman</td>
<td>CM Sans Serif</td>
<td>CM Typewriter</td>
<td>CM Math</td>
</tr>
<tr><td>mathpazo</td>
<td>Palatino</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>Palatino</td>
</tr>
<tr><td>mathptmx</td>
<td>Times</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>Times</td>
</tr>
<tr><td>helvet</td>
<td>&nbsp;</td>
<td>Helvetica</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>avant</td>
<td>&nbsp;</td>
<td>Avant Garde</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>courier</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>Courier</td>
<td>&nbsp;</td>
</tr>
<tr><td>chancery</td>
<td>Zapf
Chancery</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>bookman</td>
<td>Bookman</td>
<td>Avant Garde</td>
<td>Courier</td>
<td>&nbsp;</td>
</tr>
<tr><td>newcent</td>
<td>New Century
Schoolbook</td>
<td>Avant Garde</td>
<td>Courier</td>
<td>&nbsp;</td>
</tr>
<tr><td>charter</td>
<td>Charter</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<tr><td>utopia</td>
<td>Utopia</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
</li>
</ol>
<table class="docutils footnote" frame="void" id="id25" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id24">[5]</a></td><td>Extended versions of the standard Postscript fonts including
accented chars, Greek and Cyrillic as well as real small-caps
and old-style numbers are available with the <a class="reference external" href="http://www.gust.org.pl/projects/e-foundry/tex-gyre">TeX Gyre</a> bundle
which is part of, e.g., <a class="reference external" href="http://tug.org/texlive/">TeX Live</a>.</td></tr>
</tbody>
</table>
</div>
</div>
<div class="section" id="font-encoding">
<h2><a class="toc-backref" href="#id61">5.11&nbsp;&nbsp;&nbsp;font encoding</a></h2>
<p>LaTeX font encodings are described in detail in the <a class="reference external" href="http://mirror.ctan.org/macros/latex/doc/encguide.pdf">encguide</a> which is
part of the LaTeX base documentation.</p>
<dl class="docutils">
<dt>Option:</dt>
<dd><a class="reference external" href="config.html#font-encoding">font-encoding</a></dd>
<dt>Default:</dt>
<dd>&quot;T1&quot;</dd>
<dt>Example 1:</dt>
<dd><p class="first">Use the (obsolete) LaTeX default encoding &quot;OT1&quot;:</p>
<pre class="literal-block">
--font-encoding=OT1
</pre>
<p>or (without loading the <a class="reference external" href="http://mirror.ctan.org/help/Catalogue/entries/fontenc.html">fontenc</a> package):</p>
<pre class="literal-block">
--font-encoding=&quot;&quot;
</pre>
<p class="last">This will improve the look on screen with the default Computer Modern
fonts at the expense of problems with <a class="reference internal" href="#search-and-text-extraction">search and text extraction</a>
The recommended way is to select a T1-encoded &quot;Type 1&quot; (vector)
font, for example <a class="reference external" href="http://mirror.ctan.org/help/Catalogue/entries/lm.html">Latin Modern</a></p>
</dd>
<dt>Example 2:</dt>
<dd><p class="first">Support for characters in the Unicode blocks Latin, Latin-1 Supplement,
and Greek together with a T1-encoded &quot;Type 1&quot; (vector) font, for example
<a class="reference external" href="http://mirror.ctan.org/help/Catalogue/entries/lm.html">Latin Modern</a>:</p>
<pre class="last literal-block">
--font-encoding=LGR,T1 --stylesheet=lmodern
</pre>
</dd>
</dl>
</div>
<div class="section" id="font-size">
<h2><a class="toc-backref" href="#id62">5.12&nbsp;&nbsp;&nbsp;font size</a></h2>
<p>Add font size in points to the document options, e.g.
<tt class="docutils literal"><span class="pre">--documentoptions=12</span></tt>, use e.g. the document classes provided by
<a class="reference external" href="http://mirror.ctan.org/help/Catalogue/entries/extsizes.html">extsizes</a> for values other than [10,11,12].</p>
</div>
<div class="section" id="footnotes">
<h2><a class="toc-backref" href="#id63">5.13&nbsp;&nbsp;&nbsp;footnotes</a></h2>
<p>By default, footnotes are set with Docutils-specific wrappers around
the standard <tt class="docutils literal">\footnotemark</tt> and <tt class="docutils literal">\footnotetext</tt> commands.  You
can configure the footnote layout similar to standard LaTeX footnotes
in a custom <a class="reference internal" href="#style-sheet">style sheet</a>.</p>
<p>Further configuration is possible by alternative definitions of
<tt class="docutils literal">\DUfootnotemark</tt> and <tt class="docutils literal">\DUfootnotetext</tt></p>
<dl class="docutils">
<dt>Example 1:</dt>
<dd><p class="first">Set footnote text with a hanging indent.</p>
<ul class="last">
<li><p class="first">This is the default with <a class="reference external" href="http://mirror.ctan.org/help/Catalogue/entries/koma-script.html">KOMA-script</a> classes, e.g:</p>
<pre class="literal-block">
--documentclass=scrartcl
</pre>
<p>(for further configuration, see the <a class="reference external" href="http://mirror.ctan.org/macros/latex/contrib/koma-script/scrguien.pdf">KOMA-script Guide</a>),</p>
</li>
<li><p class="first">with package <a class="reference external" href="http://mirror.ctan.org/help/Catalogue/entries/footmisc.html">footmisc</a>:</p>
<pre class="literal-block">
\usepackage[hang]{footmisc}
\setlength{\footnotemargin}{0em}
</pre>
<p>(play with the <tt class="docutils literal">\footnotemargin</tt> setting),</p>
</li>
<li><p class="first">redefine <tt class="docutils literal">\DUfootnotetext</tt> inserting <span class="incremental">hangindent</span>:</p>
<pre class="literal-block">
\newcommand{\DUfootnotetext}[4]{%
  \begingroup%
  \renewcommand{\thefootnote}{%
    \protect\raisebox{1em}{\protect\hypertarget{#1}{}}%
    \protect\hyperlink{#2}{#3}}%
    \footnotetext{\hangindent=2em #4}%
  \endgroup%
}
</pre>
<p>(adapt the <tt class="docutils literal">\hangindent</tt> value).</p>
</li>
</ul>
</dd>
<dt>Example 2:</dt>
<dd><p class="first">place the footnote text where it appears in the source document (instead
of at the page bottom). This can be used to get the effect of endnotes
(needs the <a class="reference external" href="http://mirror.ctan.org/help/Catalogue/entries/hanging.html">hanging</a> package):</p>
<pre class="last literal-block">
\usepackage{hanging}
\newcommand{\DUfootnotetext}[4]{%
  \par\noindent\raisebox{1em}{\hypertarget{#1}{}}%
  \hyperlink{#2}{#3}%
  \hangpara{\parindent}{1}#4%
}
</pre>
</dd>
</dl>
</div>
<div class="section" id="hyphenation">
<h2><a class="toc-backref" href="#id64">5.14&nbsp;&nbsp;&nbsp;hyphenation</a></h2>
<p>The amount of hyphenation is influenced by <tt class="docutils literal">\hyphenpenalty</tt>, setting it to
10000 almost prevents hyphenation. As this produces lines with more space
between words one should increase Latex's <tt class="docutils literal">\tolerance</tt> for this.</p>
<dl class="docutils">
<dt>Example:</dt>
<dd><pre class="first last literal-block">
\hyphenpenalty=5000
\tolerance=1000
</pre>
</dd>
</dl>
</div>
<div class="section" id="hyperlinks">
<h2><a class="toc-backref" href="#id65">5.15&nbsp;&nbsp;&nbsp;hyperlinks</a></h2>
<dl class="docutils">
<dt>Options:</dt>
<dd><a class="reference external" href="config.html#hyperlink-color">hyperlink-color</a>, <a class="reference external" href="config.html#hyperref-options">hyperref-options</a></dd>
</dl>
<p>Hyperlinks are realized using the <a class="reference external" href="http://mirror.ctan.org/help/Catalogue/entries/hyperref.html">hyperref</a> package. As it re-defines many
standard LaTeX macros, this package is loaded last, <em>after</em> the style
sheets.</p>
<p>However, you can load hyperref before a package that requires its
presence in a <a class="reference internal" href="#style-sheet">style sheet</a> or the <a class="reference internal" href="#latex-preamble">LaTeX preamble</a> (see example
below). This will ignore options set with <a class="reference external" href="config.html#hyperlink-color">hyperlink-color</a> and
<a class="reference external" href="config.html#hyperref-options">hyperref-options</a>.</p>
<p>URLs are typeset with the &quot;url&quot; package (loaded implicitely by &quot;hyperref&quot;).
The font of URLs can be defined with the <tt class="docutils literal">\urlstyle</tt> command. Valid
arguments are</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">same:</th><td class="field-body">normal text font, Docutils default,</td>
</tr>
<tr class="field"><th class="field-name">tt:</th><td class="field-body">teletype (monospaced), LaTeX default,</td>
</tr>
<tr class="field"><th class="field-name">rm:</th><td class="field-body">roman,</td>
</tr>
<tr class="field"><th class="field-name">sf:</th><td class="field-body">sans serif</td>
</tr>
</tbody>
</table>
<dl class="docutils">
<dt>Example:</dt>
<dd><p class="first">Custom loading of the hyperref package also switches to
the LaTeX default (monospaced fonts for URLs). Reset to use the text
font:</p>
<pre class="last literal-block">
\usepackage[unicode,colorlinks=true,linkcolor=green]{hyperref}
\urlstyle{same}
</pre>
</dd>
</dl>
<p>See also <a class="reference internal" href="#non-breaking-hyperlinks">non-breaking hyperlinks</a>.</p>
<div class="section" id="disable-hyperlinks">
<h3><a class="toc-backref" href="#id66">5.15.1&nbsp;&nbsp;&nbsp;disable hyperlinks</a></h3>
<p>To suppress the hyper-linking completely (e.g. for printing or to
avoid clashes with other packages), set <a class="reference external" href="config.html#hyperref-options">hyperref-options</a> to &quot;draft&quot;
or load the &quot;nohyperref&quot; package that comes with the &quot;hyperref&quot;
bundle.</p>
<dl class="docutils">
<dt>Option:</dt>
<dd><tt class="docutils literal"><span class="pre">--hyperref-options=draft</span></tt></dd>
</dl>
<p><a class="reference internal" href="#latex-code">LaTeX code</a>:</p>
<pre class="literal-block">
\usepackage{nohyperref,url}
\urlstyle{same}
</pre>
</div>
</div>
<div class="section" id="line-blocks">
<h2><a class="toc-backref" href="#id67">5.16&nbsp;&nbsp;&nbsp;line blocks</a></h2>
<p>In <a class="reference external" href="../ref/rst/restructuredtext.html#line-blocks">line blocks</a>, newlines and leading whitespace are respected.</p>
<dl class="docutils">
<dt>Environment:</dt>
<dd><tt class="docutils literal">DUlineblock</tt>: special list environment for line blocks</dd>
<dt>Length:</dt>
<dd><tt class="docutils literal">\DUlineblockindent</tt>: indentation of indented lineblock parts.</dd>
<dt>Default:</dt>
<dd>2.5 times the font hight: <tt class="docutils literal">2.5em</tt></dd>
<dt>Example:</dt>
<dd><p class="first">set to the paragraph indentation:</p>
<pre class="last literal-block">
\newlength{\DUlineblockindent}
\setlength{\DUlineblockindent}{\parindent}
</pre>
</dd>
</dl>
</div>
<div class="section" id="line-spacing">
<h2><a class="toc-backref" href="#id68">5.17&nbsp;&nbsp;&nbsp;line spacing</a></h2>
<dl class="docutils">
<dt>Commands:</dt>
<dd><p class="first"><tt class="docutils literal">\linespread</tt>: for small adjustments</p>
<p class="last"><tt class="docutils literal">\singlespacing</tt>, <tt class="docutils literal">\onehalfspacing</tt>, and <tt class="docutils literal">\doublespacing</tt>: from
package <span class="incremental">setspace</span></p>
</dd>
<dt>Example 1:</dt>
<dd><p class="first">Get document wide double spacing:</p>
<pre class="last literal-block">
\usepackage{setspace}
\doublespacing
</pre>
</dd>
<dt>Example 2:</dt>
<dd><p class="first">Increase line spacing by five percent for better readability:</p>
<pre class="last literal-block">
\linespread{1.05}
</pre>
</dd>
</dl>
</div>
<div class="section" id="literal-blocks">
<h2><a class="toc-backref" href="#id69">5.18&nbsp;&nbsp;&nbsp;literal blocks</a></h2>
<p>No markup processing is done within a <a class="reference external" href="../ref/rst/restructuredtext.html#literal-blocks">literal block</a>. It is left as-is,
and is typically rendered in a monospaced typeface</p>
<dl class="docutils">
<dt>Option:</dt>
<dd><a class="reference external" href="config.html#literal-block-env">literal-block-env</a></dd>
</dl>
<p>Example:</p>
<blockquote>
<p><tt class="docutils literal"><span class="pre">--literal-block-env=lstlisting</span></tt></p>
<p>The <tt class="docutils literal">lstlisting</tt> environment is highly configurable (as documented in
<a class="reference external" href="http://mirror.ctan.org/macros/latex/contrib/listings/listings.pdf">listings.pdf</a>), for instance</p>
<pre class="literal-block">
\renewcommand{\ttdefault}{txtt}
\lstset{language=Python, morekeywords=[1]{yield}}
\lstloadlanguages{Python}
\lstset{
  basicstyle=\ttfamily,
  keywordstyle=\bfseries,
  commentstyle=\rmfamily\itshape,
  stringstyle=\slshape,
}
\lstset{showstringspaces=false}
\lstset{columns=fullflexible,
     basewidth={0.5em,0.4em}}
</pre>
<p>The indentation of literal blocks can be reset with</p>
<pre class="literal-block">
\lstset{resetmargins=true}
</pre>
<p>and/or configured with e.&nbsp;g.:</p>
<pre class="literal-block">
\lstset{xleftmargin=-2em}
</pre>
</blockquote>
</div>
<div class="section" id="list-of-figures-tables">
<h2><a class="toc-backref" href="#id70">5.19&nbsp;&nbsp;&nbsp;list of figures/tables</a></h2>
<p>Docutils does not support lists of figures or tables.</p>
<p>However, with LaTeX, they can be generated using <a class="reference internal" href="#raw-latex">raw LaTeX</a> in the
document source.</p>
<dl class="docutils">
<dt>Commands:</dt>
<dd><p class="first"><tt class="docutils literal">\listoffigures</tt>: a list of figures</p>
<p class="last"><tt class="docutils literal">\listoftables</tt>: a list of tables</p>
</dd>
<dt>Example:</dt>
<dd><pre class="first last literal-block">
.. raw:: latex

   \listoffigures
</pre>
</dd>
</dl>
</div>
<div class="section" id="option-list">
<h2><a class="toc-backref" href="#id71">5.20&nbsp;&nbsp;&nbsp;option list</a></h2>
<p><a class="reference external" href="../ref/rst/restructuredtext.html#option-lists">Option lists</a> are two-column lists of command-line options and
descriptions, documenting a program's options.</p>
<dl class="docutils">
<dt>Environment:</dt>
<dd><tt class="docutils literal">DUoptionlist</tt>: environment for option lists,</dd>
<dt>Command:</dt>
<dd><tt class="docutils literal">\DUoptionlistlabel</tt>: set appearance of the options</dd>
<dt>Example:</dt>
<dd><p class="first">set command options with a bold monospace font:</p>
<pre class="last literal-block">
\newcommand{\DUoptionlistlabel}{\texttt{\textbf{#1}} \hfill}
</pre>
</dd>
</dl>
</div>
<div class="section" id="page-breaks">
<h2><a class="toc-backref" href="#id72">5.21&nbsp;&nbsp;&nbsp;page breaks</a></h2>
<ul class="simple">
<li>Page breaks before top-level sections are the default with a
documentclass that provides &quot;chapters&quot;, e.g.  &quot;book&quot;, &quot;memoir&quot; or
&quot;scrbook&quot;.</li>
<li>Redefining the section or section* command in a
style sheet is possible too.</li>
<li><a class="reference internal" href="#raw-latex">Raw LaTeX</a> or a <a class="reference internal" href="#custom-role">custom role</a> can be used.</li>
<li>The transition element can be re-defined to produce a page break,</li>
</ul>
<dl class="docutils">
<dt>Commands</dt>
<dd><p class="first"><tt class="docutils literal">\newpage</tt>:  hard pagebreak at exactly this position</p>
<p class="last"><tt class="docutils literal">\pagebreak[2]</tt>: recommended page break after line end (precedence 1...4)</p>
</dd>
<dt>Example:</dt>
<dd><p class="first">Define the transition command as page break with the <a class="reference internal" href="#latex-code">LaTeX code</a>:</p>
<pre class="literal-block">
\newcommand*{\DUtransition}{\pagebreak[4]}
</pre>
<p class="last">(use <tt class="docutils literal">\renewcommand</tt> with <a class="reference internal" href="#raw-latex">raw LaTeX</a>).</p>
</dd>
</dl>
</div>
<div class="section" id="page-layout">
<h2><a class="toc-backref" href="#id73">5.22&nbsp;&nbsp;&nbsp;page layout</a></h2>
<p>By default, paper size and margin settings are determined by the document
class.</p>
<p>The following packages help to configure the page layout:</p>
<ol class="loweralpha">
<li><p class="first">The <a class="reference external" href="http://mirror.ctan.org/help/Catalogue/entries/typearea.html">typearea</a> package (part of the <a class="reference external" href="http://mirror.ctan.org/help/Catalogue/entries/koma-script.html">KOMA-script</a> bundle) calculates a
<em>good</em> page layout (based on rules and recommendations of typography
experts).</p>
<p>See the <a class="reference external" href="http://mirror.ctan.org/macros/latex/contrib/koma-script/scrguien.pdf">KOMA-Script Guide</a> for details on what is a <em>good</em> layout and
how this is achieved.</p>
</li>
<li><p class="first">The <a class="reference external" href="http://mirror.ctan.org/help/Catalogue/entries/geometry.html">geometry</a> package is recommended if you have to follow guidelines
with fixed values for the margins.
For details see the <a class="reference external" href="http://mirror.ctan.org/macros/latex/contrib/geometry/geometry.pdf">geometry manual</a>.</p>
</li>
</ol>
<dl class="docutils">
<dt>Example 1:</dt>
<dd><p class="first">Let <span class="incremental">typearea</span> determine the type area with <tt class="docutils literal">DIV=calc</tt> in the
documentoptions:</p>
<pre class="literal-block">
--documentoptions='a4paper,DIV=calc'
</pre>
<p class="last">The <tt class="docutils literal">DIV</tt> option can also be specified, like <tt class="docutils literal">DIV=10</tt>. It defines how
&quot;crowded&quot; a page will be: larger values mean larger text area (at the
expense of readability).</p>
</dd>
<dt>Example 2:</dt>
<dd><p class="first"><a class="reference internal" href="#latex-code">LaTeX code</a> to set margins with the <a class="reference external" href="http://mirror.ctan.org/help/Catalogue/entries/geometry.html">geometry</a> package:</p>
<pre class="last literal-block">
\usepackage{geometry}
\geometry{hmargin={3cm,0.8in},height=8in}
\geometry{height=10in}.
</pre>
</dd>
</dl>
</div>
<div class="section" id="page-headers-and-footers">
<h2><a class="toc-backref" href="#id74">5.23&nbsp;&nbsp;&nbsp;page headers and footers</a></h2>
<p>With the <a class="reference external" href="http://www.ctan.org/pkg/fancyhdr">fancyhdr</a> package or the <a class="reference external" href="http://mirror.ctan.org/help/Catalogue/entries/koma-script.html">KOMA-script</a> classes, you can define
custom page head- and foot-lines.</p>
<p>The <a class="reference external" href="../ref/rst/directives.html#header">&quot;header&quot; and &quot;footer&quot; directives</a> save their content in the macros
<tt class="docutils literal">\DUheader</tt> rsp. <tt class="docutils literal">\DUfooter</tt>. The macros can be used in LaTeX code and
will be replaced by LaTeX with the content of the directives.</p>
<dl class="docutils">
<dt>Example:</dt>
<dd><p class="first"><a class="reference internal" href="#latex-code">LaTeX code</a> to place left-aligned &quot;header&quot; and &quot;footer&quot; on every
page with <a class="reference external" href="http://www.ctan.org/pkg/fancyhdr">fancyhdr</a>:</p>
<pre class="last literal-block">
\usepackage{fancyhdr}
\fancyhead[L]{\DUheader}
\fancyfoot{} % reset
\fancyfoot[L]{\DUfooter}
\pagestyle{fancy}
</pre>
</dd>
</dl>
</div>
<div class="section" id="page-numbering">
<h2><a class="toc-backref" href="#id75">5.24&nbsp;&nbsp;&nbsp;page numbering</a></h2>
<dl class="docutils">
<dt>Example:</dt>
<dd><p class="first">Number pages by chapter (using the <a class="reference external" href="http://mirror.ctan.org/help/Catalogue/entries/chappg.html">chappg</a> package):</p>
<pre class="literal-block">
\usepackage{chappg}
</pre>
<p class="last">See the <a class="reference external" href="http://mirror.ctan.org/macros/latex/contrib/chappg/chappg.pdf">chappg documentation</a> for details.</p>
</dd>
</dl>
</div>
<div class="section" id="paper-size">
<h2><a class="toc-backref" href="#id76">5.25&nbsp;&nbsp;&nbsp;paper size</a></h2>
<p>Paper geometry can be changed using <tt class="docutils literal"><span class="pre">--documentoptions</span></tt> or with the
<a class="reference external" href="http://mirror.ctan.org/help/Catalogue/entries/geometry.html">geometry</a> package.</p>
<p><a class="reference internal" href="#latex-code">LaTeX code</a>:</p>
<pre class="literal-block">
\usepackage{geometry}
\geometry{OPTIONLIST}
</pre>
<dl class="docutils">
<dt>Default:</dt>
<dd>a4paper</dd>
</dl>
<p>Some possibilities:</p>
<ul class="simple">
<li>a4paper, b3paper, letterpaper, executivepaper, legalpaper</li>
<li>landscape, portrait, twoside.</li>
</ul>
<dl class="docutils">
<dt>Example:</dt>
<dd><p class="first">Choose A5 pager in landscape orientation with command line argument:</p>
<pre class="literal-block">
--documentoptions=a5paper,landscape
</pre>
<p>The same with LaTeX commands in the <a class="reference internal" href="#style-sheet">style sheet</a>:</p>
<pre class="literal-block">
\usepackage{geometry}
\geometry{a5paper,landscape}
</pre>
<p class="last">For details see the <a class="reference external" href="http://mirror.ctan.org/macros/latex/contrib/geometry/geometry.pdf">geometry manual</a>.</p>
</dd>
</dl>
</div>
<div class="section" id="paragraph-indent">
<h2><a class="toc-backref" href="#id77">5.26&nbsp;&nbsp;&nbsp;paragraph indent</a></h2>
<dl class="docutils">
<dt>Default (in most document classes):</dt>
<dd>Indent the first line in a paragraph unless it is the first line of a
chapter, section, subsection, or subsubsection.</dd>
<dt>Example:</dt>
<dd><p class="first">To set paragraph indentation to zero but add a vertical space between
load the <span class="incremental">parskip</span> package with the command line argument:</p>
<pre class="literal-block">
--stylesheet=parskip
</pre>
<p>or in a custom <a class="reference internal" href="#style-sheet">style sheet</a> with:</p>
<pre class="last literal-block">
\usepackage{parskip}
</pre>
</dd>
</dl>
</div>
<div class="section" id="rubric">
<h2><a class="toc-backref" href="#id78">5.27&nbsp;&nbsp;&nbsp;rubric</a></h2>
<p>A <a class="reference external" href="../ref/rst/directives.html#rubric">rubric</a> is like an informal heading that doesn't correspond to the
document's structure.</p>
<dl class="docutils">
<dt>Command:</dt>
<dd><tt class="docutils literal">\DUrubric</tt></dd>
<dt>Default:</dt>
<dd>subsubsection style, italic, centred</dd>
<dt>Example:</dt>
<dd><p class="first">set flushleft and red:</p>
<pre class="last literal-block">
\newcommand*{\DUrubric}[2][class-arg]{%
   \subsubsection*{{\color{red}#1}\hfill}}
</pre>
</dd>
</dl>
</div>
<div class="section" id="section-numbering">
<h2><a class="toc-backref" href="#id79">5.28&nbsp;&nbsp;&nbsp;section numbering</a></h2>
<p>Sections are numbered if there is a <a class="reference external" href="../ref/rst/directives.html#sectnum">sectnum directive</a> in the document.</p>
<dl class="docutils">
<dt>Option: <a class="reference external" href="config.html#sectnum-xform">sectnum_xform</a></dt>
<dd><tt class="docutils literal"><span class="pre">--section-numbering</span></tt>, <tt class="docutils literal"><span class="pre">--no-section-numbering</span></tt></dd>
</dl>
<p>If <a class="reference external" href="config.html#sectnum-xform">sectnum_xform</a> is False, section numbers are generated by LaTeX. In this
case the &quot;prefix&quot; and &quot;suffix&quot; arguments of the <a class="reference external" href="../ref/rst/directives.html#sectnum">sectnum directive</a> are
ignored. The section number style is determined by the <a class="reference internal" href="#document-class">document class</a>
and can be configured in a LaTeX <a class="reference internal" href="#style-sheet">style sheet</a>, e.g.:</p>
<pre class="literal-block">
\setcounter{secnumdepth}{5}
</pre>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">The LaTeX name is 'secnumdepth' (whithout 't').</p>
</div>
</div>
<div class="section" id="sidebar">
<h2><a class="toc-backref" href="#id80">5.29&nbsp;&nbsp;&nbsp;sidebar</a></h2>
<p><a class="reference external" href="http://docutils.sf.net/docutils/docs/ref/rst/directives.html#sidebar">Sidebars</a> are like miniature, parallel documents that occur inside other
documents, providing related or reference material. They can be likened to
super-footnotes; their content is outside of the flow of the document's main
text.</p>
<dl class="docutils">
<dt>Command:</dt>
<dd><tt class="docutils literal">DUsidebar</tt></dd>
<dt>Default:</dt>
<dd>Box with grey background.</dd>
<dt>Example 1:</dt>
<dd><p class="first">Less space before the title:</p>
<pre class="last literal-block">
\providecommand{\DUsidebar}[2]{%
    \begin{center}
      \colorbox[gray]{0.90}{\parbox{0.9\textwidth}{%
        \smallskip\textbf{#1}\smallskip
        #2}}
    \end{center}
}
</pre>
</dd>
<dt>Example 2:</dt>
<dd><p class="first">Use margin notes:</p>
<pre class="literal-block">
\newcommand{\DUsidebar}[2]{\marginpar{\flushleft \textbf{#1} #2}}
</pre>
<ul class="last simple">
<li>Make sure the margin is wide enough to hold the note.</li>
<li>This fails with some constructs inside the <span class="incremental">side bar</span> and where
marginpar cannot be used, e.g., inside floats, footnotes, or in frames
made with the framed package (see <a class="reference external" href="http://mirror.ctan.org/help/Catalogue/entries/marginnote.html">marginnote</a>).</li>
</ul>
</dd>
</dl>
</div>
<div class="section" id="size-of-a-pixel">
<h2><a class="toc-backref" href="#id81">5.30&nbsp;&nbsp;&nbsp;size of a pixel</a></h2>
<p>The length unit <tt class="docutils literal">px</tt> is a &quot;relative length&quot; whose value depends on the
<em>resolution</em> of the output device (usually specified in <em>dots per inch</em>
(DPI). However, when producing a PDF, the resolution of the output device
(printer, screen (for PDF-viewer)) is generally not known.</p>
<p>With pdftex, the &quot;resolution&quot; is a configuration setting.</p>
<dl class="docutils">
<dt>Default:</dt>
<dd>72&nbsp;DPI, i.e. 1&nbsp;px&nbsp;=&nbsp;1/72&nbsp;in.</dd>
<dt>Example:</dt>
<dd><p class="first">Set a resolution of 96 DPI with the <a class="reference internal" href="#latex-code">LaTeX code</a>:</p>
<pre class="last literal-block">
\pdfpxdimen=1in % 1 DPI
\divide\pdfpxdimen by 96 % 96 DPI
</pre>
</dd>
</dl>
</div>
<div class="section" id="topic-element">
<h2><a class="toc-backref" href="#id82">5.31&nbsp;&nbsp;&nbsp;topic element</a></h2>
<p>A <a class="reference external" href="../ref/rst/directives.html#topic">topic</a> is like a block quote with a title, or a self-contained section with
no subsections.</p>
<p>Topics and rubrics can be used at places where a <a class="reference external" href="../ref/rst/restructuredtext.html#sections">section title</a> is not
allowed (e.g. inside a directive).</p>
<dl class="docutils">
<dt>Command:</dt>
<dd><tt class="docutils literal">DUtopic</tt></dd>
<dt>Default:</dt>
<dd>&quot;quote&quot; environment</dd>
<dt>Example 1:</dt>
<dd><p class="first">If you generally prefer a &quot;normal&quot; section over a block quote, define:</p>
<pre class="last literal-block">
\newcommand{\DUtopic}[2][class-arg]{%
  \ifcsname DUtopic#1\endcsname%
    \csname DUtopic#1\endcsname{#2}%
  \else
    #2
  \fi
}
</pre>
</dd>
<dt>Example 2:</dt>
<dd><p class="first">If you want a &quot;normal&quot; section for topics with class argument &quot;noquote&quot;,
define:</p>
<pre class="last literal-block">
\newcommand{\DUtopicnoquote}[1]{#1}
</pre>
</dd>
</dl>
</div>
<div class="section" id="topic-title">
<h2><a class="toc-backref" href="#id83">5.32&nbsp;&nbsp;&nbsp;topic title</a></h2>
<p>The titles of <a class="reference internal" href="#admonitions">admonitions</a>, <a class="reference internal" href="#sidebar">sidebar</a>, and <a class="reference internal" href="#topic-element">topic element</a> are defined with
the <tt class="docutils literal">\DUtitle</tt> command that also takes a &quot;class&quot; argument.</p>
<dl class="docutils">
<dt>Example 1:</dt>
<dd><p class="first">a centered and somewhat larger title for topcis:</p>
<pre class="last literal-block">
\newcommand*{\DUtitletopic}[1]{\subsection*{\centering #1}
</pre>
</dd>
<dt>Example 2:</dt>
<dd><p class="first">a right-pointing hand as title for the &quot;attention&quot; directive:</p>
<pre class="literal-block">
\usepackage{pifont}
\newcommand{\DUtitleattention}[1]{\ding{43}}
</pre>
<p>The title argument is &quot;swallowed&quot; by the command.
To have both, hand and title use:</p>
<pre class="last literal-block">
\usepackage{pifont}
\newcommand{\DUtitleattention}[1]{\ding{43} #1}
</pre>
</dd>
</dl>
</div>
<div class="section" id="table-of-contents">
<h2><a class="toc-backref" href="#id84">5.33&nbsp;&nbsp;&nbsp;table of contents</a></h2>
<p>A <a class="reference external" href="../ref/rst/directives.html#contents">contents directive</a> is replaced by a table of contents (ToC).</p>
<dl class="docutils">
<dt>Option: <a class="reference external" href="config.html#use-latex-toc">use-latex-toc</a></dt>
<dd><tt class="docutils literal"><span class="pre">--use-latex-toc</span></tt>, <tt class="docutils literal"><span class="pre">--use-docutils-toc</span></tt></dd>
</dl>
<p>With use-latex-toc (default since release 0.6):</p>
<ul>
<li><p class="first">The ToC is generated by LaTeX (via the <tt class="docutils literal">\tableofcontents</tt> command).</p>
<p>The layout depends on the choosen document class and can be configured in
a custom <a class="reference internal" href="#style-sheet">style sheet</a> (see e.g. the <a class="reference external" href="http://mirror.ctan.org/macros/latex/contrib/koma-script/scrguien.pdf">KOMA-Script Guide</a> for the
<a class="reference external" href="http://mirror.ctan.org/help/Catalogue/entries/koma-script.html">KOMA-script</a> classes).</p>
</li>
<li><p class="first">The depth of the ToC and PDF-bookmarks can be configured</p>
<ul class="simple">
<li>with the &quot;depth&quot; argument of the <a class="reference external" href="../ref/rst/directives.html#contents">contents directive</a>, or</li>
<li>in a style sheet with e.g. <tt class="docutils literal"><span class="pre">\setcounter{tocdepth}{5}</span></tt>.</li>
</ul>
</li>
<li><p class="first">Local ToCs are done with the <a class="reference external" href="http://mirror.ctan.org/help/Catalogue/entries/minitoc.html">minitoc</a> package. See the <a class="reference external" href="http://mirror.ctan.org/macros/latex/contrib/minitoc/minitoc.pdf">minitoc
documentation</a> for the numerous configuration options.</p>
</li>
</ul>
<div class="note">
<p class="first admonition-title">Note</p>
<p>Minitoc supports local ToCs only at &quot;part&quot; and top section level
(&quot;chapter&quot; or &quot;section&quot;). Local <span class="incremental">contents</span> directives at lower levels
are ignored (a warning is issued).</p>
<p class="last">This is an intended feature of the <a class="reference external" href="http://mirror.ctan.org/help/Catalogue/entries/minitoc.html">minitoc</a> package. If you really
require local ToCs at lower level, turn off the <a class="reference external" href="config.html#use-latex-toc">use-latex-toc</a> option.</p>
</div>
</div>
<div class="section" id="title-reference-role">
<h2><a class="toc-backref" href="#id85">5.34&nbsp;&nbsp;&nbsp;title reference role</a></h2>
<p><a class="reference external" href="../ref/rst/roles.html#title-reference">Title reference</a> is the default <a class="reference external" href="../ref/rst/directives.html#setting-the-default-interpreted-text-role">default role</a> for <a class="reference external" href="../ref/rst/restructuredtext.html#interpreted-text">interpreted text</a>.</p>
<dl class="docutils">
<dt>Command:</dt>
<dd><tt class="docutils literal">\DUroletitlereference</tt></dd>
<dt>Default:</dt>
<dd>use slanted font (<tt class="docutils literal">\textsl</tt>)</dd>
<dt>Example:</dt>
<dd><p class="first">set title references with a bold monospace font:</p>
<pre class="last literal-block">
\newcommand{\DUroletitlereference}[1]{\texttt{\textbf{#1}}}
</pre>
</dd>
</dl>
</div>
<div class="section" id="text-encoding">
<h2><a class="toc-backref" href="#id86">5.35&nbsp;&nbsp;&nbsp;text encoding</a></h2>
<p>The encoding of the LaTeX source file is Docutils' <em>output</em> encoding
but LaTeX' <em>input</em> encoding.</p>
<dl class="docutils">
<dt>Option: <a class="reference external" href="config.html#output-encoding">output-encoding</a></dt>
<dd><tt class="docutils literal"><span class="pre">--output-encoding=OUTPUT-ENCODING</span></tt></dd>
<dt>Default:</dt>
<dd>&quot;utf8&quot;</dd>
<dt>Example:</dt>
<dd><p class="first">Encode the LaTeX source file with the ISO <span class="incremental">latin-1</span> (west european)
8-bit encoding (the default in Docutils versions up to 0.6.):</p>
<pre class="last literal-block">
--output-encoding=latin-1
</pre>
</dd>
<dt>Note:</dt>
<dd><p class="first">LaTeX comes with two options for UTF-8 support,</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">utf8:</th><td class="field-body">by the standard <a class="reference external" href="http://mirror.ctan.org/help/Catalogue/entries/inputenc.html">inputenc</a> package with only limited coverage
(mainly accented characters).</td>
</tr>
<tr class="field"><th class="field-name">utf8x:</th><td class="field-body">supported by the <a class="reference external" href="http://mirror.ctan.org/help/Catalogue/entries/unicode.html">ucs</a> package covers a wider range of Unicode
characters than does &quot;utf8&quot;.  It is, however, a non-standard
extension and no longer developed.</td>
</tr>
</tbody>
</table>
<p class="last">Currently (in version 0.6), &quot;utf8&quot; is used if the output-encoding is
any of &quot;utf_8&quot;, &quot;U8&quot;, &quot;UTF&quot;, or &quot;utf8&quot;.</p>
</dd>
</dl>
<!-- with utf8x:
If LaTeX issues a Warning about unloaded/unknown characters adding ::

  \PreloadUnicodePage{n}

(where *n* is the Unicode page-number) to the style sheet might help. -->
</div>
<div class="section" id="transition-element">
<h2><a class="toc-backref" href="#id87">5.36&nbsp;&nbsp;&nbsp;transition element</a></h2>
<p><a class="reference external" href="http://docutils.sf.net/docutils/docs/ref/rst/restructuredtext.html#transitions">Transitions</a> are commonly seen in novels and short fiction, as a gap
spanning one or more lines, marking text divisions or signaling changes in
subject, time, point of view, or emphasis.</p>
<dl class="docutils">
<dt>Command:</dt>
<dd><tt class="docutils literal">\DUtransition</tt></dd>
<dt>Default:</dt>
<dd>A horizontal line, 1/3 of text width</dd>
<dt>Example 1:</dt>
<dd><p class="first">Use three stars:</p>
<pre class="literal-block">
\newcommand*{\DUtransition}[1][class-arg]{\centering{}*\quad*\quad*}
</pre>
<p class="last">Alternatively use the more elaborated version in <a class="reference external" href="../../../sandbox/stylesheets/transition-stars.sty">transition-stars.sty</a>.</p>
</dd>
<dt>Example 2:</dt>
<dd><p class="first">If paragraphs are separated by indentation, you can simply use a vertical
space:</p>
<pre class="last literal-block">
\newcommand*{\DUtransition}[1][class-arg]{\vspace{2ex}}
</pre>
</dd>
</dl>
</div>
</div>
<div class="section" id="changes">
<h1><a class="toc-backref" href="#id88">6&nbsp;&nbsp;&nbsp;Changes</a></h1>
<ul class="simple">
<li>The Docutils <a class="reference external" href="../../HISTORY.html">HISTORY</a> lists all changes during the history of docutils.</li>
<li>Changes since release (0.5) are summarized in the <a class="reference external" href="../../RELEASE-NOTES.html">RELEASE-NOTES</a>
and explained in detail in <a class="reference external" href="docutils-05-compat.sty.html">docutils-05-compat</a>.</li>
<li><a class="reference external" href="../../docutils/writers/latex2e/docutils-05-compat.sty">docutils-05-compat.sty</a> is a <a class="reference internal" href="#style-sheet">style sheet</a> that provides best possible
backwards compatibility.</li>
</ul>
</div>
<div class="section" id="problems">
<h1><a class="toc-backref" href="#id89">7&nbsp;&nbsp;&nbsp;Problems</a></h1>
<div class="section" id="troubleshooting">
<h2><a class="toc-backref" href="#id90">7.1&nbsp;&nbsp;&nbsp;Troubleshooting</a></h2>
<div class="section" id="bad-looking-pdf-output">
<h3><a class="toc-backref" href="#id91">7.1.1&nbsp;&nbsp;&nbsp;Bad looking PDF output</a></h3>
<blockquote>
<p>What I am looking for when I try Docutils is if the PDF files I can get
are of high quality. Unfortunaltely that never is the case.</p>
<p>So am I just stupid or is there a way to get really high quality pdf from
Docutils?</p>
</blockquote>
<p>Make sure the default font is not a bitmap font.</p>
<p>There is <a class="reference external" href="http://mirror.ctan.org/help/Catalogue/entries/lm.html">Latin Modern</a> if you like the look of the standard font on paper,
but want nice pdf. Or select something else like Times, Palatino, ... via
configuration <a class="reference internal" href="#options">options</a> to the Docutils tool. See <a class="reference internal" href="#font">font</a> and <a class="reference external" href="config.html#font-encoding">font-encoding</a>.</p>
</div>
<div class="section" id="footnote-mark-and-text-at-different-pages">
<h3><a class="toc-backref" href="#id92">7.1.2&nbsp;&nbsp;&nbsp;footnote mark and text at different pages</a></h3>
<p>Docutils stores the footnote text in a separate node, at the position where
it is specified in the input document. With the default settings, the
footnote is put at the bottom of the page where the footnote text is located,
maybe far away from the footnote mark (see e.g. <a class="reference external" href="rst/demo.txt">rst/demo.txt</a>).</p>
<p>To get footnote mark and text at the same page, keep footnote mark and
footnote text close together!</p>
</div>
<div class="section" id="non-breaking-hyperlinks">
<h3><a class="toc-backref" href="#id93">7.1.3&nbsp;&nbsp;&nbsp;non-breaking hyperlinks</a></h3>
<p>If you convert with <tt class="docutils literal">latex</tt> (as opposed to <tt class="docutils literal">pdflatex</tt>), hyperlinks will
not wrap and sometimes stick into the margin.</p>
<dl class="docutils">
<dt>Wrong:</dt>
<dd><pre class="first literal-block">
\usepackage[breaklinks=true]{hyperref}
</pre>
<p class="last">&quot;breaklinks&quot; is an internal option that indicates whether the chosen
driver can handle split links. (It might work to <em>disable</em> link breaking.)</p>
</dd>
<dt>Right:</dt>
<dd><p class="first">Use one of the following:</p>
<ol class="last loweralpha simple">
<li>compile with <a class="reference internal" href="#pdflatex">pdflatex</a>,</li>
<li>compile with <a class="reference internal" href="#latex-dvipdfmx">latex + dvipdfmx</a>,</li>
<li>use the package <a class="reference external" href="http://mirror.ctan.org/help/Catalogue/entries/breakurl.html">breakurl</a>,</li>
<li>(for printout) <a class="reference internal" href="#disable-hyperlinks">disable hyperlinks</a> using the package &quot;nohyperref&quot;.</li>
</ol>
</dd>
</dl>
<p>See also the <a class="reference external" href="http://www.tex.ac.uk/cgi-bin/texfaq2html?label=breaklinks">Link text doesn’t break at end line</a> FAQ entry.</p>
</div>
<div class="section" id="glyph-not-defined-in-pd1-encoding">
<h3><a class="toc-backref" href="#id94">7.1.4&nbsp;&nbsp;&nbsp;Glyph not defined in PD1 encoding</a></h3>
<p>If a section title or other link contains non-Latin (e.g. Cyrillic)
characters, the LaTeX log contains lots of warnings like:</p>
<pre class="literal-block">
Package hyperref Warning: Glyph not defined in PD1 encoding,
(hyperref)                removing `\CYRZ' on input line 6.
...
</pre>
<p>This can be solved with the &quot;unicode&quot; <a class="reference external" href="config.html#stylesheet-latex2e-writer">hyperref_option</a> setting:</p>
<pre class="literal-block">
--hyperref-option=unicode
</pre>
<p>(works also with non-unicode input/output encoding (e.g. &quot;koi8r&quot; or
&quot;latin1&quot;). Newer versions of hyperref default to &quot;unicode=true&quot; if the
document language is &quot;russian&quot;.</p>
<p>However, this setting leads to &quot;strange&quot; characters in the bookmarks
if used with <a class="reference internal" href="#xelatex">xelatex</a> in hyperref versions before v6.79g (2009/11/20).
(cf <a class="reference external" href="http://sourceforge.net/tracker/?func=detail&amp;aid=3100778&amp;group_id=38414&amp;atid=422030">bugreport 3100778</a>).</p>
<p>If updating the hyperref package is not an option, the workaround is
to set</p>
<pre class="literal-block">
--hyperref-option=&quot;unicode=false&quot;
</pre>
<p>or (in the config file):</p>
<pre class="literal-block">
[xetex writer]

hyperref-option: unicode=false
</pre>
</div>
<div class="section" id="image-inclusion">
<h3><a class="toc-backref" href="#id95">7.1.5&nbsp;&nbsp;&nbsp;image inclusion</a></h3>
<p><a class="reference external" href="../ref/rst/directives.html#images">Images</a> are included in LaTeX with the help of the <span class="incremental">graphicx</span> package. The
supported file formats depend on the used driver:</p>
<ul class="simple">
<li>Standard <a class="reference internal" href="#id6">latex</a> can include <strong>only EPS</strong> graphics, no other format.</li>
<li><a class="reference internal" href="#latex-dvipdfmx">latex + dvipdfmx</a> works with EPS and JPG (add 'dvipdfmx' to the
<a class="reference external" href="config.html#documentoptions">documentoptions</a> and 'bmpsize' to the <a class="reference external" href="config.html#stylesheet-latex2e-writer">stylesheet</a> setting).</li>
<li><a class="reference internal" href="#pdflatex">pdflatex</a> and <a class="reference internal" href="#xelatex">xelatex</a> work with PNG, JPG, or PDF, but <strong>not EPS</strong>.</li>
</ul>
<p>If PDF-image inclusion in PDF files fails, specifying
<tt class="docutils literal"><span class="pre">--graphicx-option=pdftex</span></tt> or <tt class="docutils literal"><span class="pre">--graphicx-option=auto</span></tt> might help.</p>
<p>For details see <a class="reference external" href="http://mirror.ctan.org/macros/latex/required/graphics/grfguide.pdf">grfguide.pdf</a>.</p>
<p>The <a class="reference internal" href="#rubber">Rubber</a> wrapper can be used for automatic image conversion.</p>
<p>Docutils expects an URI as pointer to the image file. The latex writer
transforms this URI to a local path. By default, LaTeX does not accept
spaces and more than one dot in the filename. If using &quot;traditional&quot;
filenames is not an option, the adding <a class="reference external" href="http://mirror.ctan.org/help/Catalogue/entries/grffile.html">grffile</a> to the <a class="reference internal" href="#style-sheets">style sheets</a>
can help.</p>
</div>
<div class="section" id="why-are-my-images-too-big">
<h3><a class="toc-backref" href="#id96">7.1.6&nbsp;&nbsp;&nbsp;Why are my images too big?</a></h3>
<p>HTML-browsers use the actual screen resolution (usually around
100&nbsp;DPI).</p>
<p>The CSS specification suggests:</p>
<blockquote>
<p>It is recommended that the reference pixel be the visual angle of one
pixel on a device with a pixel density of 96&nbsp;DPI and a distance from the
reader of an arm's length.</p>
<p class="attribution">&mdash;<a class="reference external" href="http://www.w3.org/TR/CSS2/syndata.html#length-units">http://www.w3.org/TR/CSS2/syndata.html#length-units</a></p>
</blockquote>
<p>This is why pixmap images without size specification or objects with a size
specified in <tt class="docutils literal">px</tt> tend to come too large in the PDF.</p>
<dl class="docutils">
<dt>Solution:</dt>
<dd>Specify the image size in fixed units (<tt class="docutils literal">pt</tt>, <tt class="docutils literal">cm</tt>, <tt class="docutils literal">in</tt>) or
configure the <a class="reference internal" href="#size-of-a-pixel">size of a pixel</a> (length unit px).</dd>
</dl>
</div>
<div class="section" id="error-illegal-unit-px">
<h3><a class="toc-backref" href="#id97">7.1.7&nbsp;&nbsp;&nbsp;Error <tt class="docutils literal">illegal unit px</tt></a></h3>
<p>If you convert the LaTeX source with a legacy program, you might get this
error.</p>
<p>The unit &quot;px&quot; was introduced by the <span class="incremental">pdfTeX</span> converter on 2005-02-04.
<span class="incremental">pdfTeX</span> is used also for conversion into DVI format in all modern LaTeX
distributions (since ca. 2006).</p>
<p>If updating LaTeX is not an option, just remove the &quot;px&quot; from the length
specification. HTML/CSS will default to &quot;px&quot; while the <span class="incremental">latexe2</span> writer
will add the fallback unit &quot;bp&quot;.</p>
</div>
<div class="section" id="error-symbol-textcurrency-not-provided">
<h3><a class="toc-backref" href="#id98">7.1.8&nbsp;&nbsp;&nbsp;Error <tt class="docutils literal">Symbol \textcurrency not provided</tt> ...</a></h3>
<p>The currency sign (\u00a4) is not supported by all fonts (some have
an Euro sign at its place). You might see an error like:</p>
<pre class="literal-block">
! Package textcomp Error: Symbol \textcurrency not provided by
(textcomp)                font family ptm in TS1 encoding.
(textcomp)                Default family used instead.
</pre>
<p>(which in case of font family &quot;ptm&quot; is a false positive). Add either</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">warn:</th><td class="field-body">turn the error in a warning, use the default symbol (bitmap), or</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">force,almostfull:</th></tr>
<tr class="field"><td>&nbsp;</td><td class="field-body">use the symbol provided by the font at the users
risk,</td>
</tr>
</tbody>
</table>
<p>to the document options or use a different font package.</p>
</div>
<div class="section" id="search-and-text-extraction">
<h3><a class="toc-backref" href="#id99">7.1.9&nbsp;&nbsp;&nbsp;Search and text extraction</a></h3>
<p>Search for text that contains characters outside the ASCII range (e.g.
umlauts) might fail.  See <a class="reference internal" href="#font">font</a> and <a class="reference internal" href="#font-encoding">font encoding</a> (as well as
<a class="reference external" href="http://www.tex.ac.uk/cgi-bin/texfaq2html?label=srchpdf">Searching PDF files</a> for background information).</p>
</div>
<div class="section" id="unicode-box-drawing-and-block-characters">
<h3><a class="toc-backref" href="#id100">7.1.10&nbsp;&nbsp;&nbsp;Unicode box drawing and block characters</a></h3>
<p>The easiest solution is to use <a class="reference internal" href="#xelatex">xelatex</a> for <a class="reference internal" href="#pdf-generation">PDF generation</a>.</p>
<p>With &quot;traditional&quot; TeX engines (e.g. <a class="reference internal" href="#pdflatex">pdflatex</a>):</p>
<ul class="simple">
<li>Generate LaTeX code with <a class="reference external" href="config.html#output-encoding">output-encoding</a> &quot;utf-8&quot;.</li>
<li>Add the <a class="reference external" href="http://mirror.ctan.org/help/Catalogue/entries/pmboxdraw.html">pmboxdraw</a> package to the <a class="reference internal" href="#style-sheets">style sheets</a>.
(For shaded boxes also add the <span class="incremental">color</span> package.)</li>
</ul>
<p>Unfortunately, this defines only a subset of the characters
(see <a class="reference external" href="http://mirror.ctan.org/macros/latex/contrib/oberdiek/pmboxdraw.pdf">pmboxdraw.pdf</a> for a list).</p>
</div>
</div>
<div class="section" id="bugs-and-open-issues">
<h2><a class="toc-backref" href="#id101">7.2&nbsp;&nbsp;&nbsp;Bugs and open issues</a></h2>
<p>Open to be fixed or open to discussion.</p>
<p>See also the entries in the <a class="reference external" href="../dev/todo.html#latex-writer">Docutils TODO list</a>,
the <a class="reference external" href="../../BUGS.html">BUGS</a> documentation and the <a class="reference external" href="http://sourceforge.net/tracker/?group_id=38414&amp;atid=422030">SourceForge Bug Tracker</a>.</p>
<div class="section" id="footnotes-and-citations">
<h3><a class="toc-backref" href="#id102">7.2.1&nbsp;&nbsp;&nbsp;Footnotes and citations</a></h3>
<p>Initially both were implemented using figure floats, because hyperlinking
back and forth seemed to be impossible. Later the <span class="incremental">figure</span> directive was
added that puts images into figure floats.</p>
<p>This results in footnotes, citations, and figures possibly being mixed at
page foot.</p>
<dl class="docutils">
<dt>Workaround:</dt>
<dd>Select footnote and citation handling with the <a class="reference external" href="config.html#docutils-footnotes">docutils-footnotes</a> and
<a class="reference external" href="config.html#use-latex-citations">use-latex-citations</a> options.</dd>
</dl>
<p>If <tt class="docutils literal"><span class="pre">use-latex-citations</span></tt> is used, a bibliography is inserted right at
the end of the document. <em>This should be customizable</em>.</p>
<p>If <tt class="docutils literal"><span class="pre">use-latex-citations</span></tt> is used adjacent citation references (separated
only by a single space or a newline) are combined to a single citation
group, i.e. <tt class="docutils literal">[cite1]_ [cite2]_</tt> results in <tt class="docutils literal">\cite{cite1,cite2}</tt>.
The appearance in the output can be configured in a <a class="reference internal" href="#style-sheet">style sheet</a>.</p>
</div>
<div class="section" id="tables">
<h3><a class="toc-backref" href="#id103">7.2.2&nbsp;&nbsp;&nbsp;Tables</a></h3>
<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">Tablewidth:</th><td class="field-body"><p class="first">reST-documents line length is assumed to be 80 characters. The
tablewidth is set relative to this value. If someone produces
documents with line length of 132 this will fail.</p>
<p class="last">Table width is tried to fit in page even if it is wider than
the assumed linewidth, still assumed linewidth is a hook.</p>
</td>
</tr>
</tbody>
</table>
<ul class="simple">
<li>Table: multicol cells are always left aligned.</li>
<li>The contents of a rowspan cell do not influence table height.
(multirow &quot;feature&quot;, use a phantom or strut?)</li>
<li>Multirow cells might mix up the following table rows.</li>
<li>Table cells with both multirow and multicolumn are currently not possible.</li>
<li>literal-blocks in table cells:<ul>
<li>If verbatim or flushleft is used one gets vertical space above and below.</li>
<li>This is bad for the topmost paragraph in a cell, therefore the writer
uses raggedright.</li>
<li>Ragged right fails on followup paragraphs as the vertical space would be
missing.</li>
</ul>
</li>
<li><tt class="docutils literal"><span class="pre">--table-style=booktabs</span></tt>, <tt class="docutils literal">..class:: booktab</tt>: <span class="incremental">booktabs</span> version
1.00 does not work with <span class="incremental">longtable</span>. This is solved in newer versions
(current is 2005/04/14 v1.61803).</li>
</ul>
</div>
<div class="section" id="id35">
<h3><a class="toc-backref" href="#id104">7.2.3&nbsp;&nbsp;&nbsp;Figures</a></h3>
<ul class="simple">
<li>Figures are always as wide as the containing text. The &quot;figwidth&quot; argument
is currently not supported. As a consequence, the &quot;align&quot; argument has no
effect.</li>
<li>Wrapping text around figures is currently not supported. (Requires the
<a class="reference external" href="http://mirror.ctan.org/help/Catalogue/entries/wrapfig.html">wrapfig</a> package.)</li>
</ul>
</div>
<div class="section" id="miscellaneous">
<h3><a class="toc-backref" href="#id105">7.2.4&nbsp;&nbsp;&nbsp;Miscellaneous</a></h3>
<ul class="simple">
<li>Pdfbookmark level 4 (and greater) does not work (might be settable but
complicated).</li>
<li>Hyperlinks are not hyphenated; this leads to bad spacing. See
docs/user/rst/demo.txt 2.14 directives.</li>
<li>Pagestyle headings does not work, when sections are starred. Use LaTeX for
the section numbering with the <a class="reference internal" href="#options">options</a> <tt class="docutils literal"><span class="pre">--no-section-numbers</span></tt>
(command line) or <tt class="docutils literal">sectnum_xform: False</tt> (config file).</li>
</ul>
</div>
</div>
</div>
</div>
</body>
</html>